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

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.

5.3 Relationship Diagram

6. Services and Responsibilities

6.1 PeopleAccessService

Superadmin (activeRole.isSuperadmin) and holding the entity's own Module_READ permission both resolve to { kind: "all" }. Otherwise the active role's name decides: guardian and student get bespoke restricted predicates; everything else (including staff/teacher without the module permission, and anyone with no active role) gets selfOnlyScope, which is sql\false`for every entity exceptusers/staff` where it resolves to the actor's own row.

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"), 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, never a truncating fixed width (lpad('10000', 4, '0') returns '1000', which this code avoids via padStart, which only pads and never truncates).

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.

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.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.

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.

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.

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.

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.

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

None. No Socket.IO gateway, no emitted domain event, and no realtime room is referenced anywhere in this module.

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.
• 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.
• 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.

The admission-time role grant

StudentsService.create writes a user_role row granting the pupil the seeded student role, inside the same transaction as the admission. Guardians and staff have always received their roles on creation; pupils did not, so every pupil in the database had no active role and the consumer portal refused them.

The grant throws ROLE_NOT_FOUND (500) and aborts the whole admission 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.

The grant is narrow: student carries scope_kind = 'student', which resolves to the pupil's own record and their own guardians, and the role holds no admin-catalogue permission. A pupil moves from holding no role and reaching nothing, to holding a role scoped to themselves.

Migration 0013_student_role_backfill covers pupils admitted before this change. It deliberately does not filter deleted_at, because restoring a soft-deleted pupil does not re-grant the role — restoreProfile clears the deletion marks and never touches user_role.

See Also

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