People Backend Documentation

1. Documentation Evidence

2. Backend Scope and Boundaries

Owns

• The unified person write path shared by students, guardians and staff: users identity fields, normalization, and the email-conflict rule (PersonWriterService).
• Object-level access control over students, guardians, staff, and users rows — deciding which rows an actor's active role may see or touch (PeopleAccessService).
• Admission-number and employee-code allocation, atomic and timezone-correct (PeopleCodeService).
• Soft delete and restore, profile-scoped, with the rule for when the underlying users row goes too (PeopleDeletionService).
• Account actions common to all three profile kinds: ban, unban, password-reset link, and granting or revoking sign-in access with its account invitation (PeopleAccountService).
• Field-level permission resolution for the two gated field groups, StaffSalary and StudentMedical, and the sign-in grant decision shared by all three create paths (PeoplePermissionsService).
• The students, guardians, and staff CRUD surfaces themselves, including the student-guardian relationship (many-to-many, with a primary/legal/emergency/pickup/lives-with flag set per link) and the staff department/designation assignment.
• Trigram-backed name/code/organisation search, with the transaction-scoped similarity threshold (withSearchThreshold).

Does Not Own

• Authentication, session issuance, and JWT validation — AuthModule/JwtAuthGuard/AuthSessionService (imported, not owned).
• Role and permission definitions and the RoleGuard that enforces them — RoleModule.
• The school's timezone value itself — SchoolProfileModule/SchoolProfileService; this module only consumes getTimezone().
• Department and designation lookup rows — LookupsModule owns their CRUD; packages/db/src/schema/school/lookups.ts owns their schema. This module only references them as foreign keys on staff.
• Ethnicity and mother-tongue lookup rows — also LookupsModule (PersonClassificationsController), backed by ethnicities/mother_tongues in packages/db/src/schema/identity.ts. This module only stores the foreign key on users and resolves the display name at read time; renaming or deleting an entry there is a LookupsModule write, never one this module performs.
• Redis connection management and the generic cache primitives — RedisCacheService; this module only calls getSoft/setSoft/delPatternSoft.
• Email delivery and verification-token issuance for the password-reset flow — AuthEmailService/VerificationTokenService, both from AuthModule.
• Superadmin protection logic itself — ActorAuthorityService.assertNotLastSuperadmin and assertMayActOnAccount; this module only calls the former before a ban or a deletion that could remove the last superadmin, and the latter before every ban, unban, and password-reset-link call.
• Classes, sections, enrollment lifecycle (enrolled/promoted/graduated/transferred/withdrawn/struck-off) — deliberately absent from students; record_status here is a two-value record-level toggle only, not that vocabulary.
• Bulk roll import/export — a separate DataImport/DataExport permission module.

Source of Truth

3. Module Composition

GuardiansModule re-declares the shared services as its own providers rather than importing them from PeopleModule. Nest instantiates a second copy of each — PeopleAccessService, PeopleAccountService, PeopleDeletionService, PeoplePermissionsService, and PersonWriterService each exist twice in the running application, once per module. None of them carry per-instance state (each only holds injected singletons — the database handle, RoleService, etc.), so the duplication is a wiring redundancy, not a correctness bug; it does mean a change to one of these services' constructors must satisfy both modules' import lists independently.

4. File and Directory Map

apps/api/src/modules/people/
  people.module.ts
  dto/
    person.dto.ts
    account-action.dto.ts
    index.ts
  shared/
    people-access.service.ts
    people-account.service.ts
    people-code.service.ts
    people-deletion.service.ts
    people-permissions.service.ts
    person-writer.service.ts
    trigram-search.ts
  students/
    students.controller.ts
    students.service.ts
    student-guardians.service.ts
    student-medical.service.ts
    dto/
      student.dto.ts
      index.ts
    __tests__/
      students.service.integration.spec.ts
    index.ts
  guardians/
    guardians.module.ts
    guardians.controller.ts
    guardians.service.ts
    guardians.service.spec.ts
    dto/
      guardian.dto.ts
      index.ts
  staff/
    staff.controller.ts
    staff.service.ts
    staff-salary.service.ts
    staff.service.spec.ts
    dto/
      staff.dto.ts
      index.ts
    index.ts
  summary/
    people-summary.controller.ts
    people-summary.service.ts
    people-summary-month.ts
    dto/
      people-summary.dto.ts
    __tests__/
      people-summary.integration.spec.ts
      people-summary-month.spec.ts

5. Data Model

5.1 Schema Source

packages/db/src/schema/
  identity.ts        # users, user_role, sessions, userDevice, lookups (ethnicities, motherTongues)
  school/
    people.ts         # students, guardians, student_guardian, staff, code_counters
    lookups.ts         # departments, designations

5.2 Tables and Collections

users

The unified person model — one row per human, whatever hats they wear. Owned by the identity schema, not this module, but every field below is what PersonWriterService/PERSON_SELECTION read and write on behalf of students, guardians and staff.

Money, timezone, and JSON: none of users' own columns are money or JSON; date-of-birth and banned_at/timestamps follow the same timestamptz convention as every other table in this schema.

students

There is deliberately no is_complete column — see the Business Logic and Invariant Catalog (§16.5) and the Business Rules table in the feature doc.

guardians

The guardian_org_has_name CHECK is written as kind <> 'organization' OR (organization_name IS NOT NULL AND btrim(organization_name) <> '') — deliberately not the algebraically equivalent (kind = 'organization') = (organization_name IS NOT NULL) form, because AND with a false first operand evaluates to false (never NULL), while the equality form can evaluate to NULL and a CHECK whose expression is NULL passes.

student_guardian

The join table that makes siblings — and every irregular family situation — ordinary. No father/mother columns; a student has zero or more guardians of any relationship.

No deleted_at on this table — a link is deleted outright (by setGuardians' delete-and-reinsert) rather than soft-deleted.

staff

The composite foreign key staff_designation_in_department_fk targets (departments.id, designations.id) — it exists because MATCH SIMPLE (Postgres's default) skips a multi-column FK check when any referencing column is NULL, which is wanted for "department set, designation not yet chosen" but would otherwise leave a hole for (NULL, designation-from-a-different-department). The staff_designation_needs_department CHECK closes the case where designation_id is set but department_id is not.

code_counters

The atomic-allocation backing table for admission numbers and employee codes.

student_graduations

Owned by rollover's schema file (packages/db/src/schema/school/rollover.ts) but read and written by this module's graduate-access surface, because a graduation is what turns a pupil read-only. One row per graduation; revoked_at marks a row no longer live rather than deleting it.

5.3 Relationship Diagram

6. Services and Responsibilities

6.1 PeopleAccessService

Superadmin (activeRole.isSuperadmin) resolves to { kind: "all" } before anything else is read. Otherwise the active role's scope_kind column decides — not its name. guardian and student get bespoke restricted predicates; all gets { kind: "all" } provided the caller also holds the entity's own Module_READ permission, falling back to selfOnlyScope when it does not; and self, together with anything unrecognised and any caller with no active role, gets selfOnlyScope — which is the sql-tagged literal false for students, guardians and classSubjects, and the actor's own row for users and staff.

The distinction between name and column is load-bearing and this page previously stated the wrong one. Deriving scope from a role's name meant every operator-created role fell through to a branch it was never meant to reach; the column exists so an arbitrary role is safe to assign.

scope_kind is a second, independent grant, not a filter on the first. A permission code answers "may this role read pupils at all"; scope_kind answers "which pupils". Neither implies the other, which is why the two are checked separately and why a role can hold Students_READ and still see nothing.

scope_kind is settable, through exactly one route

PUT /roles/:publicId/row-visibility, body { scopeKind: "self" | "all" }, behind Roles_UPDATE.

It is a dedicated route rather than a field on PATCH /roles/:publicId because that DTO is shared with create through PartialType(OmitType(CreateRoleDto, ...)), so one field on either would reach both write paths. scope_kind appears on neither DTO, and both write paths name their columns instead of spreading.

RoleService.setRowVisibility runs in one transaction that first reads the role row FOR UPDATE. Six constraints, enforced in this order:

Constraint 6 is the global ValidationPipe, so over HTTP it answers before the service runs and constraint 5 is never reached through this route. Constraint 5 sits in the service so that no caller of setRowVisibility can turn a role that staff hold into a guardian- or pupil-scope role: staff surfaces never grant such a role (§6.11a), and narrowing one after the fact would hand every holder a parent's or a pupil's view. Soft-deleted staff count because a restore brings the person's grants back with them. The row lock is what makes the check hold against a concurrent staff edit, which reads the role FOR SHARE before granting it — the two serialise on the roles row (and, like any FOR UPDATE on a parent row, the lock also holds back concurrent user_role inserts for that role for its duration).

Constraint 2 is the only thing preventing a school-wide lockout. All five seeded roles are isSystemRole, and the seeded guardian role is scoped guardian precisely so a parent sees their own children — narrowing it to self would refuse every parent in the school, from a screen whose worst apparent outcome is "a dropdown changed".

Constraint 4 rests on a flag, not on a permission code, because Roles_UPDATE is not a superadmin proxy: "Roles" is absent from SUPERADMIN_ONLY_MODULES, so the admin catalogue includes it. Permission arithmetic cannot reach isSuperadmin.

Constraint 3 reads user_role. Reading activeRole.id instead would let a multi-role caller widen a role they hold but are not currently acting as.

After the transaction commits, the write is accompanied by an explicit recordActivity carrying { field: "scopeKind", from, to } and the target role. The audit interceptor derives module/action from @Permissions(), so its own entry for this request is Roles/UPDATE — indistinguishable from a description edit. The explicit call is what carries the detail.

RoleDto gained scopeKind, hasUnreachablePermissions, canSetRowVisibility and canWidenRowVisibility; RoleWithPermissionsDto gained unreachablePermissions. The last three are computed from the same constraints and the same user_role query the route enforces, so the admin panel renders them and derives no authority of its own. hasUnreachablePermissions and unreachablePermissions cover the five *_READ codes this resolver maps to an entity, and are derived from isEntityReachable rather than restated as a second table.

6.2 PeopleAccountService

inviteOnCreate and issue live on PeopleInvitationService, not here — see §6.2a.

All the ban/unban/reset methods are wired to all three controllers — StaffController exposes /staff/:id/ban, /:id/unban, and /:id/password-reset exactly like the student and guardian controllers, each behind Staff_UPDATE. The two :id/sign-in routes are wired the same way on all three, but behind Users_UPDATE.

setSignIn is the only post-create writer of can_login. buildUpdate emits no such key, so the sign-in transition cannot ride along on a person PATCH. That separation is what allows the write to be guarded: setSignIn issues UPDATE users SET can_login = :wanted WHERE id = :id AND can_login = :observed AND deleted_at IS NULL, so a lost race is a zero-row result and a 409 PERSON_SIGN_IN_STATE_CHANGED rather than a silent overwrite. Folding the same guard into buildUpdate is not possible — that returns one object applied as a single UPDATE, so a failed guard would discard the caller's name, phone and address edits too and answer 200 having written nothing.

Granting and inviting are separate questions, and only the revoke may short-circuit. A grant whose can_login already holds true skips the write and still decides the invitation. Returning early instead would make both documented recovery paths unreachable: invite: false promises "prepare an account and invite later", no_email promises "add an address and call again", and both bring the operator back to this route with the state already correct. They would then get a 200 that sent nothing — indistinguishable from success, with no other route that would ever send that invitation. A revoke has no second question left to answer, so it is the one direction that returns early.

The grant and its invitation share one transaction. PeopleInvitationService runs on that transaction and propagates: a failure to schedule the email rolls the grant back rather than answering sent: true for an invitation nobody will receive. Reporting a person as invited when they are not tells the operator something false about somebody who now holds credentials they will never be told about.

Three conditions skip the invitation without failing the grant, each named in the outcome: invite: false gives not_requested, no address on file gives no_email, and a suspended account gives banned — an invitation into an account JwtStrategy will refuse is a support call, not an activated account, which is the same rule people-invite.processor.ts applies to bulk invitations. A revoke always answers revoked.

Revoking deletes the sessions. JwtStrategy re-reads can_login on every request, so a revoke takes effect on the next call either way; deleting the rows removes the possibility of a refresh token staying redeemable, which is the same argument ban makes two methods above.

Input normalization: ban's reason is trimmed before the blank check, so whitespace-only input is refused. Validation order in ban: blank-reason check, then self-target check (actorId === targetUserId, exempt from every other check here), then ActorAuthorityService.assertMayActOnAccount (refuses a non-superadmin acting on a superadmin), then — inside the transaction — the last-superadmin count, then the write. unban and sendPasswordResetLink run assertMayActOnAccount but never the self-check or the last-superadmin count, since neither action can remove access from anyone. assertMayActOnAccount reads the target's full role set, not their currently active role, so a superadmin who happens to be acting as a guardian in the current session is still protected. Transaction boundary: the users update and the last-superadmin assertion share one transaction; the session sweep happens after commit, outside it; assertMayActOnAccount runs before the transaction opens on all three methods. Fail-open/closed: both the last-superadmin check and assertMayActOnAccount are fail-closed (throw rather than allowing an ambiguous state). Logger usage: sendPasswordResetLink logs at log level on success, naming the kind, profile id, and acting administrator — never the email address or the token.

6.2a PeopleInvitationService

Separate from PeopleAccountService because the two answer different questions. That service decides whether somebody may have an account — it reads authority, guards the transition and sweeps sessions. This one only knows how to tell a person they have one.

Every method takes an executor, and every method propagates. The token, the notification event and its outbox row commit with the caller's business change or not at all; a fire-and-forget call after the commit would lose the invitation entirely on a restart between the two, leaving somebody who exists, believes they were invited, and has nothing scheduled. Propagating rather than swallowing is the other half of that contract, for the reason given under setSignIn above.

inviteOnCreate returns three distinguishable answers: null when sign-in was not granted, so there was never anything to invite anybody to; { sent: false, reason: "no_email" } when it was granted but there is nowhere to send; and { sent: true, to } otherwise. sent: true means enqueued, not delivered — the delivery row carries that.

Invitations last 7 days (ACCOUNT_INVITE_TTL_MS), stated explicitly on every mint. Without it the record inherits OTP_EXPIRY_MINUTES, 15 minutes, and an invitation that dies before the recipient next opens their inbox is not an invitation. The one-time code is minted alongside — createPasswordReset always mints one — but is stripped before the email is built, because consumeByOtp is scoped to password_reset and an invitation is therefore redeemable by link only. Rendering a code an invitation cannot be redeemed with would send the recipient down a path that always refuses them.

6.3 PeopleCodeService

Input normalization: none needed — the scope is a closed union ("student" \| "staff" \| "student_id" \| "asset"), enforced by the type system and mirrored by the code_counters_scope_known CHECK as a database-level backstop. Idempotency: none — each call reserves a new block; a caller that must retry a failed admission without burning a number has to catch the failure before calling this. Response mapping: format() builds PREFIX-YEAR-0001, zero-padded to 4 digits as a minimum for student/staff/student_id, never a truncating fixed width (lpad('10000', 4, '0') returns '1000', which this code avoids via padStart, which only pads and never truncates). The asset scope (prefix AST, allocated from assets in apps/api/src/modules/assets) is the one exception to that width: it zero-pads to a fixed 6 digits (ASSET_SEQUENCE_WIDTH), matching the assets_code_format CHECK (^AST-[0-9]{4}-[0-9]{6}$) — a school issuing more than 999,999 assets in one year exhausts the range and AssetsService.create raises ASSET_CODE_RANGE_EXHAUSTED rather than silently truncating the sequence.

adoptSuppliedStudentId(supplied, executor) is a third path alongside allocate/allocateOne, used only when an operator types a studentId on POST /students instead of leaving it to be allocated. It canonicalises the value (trim, upper-case, zero-pad the sequence to at least 4 digits), rejects a shape that does not match SID-YYYY-NNNN with 400 STUDENT_ID_MALFORMED, and rejects a sequence above MAX_STUDENT_ID_SEQUENCE (999,999) with 400 STUDENT_ID_SEQUENCE_OUT_OF_RANGE — the bound exists because an unbounded supplied value once set code_counters.next_value to INT_MAX (SID-2026-2147483647), after which every auto-allocated admission for the rest of that calendar year raised 22003 integer out of range with no route able to reset the counter, and only Students_CREATE was needed to trigger it. The counter is then advanced with GREATEST(next_value, sequence), in the year the supplied value names, never the current year — advancing only the current year would let a future-dated SID-2027-0001 sail through today and then collide with the real allocation on 1 January 2027. GREATEST also means a supplied value can never rewind the counter and hand the next admission a number already in use.

6.4 PeopleDeletionService

Transaction boundaries: both methods run entirely inside one db.transaction. softDeleteProfile's guardian-with-live-children check runs first, so the whole operation aborts before any write on a blocked guardian. Idempotency: restoreProfile is a no-op (returns without writing) when the row is already live — it does not throw. Fail-closed: assertNotLastSuperadmin inside softDeleteProfile is a hard stop with no fallback.

6.5 PeoplePermissionsService

can is the authorization decision; heldPermissions is not. can returns true for a superadmin without consulting the set at all. heldPermissions does not special-case superadmin — measured, a superadmin gets every seeded code back — and that is only harmless while the seed grants them all. grantToRoles uses onConflictDoNothing and never revokes, so a deployment upgraded without permissions:sync leaves superadmin missing whichever codes the release added, and a raw membership test would then deny the highest-privileged user with no way to tell why. Use heldPermissions to pass a resolved set into something that will itself go through can, or for a scope predicate where superadmin is handled separately; use can for anything that decides.

resolveSignInGrant is the single implementation of the create-time sign-in decision, shared by all three create paths. It accepts two spellings of the same intent — grantSignIn on the create body, and the older person.canLogin that the admin panel posts from a checkbox — because ValidationPipe runs forbidNonWhitelisted and dropping the older field would reject every create the panel sends. Both pass through the identical check, so neither is an unguarded route to the same state. A contradiction between them raises 400 PERSON_SIGN_IN_FLAGS_CONFLICT rather than being resolved by precedence: the caller has stated two intentions and the server cannot know which is the mistake. Absent means no. A grant then requires Users_UPDATE through can, and raises 403 AUTH_FORBIDDEN without it — granting sign-in creates a credential-bearing account, and POST /auth/password/forgot is public, so anybody with an email on their row can then obtain a session.

6.6 PersonWriterService

buildUpdate uses Object.hasOwn(dto, key) rather than !== undefined for every field — an explicit "lastName": null in the request body is a clearing instruction and must survive; an absent key must produce no key in the patch at all.

canLogin is an argument to buildInsert, not a field of the DTO it reads, and buildUpdate never emits it at all. buildInsert takes a second parameter, account: { canLogin: boolean }, and there is no default: every caller states the value, having already checked what it is allowed to state (PeoplePermissionsService.resolveSignInGrant for the three top-level creates, an explicit Users_UPDATE check in StudentGuardiansService for a guardian created inside an admission). Reading it from dto instead would put the decision here — silently, from a request body, with no permission check anywhere on the path — and simply removing the field from the DTO would not fix that, because dto.canLogin ?? true would still yield true and so would the column default behind it. The decision has to stop being made in this file, which is why the parameter is required rather than optional.

buildUpdate omitting it is the same rule on the other side: can_login taken from a PATCH body would let an actor holding only Students_UPDATE flip an existing person to login-capable. Post-create transitions go through PeopleAccountService.setSignIn, which checks the identity permission and guards the write.

An address group (permanentAddress/currentAddress) is replaced WHOLE, never patched field by field, and the Object.hasOwn discipline above governs only the flat, top-level keys — it does not reach through nesting on its own. When a group key is present on the DTO, all six of its columns are written from it and a missing key inside the group means NULL; when the group key is absent, the whole group is left untouched. A field-wise patch would let { "permanentAddress": { "provinceId": null } } clear the province while leaving the district in place, which raises the unmapped 23514 permanent_district_needs_province from a request the operator considers perfectly reasonable — the fill-order CHECKs on the schema are what make this discipline load-bearing rather than stylistic. An all-NULL current address, by the same rule, is what "not recorded" looks like: there is no separate flag for "same as permanent", so a family that has not given a different present address simply has six NULL columns rather than a copy of the permanent one.

A guardian's kind (person/organization) is orthogonal to the slot (relationship: father/mother/local_guardian) it occupies in student_guardian — either can vary independently, which is what lets a local guardian be an orphanage or a father slot be filled by an organisation acting in loco parentis. resolveGuardian in StudentGuardiansService reads kind directly from the payload rather than inferring it from relationship, because an earlier version inferred it from relationship === "organization", and narrowing the relationship enum to three slots made that comparison permanently false — every guardian created from the pupil form would have silently become a natural person, with guardian_org_has_name never able to fire on that path again. Response mapping: none — this service builds column sets and selections, never a response DTO. PersonWriterService.translate's constraint lookup (constraintOf) walks error.cause recursively up to depth 5, because drizzle-orm's node-postgres driver wraps the raw pg error (which carries .constraint) inside .cause rather than rethrowing it directly — reading error.constraint on the top-level object finds nothing on every single database error from this driver.

An administrator editing a person's email keeps the sign-in credential in step. syncSignInEmail compares the address on users before the write to the incoming one, both trimmed and lower-cased, and does nothing when they already agree. When they differ it writes the same normalised value onto account.account_id for that person's email-provider row — or user:<userId> when the address is cleared to null, since account_id cannot itself be null — and deletes every unconsumed verification row the person holds, of any purpose. That last step is deliberate: a password-reset or email-change link minted against the address being replaced must not go on working once an administrator has moved the person to a different one. This runs on the same transaction as the users update, so the two rows never observe each other's address as stale.

PERSON_SELECTION (also exported from this file) is the users column set every student, guardian, and staff read projects — six list/detail queries share it so the person shape cannot drift by call site. Alongside the plain columns it carries ethnicityName and motherTongueName as two correlated subqueries (SELECT name FROM ethnicities/mother_tongues WHERE id = users.ethnicity_id/mother_tongue_id) rather than LEFT JOINs: a join added at one of the six call sites would have to be replicated at the other five in the same position or the projected shape silently diverges, while both lookups are small, indexed on their primary key, and read once per row from Postgres's own cache, so the join buys nothing measurable and costs the invariant. Both the id and the name are returned together — the id is what an edit form posts back on the next write and what a filter compares against, the name is what a person reads, and a response carrying only the name would force the client to search the lookup list by string to re-select the value it was just given.

6.7 StudentsService

Input normalization: admissionNumber?.trim() || allocateOne(...) — a supplied number that is blank after trimming is treated as absent. Validation order in create: guardian-set shape validated before the transaction opens (fail fast, no partial work to roll back for a purely structural error), then inside the transaction: email freedom, then the insert. Transaction boundaries: the entire admission — users insert, code allocation, students insert, guardian links — is one transaction; a half-admitted student is not a reachable state. Idempotency: none at the API layer; a client retry after a timeout can create a duplicate person unless the caller supplies its own admissionNumber and relies on the unique index to reject the second attempt. Response mapping: toDto computes isRecordComplete from guardianCount > 0 and version from versionOf(row.version). Fail-open/closed: the version check in update is fail-closed — a mismatch always aborts, never a warning. Logger usage: none in this service directly (logging for the account actions it delegates to lives in PeopleAccountService).

6.7a StudentGraduateAccessService and GraduateAccessService

StudentGraduateAccessService (people/students/student-graduate-access.service.ts) is the thin admin read/write behind GET/PATCH /api/students/:id/graduate-access: it runs the same two-layer authorization every single-record student route runs (@Permissions for "at all", PeopleAccessService.assertCanAccess for "this one"), loads the pupil's live (unrevoked) graduation, and delegates every decision to GraduateAccessService (people/shared/graduate-access.service.ts), which five modules share — the guardian portal, attendance, leave, assignments and people itself.

The read side is pure computation over the stored row and today's school-calendar date: graduateAccessState (utils/graduation/graduate-access.util.ts) returns none | pending | grace | ended, and ended also counts a portal_access_until that has simply passed, so a read never trusts the expiry sweep to have reached the row yet. The write side never reads that computed state — end, setUntil and endNow all decide on the stored portal_access_ended_at directly, because deciding on the computed state would make "end now" a no-op for a row the sweep has not stamped.

end(tx, graduationId, cause, today, actor, effects, reason?) is idempotent (a revoked or already-ended row is left alone) and, once it actually ends access:

1. Removes every scope_kind = 'student' role grant from the user, unconditionally — a grant left behind would hand full pupil-portal reads back to anyone who later gets a login for another reason (hired as staff, or becoming a parent). Their ids are stored on revoked_role_ids so a re-opening grants back exactly those.
2. Detaches any live session's active_role_id before deleting the grant (session.(user_id, active_role_id) is ON DELETE SET NULL on both columns and user_id is NOT NULL, so deleting a grant a session is currently acting as would otherwise fail the delete).
3. Switches users.can_login off — through writeCanLogin, the same guarded write PeopleAccountService.setSignIn uses — and deletes every session, but only when the account holds no other live profile (holdsOtherAccess). A graduate who is also a guardian or staff member keeps their login.
4. Records GRADUATE_ACCESS_ENDED through ActivityRecordService, deferred until the transaction commits, with the cause, whether sign-in was disabled, and the revoked role ids.

Re-opening (setUntil moving the date back into the future, or undoForRevoke when a rollover realignment undoes the graduation itself) gives back exactly what end took, and no more:

• Pupil-scope role grants come back only for roles that still exist, are still scope_kind = 'student', and are not superadmin — a role edited wider or deleted since revocation is not silently handed back, and the skip is logged.
• Sign-in comes back only when end is what switched it off (login_disabled_by_expiry) and the caller may decide sign-in (Users_UPDATE) and the account has not gained other access since — an account that picked up another profile while dormant is not quietly re-activated by a graduate-access change; turning its sign-in on is an explicit setSignIn decision instead.

Lock order is always student_graduations → users, matched by PeopleAccountService.setSignIn, which clears the login_disabled_by_expiry flag before touching users — see the sign-in toggle interaction below. The expiry sweep chooses its candidates without a lock, so end(..., "expiry") re-checks the window has really passed once it holds the row, in case an administrator extended it in between.

The sign-in toggle interaction. PeopleAccountService.setSignIn — the service behind the ordinary POST/DELETE /:entity/:id/sign-in routes — calls clearGraduateLoginFlag before writing users.can_login, whichever direction the toggle moves. That clears login_disabled_by_expiry on any live graduation for that user, so an administrator's explicit sign-in decision permanently overrides the automatic bookkeeping: a later re-opening of the graduation window never flips sign-in back on top of a decision a human already made.

Guardian visibility. graduate-access.query.ts exports the read-side helpers the other four modules use: graduateAccessEnded(studentIdColumn, today) is a SQL predicate — a live graduation with portal_access_ended_at IS NOT NULL or portal_access_until < today. The guardian portal's own-child resolution adds NOT graduateAccessEnded(...) to its identity filter, so once access has ended the child stops resolving as this guardian's child at all: the same 404 a stranger's child would produce, deliberately at the identity layer rather than the row-scope layer, because ending access is an audited lifecycle transition and not a record-keeping toggle. A graduate in grace — access ended in the future, not yet reached — is still visible; only ended removes them.

assertNotGraduatedReadOnly(executor, studentId, today) is the write-side guard the pupil's own portal calls, and only ever after the caller has already resolved the student through its own identity check (never on a raw id, which would let a 403 disclose that an arbitrary id belongs to a graduate). It throws STUDENT_GRADUATED_READ_ONLY when the pupil's state is grace or ended.

6.8 StudentGuardiansService

Validation order in writeGuardianLinks: every entry is inserted with is_primary = false first (a full pass), and only after every row exists is the primary flipped in a second statement — because student_single_primary_guardian is a non-deferrable partial unique index evaluated per row as the statement runs, and inserting a batch whose primary lands ahead of a row about to be deleted (in setGuardians's delete-then-reinsert) can raise 23505 depending on heap visitation order, which passes in a test and fails in production against a differently laid-out table. Response mapping: loadGuardians orders primary first (desc(isPrimary)), then by guardian id, so the "who does the office call first" position never depends on insertion order.

A student must have at least one guardian. assertGuardianSetValid refuses an empty guardian set outright, before the transaction opens, with 400 STUDENT_REQUIRES_ONE_GUARDIAN — "add a father, a mother or a local guardian." This runs on both POST /students and PUT /students/:id/guardians; an earlier version let an empty set through on PUT specifically, which deleted every existing link and committed, defeating the minimum on the one route whose entire job is the guardian set. It also checks that entries do not repeat a relationship slot, returning 400 GUARDIAN_SLOT_TAKEN naming the slot before the request ever reaches student_guardian_one_per_relationship's 23505.

6.9 StudentMedicalService

Two layers of authorization, both required: @Permissions("StudentMedical_READ") on the route (fails closed on the handler if absent), and PeopleAccessService.assertCanAccess(actor, "students", id, held) inside the service (answers "this specific child", which the route-level permission cannot). Response shape: never merged into StudentDto — a field that appears or vanishes by permission would make the response shape a function of authorization.

6.10 GuardiansService

translateGuardianError (module-level function, not a class method) unwraps error.cause before calling PersonWriterService.translate, because in this service's specific call sites the raw pg error's .constraint field is one level deeper than PersonWriterService.translate looks by default. Input normalization: organizationName is always recomputed as (dto.person?.firstName ?? current.firstName).trim() on update, even when neither kind nor person.firstName is present in the request body — because the pair must stay coherent with the CHECK regardless of which half of it a given PATCH touches. Response mapping: toDto emits version from versionOf(row.version), and update compares it under the row's FOR UPDATE before writing — a guardian is routinely shared across siblings, so two operators editing one family from two pupil records is the ordinary case rather than the unlucky one.

6.11 StaffService

ban/unban/sendPasswordResetLink first run the same object-level scope check every other :id method here does, then hand off to the shared PeopleAccountService exactly as StudentsService and GuardiansService do — staff is not a special case among the three profile kinds for any of these three actions.

Single-record responses carry roles for viewers who could change them. findOne, update, create and restore return StaffDetailDto: StaffDto plus roles — { publicId, name } for every role the person holds except guardian- and pupil-scope roles, sorted by name — present only when the viewer's active role holds Staff_UPDATE (PeoplePermissionsService.can, so a superadmin passes). For anybody else the key is absent, not empty: a teacher reading a colleague's record learns nothing about who holds what authority. update reads roles inside its transaction, so they are the roles the edit left. The list stays StaffDto and its cache key's shape token is unchanged.

Choosing roles is an identity change. Sending rolePublicIds on create, or roleSource on update, requires Users_UPDATE on top of the staff permission — checked with PeoplePermissionsService.can, the same line sign-in access is held at. The refusal is 403 PEOPLE_ROLE_NOT_PERMITTED. On create it runs before the transaction opens; everything else about the chosen roles runs inside it, so a refusal rolls the whole admission back.

grantStaffRoles runs after the staff insert succeeds, so a given designationId is already known to name a real designation — the foreign key on the row just inserted enforced that. It uses onConflictDoNothing on (user_id, role_id), reasoning that a brand-new user cannot already hold either role but a role-grant failure should not be what fails a whole admission if it somehow occurs. create is the only write method in this module with no row lock (FOR UPDATE) before reading the current state. update takes one, and checks the required version token under it, so two concurrent PATCHes to the same staff row cannot silently overwrite each other — the second is refused with 409 PEOPLE_STALE_RECORD.

A role edit runs inside the update transaction, after the staff patch. update checks roleSource/rolePublicIds pairing (400) and Users_UPDATE (403), then hands the rest to StaffRolesService.changeRoles (§6.11a). Any refusal rolls back the staff patch and the role change together. After commit, and only when the edit changed something, afterRoleChange writes one audit entry through ActivityRecordService.recordActivity — module: "Staff", action: "UPDATE", resource: { id: <staff id>, type: "staff" }, metadata: { rolesAdded: string[], rolesRemoved: string[] } (role names) — because the interceptor's own entry for the request cannot see the diff. When a role was removed it then calls RealtimeControlPublisher.closeUserStreams(userId) (§10). Both are best-effort and neither can fail a write that has already committed.

6.11a StaffRolesService

The one home for every staff role rule. DataTransferModule provides its own instance for the bulk import writer, so its constructor takes only Database and ActorAuthorityService; anything else it needs is passed in.

The scope rule. STAFF_EXCLUDED_ROLE_SCOPES = ["guardian", "student"] and isStaffAssignableScope(scopeKind) are exported from staff-roles.service.ts. A guardian-scope role sees the rows of the holder's children and a student-scope role the holder's own pupil rows; neither means anything for an employee. Every staff role path reads this one predicate: both pickers, the create and edit writes, the set an edit replaces, the detail roles, and RoleService.setRowVisibility (§6.1).

roleSource. Absent, an edit leaves roles exactly as they are — a designation change never re-derives them, and neither does StaffDesignationService.apply on the salary path. job makes the managed set the roles the designation after the edit implies; explicit makes it exactly rolePublicIds, replace-only, so staff is not added implicitly. Only the managed set is replaced: a guardian- or pupil-scope grant the person holds through another profile is neither shown nor removed.

The edit's check order, each refusal distinct (steps 1–2 in StaffService, 3–10 here):

Step 8 runs on removals as well as additions: an actor may not strip authority it does not itself hold, or emptying a peer's roles would act above the actor's own level. The superadmin role is checked by name and flag before any permission arithmetic, so emptying its grants never makes it assignable. A session acting as a removed role has its sessions.active_role_id nulled by the composite foreign key onto user_role (ON DELETE SET NULL (active_role_id), migration 0058); RoleGuard then refuses that session's next permissioned request with 403 AUTH_ACTIVE_ROLE_REQUIRED until it chooses a role. No permission cache needs invalidating: the cache is per role (rbac:role-perms:<roleId>), and JwtStrategy re-reads the person's roles on every request.

On create, rolePublicIds runs step 2 before the transaction, then the teaching check against the requested designation, resolveRequestedRoles, and assertMayAssignRole on every requested role. Without rolePublicIds, both create and the bulk import derive the job's roles non-strictly, logging and continuing when a seeded role is missing.

Lock order on an edit: the flagged principal designation (from PrincipalInvariantService), then staff FOR UPDATE, then users, then roles FOR SHARE, then the user_role rows, then the surviving superadmins' user_role rows FOR UPDATE inside assertNotLastSuperadmin. Two rare superadmin-only interleavings can still deadlock: an edit that changes a superadmin's person fields and removes their superadmin role, racing a ban of the same person (PeopleAccountService.ban locks the survivors first, then users); and two edits removing the superadmin role from two different superadmins at once (each locks the other's grant as a survivor, then deletes its own). Postgres aborts one side, and PersonWriterService.translate answers it as 409 PEOPLE_CONCURRENT_WRITE_CONFLICT; nothing was written and the request can be sent again.

6.12 StaffSalaryService

Validation order: the pair-coherence check only runs when basicSalary or allowances is actually present in the patch (touchesBasic/touchesAllowances) — a bank-detail-only PATCH never triggers it. Fail-closed: both methods re-check PeoplePermissionsService.can even though the route already declares the matching @Permissions, because the guard answers "may this actor call this handler," never "may this actor see this field," and the second question is the one that matters if either method is ever reached another way.

Once a staff member has any salary_assignments row, the salary module owns their pay. StaffSalaryService.find reads isManagedBySalaryModule(staffId) (a plain EXISTS against salary_assignments) and returns it as managedBySalaryModule on StaffSalaryDto, so the panel's salary form can render these fields read-only once the salary module has taken over. mirrorFromAssignment is the ONLY path allowed to write basic_salary/allowances on the staff row from that point on — called by SalaryAssignmentWriter inside its own transaction on every effective salary change, never by StaffSalaryService.update directly; a stop mirrors 0/0. A PATCH to these fields through StaffSalaryService.update once the staff member is salary-module-managed refuses with STAFF_SALARY_MANAGED_BY_SALARY_MODULE.

Staff deletion is refused while pay or a school asset is still attached. PeopleDeletionService.assertStaffHoldsNothing (apps/api/src/modules/people/shared/people-deletion.service.ts) takes the same per-staff advisory lock the salary assignment writer uses (SALARY_STAFF_LOCK_NAMESPACE), then checks in one query: an effective (non-stop) or scheduled salary_assignments row, an unsettled salary_payslips row (draft, or approved with payment_status <> 'paid' and a non-zero net), and any assets row whose custodian_staff_id is this staff member. Any one of those throws STAFF_HAS_ACTIVE_PAY_OR_ASSETS naming which condition held in details (effectiveSalary, scheduledSalaryChange, unsettledPayslips, assetsInCustody) — a soft delete fires no ON DELETE, so without this check payroll would keep paying, and the asset register would keep crediting, somebody the rest of the system says is gone. Stop their pay and return their assets first.

6.13 PrincipalInvariantService

At most one live, active staff member may hold the designation flagged is_principal in designations. This cannot be a database constraint: an index predicate cannot contain a subquery, so Postgres has no way to express "at most one row whose designation is the flagged one." The alternative would have been a denormalised staff.is_principal column maintained by every write path, with nothing in the schema tying that copy to its source — the two could desynchronise silently and no constraint would catch it. apps/api/src/modules/people/shared/principal-invariant.service.ts is the single locked write path taken instead, and there is no backstop: a write path that forgets to call it does not produce an error, it produces two principals and a report card signed by whichever row a query happens to return.

The five verified write sites that call assertSinglePrincipal, per the service's own docblock:

1. Staff create — an INSERT, which no UPDATE-shaped guard would cover.
2. Staff update — the designation patch.
3. Bulk import — designation resolved by name, bypassing StaffService entirely.
4. Restore of a soft-deleted ex-principal.
5. Employment status returning to "active".

Sites 1, 2, and 5 are three different transitions reachable through only two methods (create, update); the count of transitions and the count of call sites are not the same number, and both matter for different reasons — the transitions are what the tests name, the sites are what must remember to call this.

PrincipalCandidate is the resulting state of the write, never the raw DTO. PATCH { employmentStatus: 'active' } carries no designationId and PATCH { designationId } carries no employmentStatus, so every caller resolves dto-over-current-row into a PrincipalCandidate before calling assertSinglePrincipal. Passing the DTO's own values straight through would let either transition slip past the guard undetected: a status change that reactivates a principal, or a designation change on someone already active.

The lock order is fixed and load-bearing. The flagged designations row is always locked first, before any staff row, on every path — including restoreProfile, which already takes FOR UPDATE on the profile row and is careful to call this before that lock is taken. Reversing the order on any one path would have that path lock staff-then-designations while the others lock designations-then-staff, and two operators racing on one staff row would deadlock with an unmapped 40P01.

The INSERT-path exclusion is deliberate, not an oversight. Step 5 of assertSinglePrincipal excludes the candidate's own staff id from the "does someone else already hold it" query — but only when candidate.staffId !== null. On the create path staffId is null (there is no id yet), and the exclusion clause is omitted entirely rather than compared against null, because id <> NULL evaluates to NULL in SQL for every row, which would make the query return nothing and let this assert silently never fire on the one path that has no other backstop.

resolvePrincipal uses the exact same predicate as step 5 of assertSinglePrincipal — flagged designation, deleted_at IS NULL, employment_status = 'active' — deliberately. Resolving the school profile's principal by any looser rule (for example, ignoring employment_status) could display a principal the assert would not count as one, and the two would silently disagree about who holds the role.

Missing the flagged designation is refused, not treated as "nobody is principal." If no designations row has is_principal = true, FOR UPDATE matches nothing and therefore locks nothing — proceeding as if the invariant were satisfied would enforce it against nothing while reporting success, which is worse than either allowing or refusing outright. Both the migration and the seed path are expected to write this row; a database missing it is treated as misconfigured (409 PRINCIPAL_DESIGNATION_MISSING), not merely empty.

Assigning the Principal designation moves the staff member into that designation's department. The composite foreign key staff_designation_in_department_fk — (department_id, designation_id) → designations(department_id, id) — rejects any staff row whose department does not match its designation's department, so a write that sets designationId to the flagged row without also setting the matching departmentId is rejected at the database rather than silently filed under the wrong department. This is exactly why assertSinglePrincipal returns { principalDepartmentId } when it is the caller's write taking the designation: the caller uses it to set department_id in the same write, rather than leaving the caller to separately look up which department the Principal designation belongs to.

Two designation-level guards exist solely to protect this mechanism, documented in the school module: LookupsService.updateDesignation refuses to retire the flagged designation (PRINCIPAL_DESIGNATION_RETIRE_FORBIDDEN) and LookupsService.deleteDesignation refuses to delete it (PRINCIPAL_DESIGNATION_DELETE_FORBIDDEN) — see the school module's backend doc. Both exist because retiring or deleting the flagged row would silently strand assertSinglePrincipal's lock target and resolvePrincipal's join target, with no designation left to appoint a successor to.

6.14 StaffDesignationService

No HTTP route — apply(tx, staffId, departmentId, designationId, actor) runs only inside another write's own transaction, currently the salary module's promotion/demotion path. It moves a staff member's department_id/designation_id in the CALLER's transaction, so a change of pay and a change of post commit together or not at all — a promotion that changed the designation but failed to also record the salary change (or vice versa) would leave the staff record and the pay record disagreeing about which post this person holds. It locks the staff row FOR UPDATE first, then calls PrincipalInvariantService.assertSinglePrincipal with exactly the lock order StaffService.update uses for an ordinary edit (the flagged designations row before the staff row), so a promotion racing an unrelated staff edit never deadlocks by taking that order in reverse. It invalidates the staff:* cache the same way every other staff write does.

6.15 PeopleSummaryService

Headline people counts for GET /api/people/summary.

• Scope. Each section applies PeopleAccessService.scopeFor and applyScope for its own roll, the same predicates the matching list uses. wholeSchool is scopeFor(actor, "students", held).kind === "all".
• Optional sections. staff and guardians are computed only when PeoplePermissionsService.can reports Staff_READ and Guardians_READ respectively; otherwise they are null and no query runs.
• Students. activeEnrolled counts distinct pupils with record_status = 'active' and an active enrolment in the current session; it is null with no current session. admittedThisMonth counts admission_date between the month bounds. Soft-deleted students and users are excluded.
• Staff. employed counts employment_status in (active, on_leave, suspended); teaching narrows that to designations with is_teaching. The designation join is a left join.
• Guardians. total counts live guardian rows with live users.
• Month. currentMonthBounds(today) converts the school-local date to Bikram Sambat and returns the month's first and last day as Gregorian dates. A converter failure falls back to the Gregorian month with bsYear and bsMonth null.
• Cache. Sections are cached for 60 seconds through cacheGetFast and cacheSetFast (see §8).

7. Runtime Flows

7.1 Admit a student (create)

Success path, validation failures, missing entity (n/a on create), duplicate request (no idempotency key — a retried request creates a second student unless the caller supplies and relies on its own admissionNumber), cache miss/hit (list cache is always a miss immediately after this write, by design), async enqueue (the invitation email only, and only when sign-in was granted — enqueued transactionally through the outbox rather than fired after the commit, so it cannot be lost to a restart between the two), race/concurrency (the admission-number allocation is race-safe via the atomic upsert; two simultaneous admissions never collide), guest vs. logged-in (not applicable — every route here requires a JWT).

7.2 Update a student (PATCH, with optimistic concurrency)

7.3 Replace a student's guardians

7.4 Soft delete and restore

Restore mirrors this in reverse, with two additional checks (assertCodeStillFree, assertEmailStillFree) before any write, both raising a named conflict rather than an unmapped 23505.

7.5 Field-gated read (salary / medical)

Cache miss and cache hit: neither salary nor medical reads are cached — both query Postgres directly on every call, since they gate individual fields rather than a list. Race/concurrency: StaffSalaryService.update's pair-coherence check reads current and then writes in two separate statements (no row lock), so two concurrent salary PATCHes that each independently satisfy the pair check against a stale current can together leave the pair incoherent — the database's own staff_salary_pair_coherent CHECK is the actual backstop here, and a caller that races this way gets an unmapped 23514 translated through the generic driver-error path rather than the named VALIDATION_FAILED.

8. Caching

Explain:

• Deterministic segment order. CacheKeyUtil.build joins segments in the exact array order given, and every list method supplies the same segment order on every call — the key is a pure function of the filters, never dependent on object property iteration order.
• Cache hit behavior. getSoft deserializes the JSON blob and returns it directly — no re-validation against the current permission set happens on a hit, which is exactly why viewTag must be part of the key rather than checked after the fact.
• Cache miss behavior. Falls through to queryList (wrapped in withSearchThreshold if a search term is present), then setSofts the result before returning.
• Serialization shape. Plain JSON.stringify — dates serialize to ISO strings; a consumer reading a cached hit gets Date-shaped strings exactly as JSON.parse on the controller boundary would produce anyway, since Nest's own response serialization does the same.
• Invalidation on mutations. Every write method in all three services calls a private invalidate() that sweeps the entity's entire *:* prefix — never a single targeted key, because the key space includes up to eleven independent filter dimensions and is not enumerable from the write site.
• Failure handling. Both getSoft (returns null, logged as a warn) and delPatternSoft (logs a warn, does not throw) are fail-soft. A setSoft failure is likewise swallowed. None of the three ever turns a Redis outage into a failed request; the tradeoff is a stale list for up to 120 seconds after a failed invalidation.

Summary reads are time-bounded. The three summary keys are read with cacheGetFast (apps/api/src/common/utils/cache-race.util.ts), not getSoft alone. The shared Redis client queues commands while disconnected instead of rejecting them, so an awaited read would hold the request open through an outage. cacheGetFast races the read against a 250 ms budget and treats a timeout, an error or a miss identically: the service computes from the database. cacheSetFast writes without awaiting, so a slow or lost write costs the next reader a miss and never delays the response. The staff and guardian sections are skipped entirely, with no Redis call, when the caller lacks the matching read permission. wholeSchool, the session name and the month are recomputed on every request.

The scopeTag/viewTag pair (built by PeopleAccessService.cacheTags) is folded into every one of the three list keys above. scopeTag is "all" for an unrestricted actor or u:<userId>:r:<activeRoleId> for a restricted one — keyed on the (user, active role) pair, not the user alone, because one person can hold two restricted roles (a student who is also a sibling's guardian) and a user-only tag would serve their guardian-scoped result after they switch to acting as a student. viewTag is the sorted, comma-joined list of held field-gate permissions (StaffSalary_READ, StudentMedical_READ) or the literal string "base" if neither is held — its absence from a cache key was the specific defect this field exists to prevent: an HR user's staff list and a teacher's staff list would otherwise share one key, and whichever request populated the cache first (protected by getOrSet's lock in the general case, though these three list methods use plain getSoft/setSoft rather than getOrSet) would serve its rendering to the other by design, not by race.

9. BullMQ, Schedulers, and Async Work

None. Every write in this module is synchronous within the HTTP request — there is no queue producer, no processor, and no scheduled job anywhere in apps/api/src/modules/people/. Password-reset email delivery (AuthEmailService.sendPasswordResetEmailSafe) is called synchronously and is fail-soft on delivery failure, but it is not queued.

10. Realtime and Events

No Socket.IO gateway, no emitted domain event and no realtime room. One realtime control message:

• Trigger. StaffService.update, after the transaction commits, when a role edit removed at least one role.
• Publisher. RealtimeControlPublisher.closeUserStreams(userId), from RealtimeControlModule (modules/realtime/shared/realtime-control.module.ts). PeopleModule imports that module and never RealtimeSharedModule: the data-transfer worker imports PeopleModule, and the shared module would start a stream subscriber there.
• Message. { kind: "close-user", userId } on the Redis channel realtime:control (REALTIME_CONTROL_CHANNEL). It is not an outbox event and is not in realtime.contract.ts.
• Effect. Every API instance's RealtimeStreamService ends that person's open event streams. An open stream filters on the permissions it resolved at connect time; ending it makes the browser reconnect and resolve the permissions the person holds now.
• Failure. Best-effort. The publisher's own connection has no offline queue and a 2-second command timeout, so during a Redis outage the publish fails at once, is logged at warn, and the PATCH still answers 200. A lost message leaves that person's streams on their old permissions until they next reconnect. No queue, outbox row or retry is involved.

The realtime module's own pages describe the channel and the stream's attach re-check.

11. Security, Auth, and Abuse Controls

• Guards. Every controller in this module carries @UseGuards(JwtAuthGuard, RoleGuard) at the class level — there is no public or guest-accessible route anywhere in /students, /guardians, or /staff.
• Permissions. Every handler declares @Permissions(...); RoleGuard's fail-open branch (for handlers declaring no permission at all) is scoped to non-admin surfaces only, and /students, /guardians, /staff are all classified as admin surfaces by isAdminSurface (anything not under /mobile), so a handler here that forgot @Permissions() would be refused outright rather than silently allowed.
• Object-level authorization. PeopleAccessService is the second, mandatory layer beneath every :id route — see §6.1. A route-level permission alone cannot express "this specific child's guardian may see this specific child."
• Account-action authorization. A third, orthogonal check gates ban, unban, and sendPasswordResetLink on all three entities: ActorAuthorityService.assertMayActOnAccount refuses a non-superadmin acting on any account that holds the superadmin role, reading the target's full role set rather than their currently active one, so a superadmin cannot be suspended, restored, or sent a reset link by an office clerk merely because that clerk holds the entity's _UPDATE permission and the target happens to be acting as something else in the current session. Self-targeting is exempt from this check — the specific self-actions that are dangerous (banning yourself) are refused by name where they occur, not by this gate. The same check protects the generic /users/:id/ban/:id/unban routes in the users module, since those reach accounts — a superadmin with no student, parent, or staff profile at all — that the people screens never see.
• Guest identity. Not applicable — no route in this module accepts an unauthenticated or guest caller.
• Admin identity. AuthUser.activeRole (resolved fresh per request by JwtStrategy) is the sole discriminator for both permission checks and object-level scope; activeRole.isSuperadmin — a boolean column exposed through no DTO and writable through no route — is the universal-access bypass, deliberately never keyed on a role's mutable name.
• Rate limits. None specific to this module observed; whatever global throttling apps/api applies elsewhere is inherited, not configured here.
• Anti-abuse rules. The 404-not-403 rule (§6.1, and the feature doc's business-rules table) is this module's primary anti-enumeration control — it denies an attacker the ability to distinguish "exists but not yours" from "does not exist" across a roll of children.
• Input normalization. PersonWriterService centralizes trimming and blank-to-null conversion for every text field written to users; email is additionally lower-cased before comparison and storage (emailNormalized).
• Sensitive data redaction. Salary and health fields are omitted from their base DTOs entirely (never nulled — see §16.5); PeopleAccountService.sendPasswordResetLink's log line names the kind and profile id, never the email address or the issued token.
• Identity changes are gated apart from record changes. Granting sign-in access — on create through grantSignIn/person.canLogin, or afterwards through POST /:id/sign-in — requires Users_UPDATE, never the profile-kind permission. A login-capable row carrying an email address is a route to a session, because POST /auth/password/forgot is @Public(). Revoking through DELETE /:id/sign-in additionally deletes every session the person holds. Choosing a staff member's roles — rolePublicIds on POST /staff, roleSource on PATCH /staff/:id, and both role pickers — requires Users_UPDATE for the same reason.
• Role escalation. Every staff role write refuses guardian- and pupil-scope roles, runs assertMayAssignRole on every role it adds and every role it removes, refuses the actor's own record and — unless the actor is one — a superadmin's, and protects the last superadmin who can sign in (§6.11a).
• Audit logs. No dedicated audit table for this module. PeopleAccountService.ban records banned_by on the users row itself, which is the only durable "who did this" trace for a suspension. A staff role edit that changed something writes one Mongo audit entry naming the roles added and removed (§6.11), beside the interceptor's own entry for the request.
• Fail-closed behavior. assertNotLastSuperadmin, assertMayActOnAccount, the version check, the guardian-with-live-children check, and every permission/scope check are all fail-closed — none has a fallback path that proceeds on ambiguity or error.

13. Error Handling

14. Observability

15. Testing and Validation

Validation commands:

pnpm --filter @skoolsewa/api test -- students.service.integration.spec.ts
pnpm --filter @skoolsewa/api test -- guardians.service.spec.ts
pnpm --filter @skoolsewa/api test -- staff.service.spec.ts
pnpm --filter @skoolsewa/api build
pnpm turbo run build:docs

16. Mandatory Backend Deep-Dive Pack

16.1 Submodule Coverage Matrix

Every file in apps/api/src/modules/people/ that affects runtime behavior is represented above; dto/index.ts, students/index.ts, staff/index.ts, and the various dto/index.ts re-export barrels carry no logic and are intentionally omitted as non-runtime.

16.2 UML and Architecture Diagram Pack

Component diagram:

Class diagram (representative — the students subtree):

ER diagram: §5.3 above.

Sequence diagrams: §7.1-§7.5 above.

State diagram: §7 of the feature doc (profile liveness / login).

Deployment/runtime diagram:

No BullMQ, no realtime gateway, and no external service call exists in this module's runtime path — the deployment diagram above is deliberately smaller than the generic template because there is nothing more to show.

Data lineage diagram (an admission, from request to response):

16.3 Code Flow Narrative

StudentsService.create(dto)

Auth/identity assumptions: create takes no actor parameter at all — it is reachable only because StudentsController.create is gated by @Permissions("Students_CREATE") at the route, and creation carries no object-level scope question (there is no existing row to be "out of scope" of). Logs/metrics/audit: none emitted by this method itself. Known tradeoffs: no idempotency key, so a client-side retry after a network timeout with no supplied admissionNumber can create two students for one admission event; the office's own process (checking the roll before resubmitting) is the only safeguard today.

16.4 Data Layer Deep Dive

Every table's field-level detail, indexes, and constraints are given in full in §5.2 above; this section adds what that section's format does not have room for.

• Ownership. users is owned by the identity schema (outside this module) but every column this module writes is enumerated in PersonColumns/PERSON_SELECTION; students, guardians, staff, student_guardian, and code_counters are owned entirely by this module.
• Versioning fields. students.version, guardians.version and staff.version are the optimistic-concurrency tokens, rendered by versionOf/matchesVersion in shared/row-version.ts and compared against the client-supplied version on every profile PATCH. Each is a counter maintained by the bump_row_version BEFORE UPDATE trigger, which also stamps updated_at; no application code increments it. updated_at is not a versioning field — it was, and a millisecond-resolution timestamp let two writes in one millisecond share a token.
• Audit fields. users.banned_by is the only actor-attribution column in this whole data model; no table carries a general created_by/updated_by.
• Money units. staff.basic_salary, .allowances, .total_salary are numeric (exact decimal), never float/double precision, and travel over the API as decimal strings (StaffSalaryDto's fields are typed string | null) — a numeric value does not survive a JSON-number round-trip without precision loss.
• Timezone and date interpretation. admission_date/joining_date are plain date (no time-of-day, no zone). The one place a timezone genuinely matters is code allocation, where the year is taken via Intl.DateTimeFormat against SchoolProfileService.getTimezone(), never Date.getFullYear().
• JSON schema examples. No JSON/JSONB column exists anywhere in this data model — every field is a scalar, an enum, or a foreign key.
• Migration history. Not independently inspected for this documentation pass; the schema files above are read as the current, authoritative shape.
• Seed data dependency. guardians.create and staff.create both depend on the five system roles (superadmin, staff, teacher, guardian, student) existing in role — seeded by seed-auth.ts. A guardian-role lookup miss throws ROLE_NOT_FOUND (500) rather than silently skipping the grant.

Index rationale table:

16.5 Business Logic and Invariant Catalog

16.6 Tradeoffs, Alternatives, and ADR Notes

16.7 Operational Runbook

16.8 Backend Risk Register

17. Zero-Omission Backend Checklist

• Every file in the module directory is represented or explicitly marked non-runtime — §4, §16.1.
• Every controller, service, provider, processor, scheduler, helper, mapper, DTO, enum, and schema is documented — §4, §5, §6, §16.1.
• Every method with business behavior has a code-flow narrative — §6 (per-method tables), §16.3 (the representative narrative for create).
• Every table/collection/cache object/job payload has field-level detail — §5.2, §8 (no job payloads exist).
• Every index, constraint, relation, and delete behavior has rationale — §5.2, §16.4.
• Every lifecycle/status transition has a state diagram and transition table — feature doc §7 (referenced; this domain's lifecycle is documented once, in the feature doc, to avoid duplicating the same table).
• Every read/write/action/job flow has sequence and activity diagrams — §7, §16.2 (no job flows exist to diagram).
• Every business invariant is cataloged — §16.5.
• Every cache key, invalidation path, queue job, realtime event, and external call is documented — §8, §9 (none), §10 (none), §11.
• Every architectural tradeoff is documented with alternatives and revisit triggers — §16.6.
• Every operational failure mode has a runbook entry — §16.7, §16.8.

18. Backend Completion Checklist

• Module boundaries are documented — §2.
• Every controller, service, DTO, schema file, job, cache key, and event is covered — §3-§6, §8-§10.
• Every database table/collection has a field table and relationship diagram — §5.2, §5.3.
• Every runtime flow has a diagram and branch notes — §7.
• API, feature/flows, and TDD docs are linked — See Also, below (no TDD doc exists for this module in this repository).
• No claim is made without a source file or documented source reference — every table and narrative above cites the file it was read from.

Profile roles are granted wherever a profile is created

Every pupil holds the seeded student role and every guardian the seeded guardian role, from the transaction that creates the profile. PeopleAccessService.scopeFor and every portal route switch on the active role's scopeKind, so a profile with no role falls to the self default: once given sign-in, that person logs in and reaches nothing, with no error saying why.

One function grants them, grantProfileRole (shared/profile-role.ts), and every creation path calls it in its own transaction:

Staff get staff, plus teacher for a teaching designation, from StaffRolesService.grantStaffRoles on both the API and the import path, unless POST /staff names the roles explicitly. That path logs and continues when a seeded staff role is missing; only an edit with roleSource: "job" refuses (500 ROLE_NOT_CONFIGURED). Staff are never given a guardian- or pupil-scope role through a staff surface — §6.11a.

The grant throws ROLE_NOT_FOUND (500) and aborts the whole write when the role is not seeded, rather than skipping. A silent skip would produce a 201, a correct-looking record and no access at all, with nothing connecting the two events. It is idempotent on (user_id, role_id).

The grant is narrow: student carries scope_kind = 'student', which resolves to the pupil's own record and their own guardians, and guardian resolves to the guardian's own children. Neither holds an admin-catalogue permission.

Two migrations repair rows written before a path granted the role. 0013_student_role_backfill covers pupils admitted before admissions granted it; 0042_profile_roles_backfill covers pupils and guardians written by the import or the pupil form. Both include soft-deleted profiles, because restoring a profile clears its deletion marks and never touches user_role. 0042 skips any pupil with a student_graduations row: graduate access revokes the pupil-scoped roles itself and only its own restore path hands them back.

See Also

• API doc: /docs/developer/people/api
• Features and flows doc: /docs/developer/people/feature