People Features and Flows

The people domain is the school's roll: every pupil, every parent or other responsible adult, and everyone on the payroll. One record shape underlies all three — a users row carrying name, contact, demographics and address, plus one profile row (students, guardians, or staff) carrying whatever is specific to that hat. A person who is both a teacher and a parent is two profile rows pointing at the same users row, not two people.

1. Documentation Evidence

2. Feature Summary

3. Actor Matrix

Scope is decided by the session's active role, never by the union of every role a person holds. A teacher who is also a parent, viewing as Guardian, gets the guardian scope — switching context is what makes that mean anything. See PeopleAccessService.scopeFor in the backend doc.

4. Capability Matrix

5. User-Facing Flows

5.1 Admit a student

Summary

The admissions desk records a new pupil: identity, admission details, and at least one guardian — either reusing an existing parent (the sibling case) or creating one inline.

Preconditions

• Actor authenticated, active role holding Students_CREATE.
• If guardians are linked by guardianId, those guardian rows must already exist and be live.
• If a person.email is supplied for the student or an inline guardian, it must not already belong to a live person.

Main Flow

Sequence Diagram

Branches and Edge Cases

5.2 Attach a sibling to an existing guardian

Summary

The admissions desk searches by phone number before typing a name, so the second child of a family shares the first child's guardian row rather than creating a duplicate parent.

Preconditions

• Actor holds Guardians_READ (for the lookup) and Students_CREATE or Students_UPDATE/Guardians_UPDATE (to attach).

Main Flow

Sequence Diagram

Branches and Edge Cases

5.3 Update a student, guardian, or staff member

Summary

An office edits identity or profile fields on an existing record. Students carry optimistic concurrency; guardians and staff do not.

Preconditions

• Actor holds the entity's _UPDATE permission and passes PeopleAccessService.assertCanAccess for that specific row.
• For a student or a staff member, the request must carry the version token last read from the record.

Main Flow

Sequence Diagram

Branches and Edge Cases

5.4 Replace a student's guardian set

Summary

The office corrects the whole family picture at once — who is primary, who may collect the child, who is the emergency contact — rather than adding and removing links one at a time.

Preconditions

• Actor holds Students_UPDATE and Guardians_UPDATE.
• If any guardians are given, exactly one must be marked primary.

Main Flow

Sequence Diagram

Branches and Edge Cases

5.5 Read a student's health record or a staff member's salary

Summary

Two fields groups are held out of the base record and gated by their own permission, so a teacher reading the roll never incidentally reads a diagnosis, and a colleague with plain Staff_READ never incidentally reads a payslip.

Preconditions

• Actor passes PeopleAccessService.assertCanAccess for the base entity, and holds StudentMedical_READ/_UPDATE or StaffSalary_READ/_UPDATE respectively.

Main Flow

Sequence Diagram

Branches and Edge Cases

5.6 Suspend and restore a person's sign-in (students, guardians, staff)

Summary

An office can stop somebody signing in without touching their record — a fee-suspended pupil stays on the roll and countable, a suspended parent is still the emergency contact on file, and a staff member under investigation stays employed on paper while locked out of a session.

Preconditions

• Actor holds the entity's _UPDATE permission.
• The target must not be the actor themselves.
• If the target holds the superadmin role, the actor must hold it too — an ordinary administrator cannot suspend, restore, or reset a superadmin's credentials no matter which entity's _UPDATE permission they hold.

Main Flow

Sequence Diagram

Branches and Edge Cases

5.7 Email a password-reset link

Summary

An administrator triggers a reset link, never a new password — the office never learns a child's or colleague's credential.

Preconditions

• Actor holds the entity's _UPDATE permission.
• If the target holds the superadmin role, the actor must hold it too.
• Target has an email address, canLogin = true, and is not banned.

Main Flow

Sequence Diagram

Branches and Edge Cases

5.8 Give somebody a portal account, or take it away (students, guardians, staff)

Summary

An administrator turns sign-in access on for a person who has a record but no login, and the person receives an email inviting them to choose a password. The same screen turns it off again, ending every session they hold.

Preconditions

• The actor holds Users_UPDATE — not the profile-kind permission. Granting sign-in creates a credential-bearing account rather than editing a pupil, parent or employee record.
• The target is a live person within the actor's scope.
• The target does not hold the superadmin role unless the actor does too.

Main Flow

Revoking is the same route with DELETE, no body: can_login goes to false under the same guard, and every session the person holds is deleted.

Branches and Edge Cases

An invitation is redeemable by link only. The one-time code that a password-reset email carries is never printed in an invitation, because the code lookup matches on purpose and person with nothing to tell two live records apart — a correct code checked against the wrong record would fail and burn one of the five attempts that retire it.

Revoking is not the same as suspending. A suspension records a reason and is a statement about conduct; revoking sign-in simply says the person no longer has a portal account. Either way their record is untouched, and so is every notification addressed to them.

5.9 Move or end a graduate's portal access

Summary

A rollover graduation opens a read-only window on the pupil portal: the graduate can sign in and read their own record, but nothing else, until the window's last day. An administrator reads that window, moves its last day earlier or later, or ends it immediately; the pupil portal itself refuses any write the graduate attempts once the window is over.

Preconditions

• The actor holds Students_READ to read the window, Students_UPDATE to change it.
• Changing the window additionally requires Users_UPDATE, because ending or re-opening access can switch the graduate's sign-in on or off — an identity change no Students_UPDATE holder is otherwise trusted with.
• The target pupil is within the actor's object-level scope, checked before the graduation is even looked up, so an out-of-scope actor gets the same 404 an absent graduation produces.

Main Flow

Branches and Edge Cases

5.11 Edit a staff member's salary and bank details from the staff form

The nine writable pay fields — basic salary, allowances, bank name, account number, branch, PAN, citizenship number, SSF and CIT — can be entered when a staff member is created, from the detail page's own panel, and on the staff edit form.

Because a teacher is a staff row with a teaching designation and the teachers screen reuses the same form, this covers teachers too; there is no separate teacher edit form.

The form uses the two salary endpoints: GET /staff/:id/salary behind StaffSalary_READ and PATCH /staff/:id/salary behind StaffSalary_UPDATE. It issues the same two calls the detail panel does.

Three rules govern the block, and each one is load-bearing.

• The block renders only when the pay was actually read. Not when the request merely completed — the client fetcher returns {status: "forbidden"} for a 403 rather than throwing, so "the query succeeded" is true of a refusal. Rendering on that would show nine blank editable fields to somebody who may not read them, who could then type a real account number, save, and be told it saved while the write was correctly refused.
• The write is gated on the same fact, not on the permission alone. PATCH /staff/:id/salary is a full-record write: every blank field is sent as an explicit null, because omitting a cleared field would leave the old value in place. Without a loaded baseline, a save would therefore replace bank, PAN, citizenship, SSF and CIT with nulls — so an actor holding StaffSalary_UPDATE and not StaffSalary_READ issues no salary request at all.
• The pay is sent only when it changed, compared field by field with both sides normalised: the record stores null where the form holds "", so a naive comparison reports every untouched load as changed and rewrites the whole record on every unrelated save.

Two requests, not one. The staff patch runs first and the pay second, and only if the first succeeded. PATCH /staff/:id accepts no salary block, so the key is stripped from that payload — the API runs forbidNonWhitelisted and would otherwise reject the whole save. If the pay leg fails after the staff patch landed, the message says so rather than implying the whole edit was lost.

Two further refusals apply to the write. Nobody edits their own pay or bank account, superadmin included (403 SALARY_SELF_CHANGE_FORBIDDEN). Once the salary module holds any assignment for the member, basicSalary and allowances change only through a salary assignment: sending a different figure is refused with 409 STAFF_SALARY_MANAGED_BY_SALARY_MODULE, while re-sending the unchanged figures beside a bank edit succeeds. The read reports this as managedBySalaryModule.

A staff member with no pay on file returns 200 with every column null, not a 404, so the block renders seeded blank — that is the population this change exists to serve.

Optimistic concurrency covers these fields. StaffSalaryDto carries the staff row's version counter, and PATCH /staff/:id/salary requires it: a second operator saving pay against a token that has moved is refused with 409 PEOPLE_STALE_RECORD rather than overwriting the first silently. The check runs inside a transaction with the row locked, so it cannot be raced.

The token is shared with the general staff edit, because both routes write the same staff row. A client that saves the employment record and then the pay must send the version the first call returned. What the token does NOT cover is the person's users row — a concurrent rename through ban, unban, password reset or the users module does not move it.

5.12 Read the headline people counts

The dashboard shows active enrolled pupils, pupils admitted this Bikram Sambat month, employed and teaching staff, and guardians.

1. The client calls GET /api/people/summary.
2. The API requires Students_READ; a role without it receives 403.
3. The students section counts pupils within the caller's own scope. wholeSchool is true when that scope is the whole roll and false when the caller sees only part of it.
4. The staff section appears only for a role holding Staff_READ, and the guardians section only for a role holding Guardians_READ. Otherwise the section is null and the client hides the tile.
5. activeEnrolled counts pupils with an active record and an active enrolment in the current academic session; it is null when no session is current.
6. month carries the Bikram Sambat month and its Gregorian first and last day, which bound admittedThisMonth.

Counts are cached for 60 seconds. A student, staff, guardian or enrolment write clears them immediately; a bulk import, the graduate-access sweep or a change to a designation's teaching flag appears within 60 seconds. A slow or unavailable Redis never delays the response: the counts are read from the database.

5.13 Choose a staff member's roles

Summary

A staff member's roles decide what they can see and do once signed in. By default the job decides: every staff member holds staff, and a teaching designation adds teacher. An administrator can instead choose the roles at admission, and can change them later. Staff never hold a guardian- or pupil-scope role; a person who is also a parent or a pupil keeps that grant through their other profile, and the staff surfaces never show or touch it.

Preconditions

• Choosing roles on admission needs Users_UPDATE as well as Staff_CREATE. Changing roles on an existing member needs Users_UPDATE as well as Staff_UPDATE. Choosing somebody's authority is an identity change, the same line sign-in access is drawn at. An admission or edit that names no role needs only the staff permission.
• Every role named must be one the actor could hand out: a role whose permissions the actor holds in full, and the superadmin role only if the actor is a superadmin.
• Changing roles on an existing member additionally requires the target to be somebody other than the actor.

Main Flow

The edit endpoint takes one of three choices:

Only the roles staff surfaces manage are replaced. A guardian- or pupil-scope role the person holds through another profile is never read, shown, added or removed by this flow.

The admin panel offers the role choice on the admission form and on the edit form. The edit form shows a Role select only to an actor holding both Staff_UPDATE and Users_UPDATE; any other viewer sees a read-only "Role: ..." line (or nothing, when the response carries no roles). The same read-only line replaces the select on the operator's own record, decided by comparing the signed-in user's id with the staff record's linked account id; while the session is unknown the select is still offered and the API refuses a self change. The select maps to the PATCH /staff/:id fields (Staff: Update); the roles come from GET /staff/:id/assignable-roles (Staff: Assignable roles (existing)).

• On a teaching designation the select offers only Keep current and the job choice, because the API refuses an explicit role there (400 STAFF_ROLE_TEACHER_JOB_ONLY). Switching the form to a teaching designation puts an explicit pick back on Keep current.
• While the assignable list is loading or has failed, the select offers only Keep current and the job choice.
• Under the select, a "Replaces: ..." line names the roles the member holds now that the save would take away. It is empty for Keep current.
• Refusals show these messages: PEOPLE_SELF_ROLE_CHANGE_FORBIDDEN shows "You can't change your own role."; PEOPLE_ROLE_NOT_PERMITTED, USER_SUPERADMIN_PROTECTED and a 403 ROLE_NOT_FOUND show "You can't change this person's role."; USER_LAST_SUPERADMIN_PROTECTED shows "This is the last superadmin; the role can't be removed."; STAFF_ROLE_SCOPE_NOT_ASSIGNABLE and STAFF_ROLE_TEACHER_JOB_ONLY show their own explanations; STAFF_ROLE_SOURCE_INVALID asks the operator to reload.

Only a viewer holding Staff_UPDATE sees a member's roles: the roles list (public id and name, in name order) is present on the detail response and on the create and update responses for that viewer, and absent otherwise. A colleague reading the directory learns nothing about who holds what.

Sequence Diagram

Branches and Edge Cases

5.14 Create a parent with sign-in access from the admin panel

The parent creation screen (/dashboard/parents/new) can create the parent and invite them in one submit.

• The checkbox. An operator holding Users_UPDATE sees a "Grant sign-in access" checkbox. It renders only after the page has hydrated, because the permission is read from a client query and an unhydrated render would disagree with the server, and only on create. Editing sign-in after the parent exists happens on the parent detail page's sign-in card, not in the edit form.
• What is sent. The panel sends grantSignIn: true only when the box is ticked and the operator still holds Users_UPDATE at the moment of submit. A tab left open across a role change therefore cannot post a grant the operator can no longer see. An unticked box sends no grantSignIn field at all, and the panel never sends person.canLogin, so the two flags cannot disagree (400 PERSON_SIGN_IN_FLAGS_CONFLICT).
• What the backend does. POST /guardians accepts grantSignIn, refuses it with 403 AUTH_FORBIDDEN unless the actor holds Users_UPDATE, and writes the person, the guardian role grant and, when sign-in is granted and the parent has an email address, the invitation, all in one transaction. A parent with no email address is created with sign-in access and no invitation (invitation: {"sent": false, "reason": "no_email"}). The form shows a hint under the ticked box while the email field is empty.
• The toast. The success message reports the invitation outcome:

Sources: parents/_components/ParentForm.tsx, ParentSignInAccessField.tsx, useParentSignInGrant.ts, parent-form-utils.ts (buildCreateParentPayload), parent-form-announce.ts, and guardians.service.ts (create).

5.15 Staff and teacher lists after a write

The Staff and Teachers lists share one client-side query cache. After any successful staff create, update, suspend, delete, restore, unban, or sign-in grant or revoke, the panel invalidates every cached page and filter of that list, mounted or not, before it navigates or returns control. The row the operator just changed therefore shows its new state, including employment status, on the next view of either list, rather than the pre-write row for the rest of the cache lifetime. A refused write invalidates nothing. A password-reset link changes nothing the list shows and does not invalidate.

Only the list entries are invalidated. A member's salary and manager reads and the lookup reads are separate cache entries that a person write does not change.

Sources: staff/_components/staffListQuery.ts (invalidateStaffList), staffMutations.ts, StaffDetailsClient.tsx, StaffListClient.tsx, StaffTable.tsx.

5.16 Teacher routes

A teacher is a staff row with a teaching designation, so the Teachers screens reuse the staff pages rather than duplicate them.

Links, redirects after a save and row actions for a record opened under Teachers stay under /dashboard/teachers, so the sidebar keeps highlighting Teachers. The staff routes never redirect back, which keeps the pair from looping.

Sources: teachers/**, staff/_components/staff-paths.ts.

6. Admin Flows

Every write endpoint under /students, /guardians, and /staff is an admin-surface flow — there is no separate mobile or public surface for this domain. The flows below are the ones the format's checklist calls out that are not already covered as user-facing flows above.

6.1 Create

Covered as 5.1 (students), and identically shaped for guardians (POST /guardians — one transaction: users, guardians, and a guardian role grant) and staff (POST /staff — one transaction: users, staff, and staff/teacher role grants).

Whether the person gets a portal account is decided before the transaction opens, from grantSignIn or the older person.canLogin, and requires Users_UPDATE on top of the create permission. Absent means no: most people on a school's roll want a record and no login. Roles and sign-in access are separate — the role grant above says what somebody may do once signed in, not whether they may sign in at all.

On POST /staff the role grant is the job's roles (staff, plus teacher for a teaching designation) unless rolePublicIds is sent. Sending it requires Users_UPDATE on top of Staff_CREATE, is refused for a teaching designation, and replaces the job's roles rather than adding to them. Flow 5.13 covers the rules.

6.2 List

Covered as the read path inside 5.1-5.7's supporting detail. Every list is scoped, cached, paginated (mandatory for guardians and staff; optional but supported for students), and searchable via trigram-plus-substring matching.

6.3 Read detail

Covered — findOne on each service, gated by PeopleAccessService.assertCanAccess.

6.4 Update

Covered as 5.3.

6.5 Reorder

Not applicable. Nothing in this domain has a manual display order.

6.6 Activate/deactivate

Nearest equivalent is employmentStatus on staff (active/on_leave/suspended/resigned/terminated/retired) and recordStatus on students (active/inactive) — both plain enum fields updated through the ordinary PATCH flow (5.3), not a dedicated action route. Login suspension (ban/unban, 5.6) is a separate axis from either.

6.7 Soft delete

6.8 Restore

6.9 Export/import

Not part of this module. Bulk admission/roll import is a separate DataImport/DataExport permission module and is out of scope here.

6.10 Moderation

Not applicable — there is no user-generated content in this domain to moderate.

6.11 Manual retry

Not applicable — every write here is synchronous; there is no queued job with a retry button.

7. Lifecycle and State Transitions

Three independent state axes exist per person, and they are deliberately never conflated:

1. Profile liveness (deleted_at on students/guardians/staff, and on users once every profile is gone) — soft delete and restore.
2. Login ability — two separate flags, and conflating them is a mistake the UI must not repeat. users.can_login says whether the person has a portal account at all; users.banned says whether an existing account is currently suspended, and carries a recorded reason. Both are independent of whether the record is live, and neither has any effect on notification delivery: somebody with no portal account still receives every message the school addresses to them.
3. Domain status — students.record_status (active/inactive) and staff.employment_status (active/on_leave/suspended/resigned/terminated/retired) — a plain descriptive field the office sets, with no enforced transition graph of its own.

Diagram (profile liveness, the only axis with real guard logic):

Login and domain-status are flat, unguarded toggles and are shown here as a single combined diagram for clarity rather than two trivial two-node graphs:

9. Data and Side Effects by Flow

10. Error and Recovery Flows

11. Diagrams Required Per Module

• Actor capability diagram — §3 above.
• High-level module flow diagram — §6.1's create flowchart, representative of every write.
• Sequence diagram for each major user/admin/system flow — §5.1 through §5.7.
• State machine diagram for every lifecycle — §7.
• Data side-effect diagram for write flows — §9 and §12.6.
• Error branch diagram for critical flows — §6.7 (delete), §6.8 (restore).

12. Mandatory Feature and Flow Deep-Dive Pack

12.1 Feature Inventory With Minor Behaviors

12.2 Business Process Diagram Pack

Service blueprint — admission:

Swimlane — who owns each part of an admission:

12.3 Business Rules and Policy Traceability

12.4 Tradeoffs and Product Rationale

12.5 Flow Edge-Case Matrix

12.6 Flow-to-Data Trace

12.7 Experience Quality Checklist

• The doc explains what the actor is trying to accomplish — admit a pupil, register a parent, onboard an employee, and manage each safely afterward.
• The doc explains what the backend does that the actor does not see — atomic code allocation, the two-phase primary-guardian write, computed completeness, cache tag composition.
• The doc covers every minor flow and branch — see §12.1 and §12.5.
• The doc includes user, admin, and system flows where applicable (this domain has no guest or automated-worker flows — every entry point is an authenticated, permissioned human action).
• The doc explains business logic, tradeoffs, and rationale — §12.3, §12.4.
• The doc maps every flow to API routes and backend side effects — §4, §9, §12.6.
• The doc includes diagrams appropriate to each flow type — §5-§7, §12.2.
• The doc covers all edge cases and failure recovery — §10, §12.5.

13. Completion Checklist

• Every feature, minor action, and submodule capability is listed — §4, §12.1.
• Every actor has allowed and forbidden behavior — §3.
• Every major and minor flow includes steps, branches, and diagrams — §5, §6.
• Every lifecycle has a transition table and state diagram — §7.
• Every flow links to the API and backend docs — §4, and inline throughout §5.
• TDD dependencies are called out where they shape behavior — no sibling TDD doc exists for this module in this repository; none is referenced.

See Also

• API doc: /docs/developer/people/api
• Backend doc: /docs/developer/people/backend