People - API Reference

Audience: Frontend engineers, mobile engineers, backend engineers, QA, and API consumers. Scope: Admin-facing APIs owned by PeopleModule (StudentsController, StaffController) and its nested GuardiansModule (GuardiansController). No public or mobile-facing route exists in this module.

1. Documentation Evidence

2. Module Summary

3. Concepts and Terminology

4. API Surface Map

41 routes total (16 on StudentsController, 12 on GuardiansController, 13 on StaffController) — verified against the complete contents of all three controller files. The six :id/sign-in routes are the only ones in this module that ask for Users_UPDATE rather than a profile-kind permission: granting somebody sign-in access creates a credential-bearing account rather than editing a pupil record, and POST /api/auth/password/forgot is public, so an email address on a login-capable row is a route to a session. No alias routes exist. guardian-lookup is declared before :id on StudentsController deliberately, or Nest would match it as a student id.

5. Auth, Identity, and Permissions

Two layers of authorization apply to every :id route, and both are load-bearing:

• Layer one — @Permissions() / RoleGuard. Answers "may this actor call this handler at all". Resolved from the caller's active role only, never the union of every role held — a teacher who is also a guardian, viewing as Guardian, does not carry staff permissions into that context. A role with is_superadmin = true bypasses the permission list entirely, keyed on the boolean flag rather than the role's name (a mutable text column a rename could otherwise turn into an escalation path). A caller with no active role — either no role at all, or several with none chosen — is refused 403 PERMISSION_ROLE_NOT_ASSIGNED or 403 AUTH_ACTIVE_ROLE_REQUIRED respectively, before this module's own logic ever runs.
• Layer two — PeopleAccessService.assertCanAccess. Answers "may this actor read/write this row". Superadmin always gets unrestricted scope. The order of the next two checks is load-bearing and deliberately role-name-first, not permission-first: an active role literally named guardian or student is scoped to that role's restriction (guardian sees their own children and those children's co-guardians; student sees their own record and their own guardians) before the module permission is ever consulted — holding Students_READ/Guardians_READ on top of a guardian/student role does not widen it to all. Only for a role named anything else does holding the module permission grant all; failing that, the caller sees only their own profile row. The restricted predicate is always ANDed inside the SQL, never filtered after the fact — filtering afterward would page over rows the actor cannot see and under-report count.

Why the ordering matters, concretely: the reverse ordering (permission checked first) was tried and reverted — checking the module permission before the role name made both portal branches unreachable, because every route reaching this method is already gated on that same permission by RoleGuard. The failure it produced was not theoretical: an administrator builds a "Parent Portal" role, grants it Students_READ so parents can see their own children, and assigns it to the guardian cohort — under the permission-first ordering every parent holding that role then received every pupil's name, date of birth, home address, and phone number from GET /students, with no error anywhere and a green test suite, because the guardian-scope branch was dead code. Role-name-first is what the code does today and is what closes that path.

A record outside the caller's scope answers 404, never 403, carrying the entity's own *_NOT_FOUND code (STUDENT_NOT_FOUND, GUARDIAN_NOT_FOUND, STAFF_NOT_FOUND) — byte-for-byte identical to a genuinely absent id. A 403 would confirm the record exists, turning the id space into an enumeration oracle against a roll of children. There is deliberately no NOT_YOUR_RECORD code; its existence would be the leak.

Sign-in access is gated on Users_UPDATE, not on the profile-kind permission. The six :id/sign-in routes, and the create-time grantSignIn/person.canLogin flags, all ask for the same identity permission whatever the profile kind — Students_CREATE alone cannot mint a login-capable pupil, and Staff_UPDATE alone cannot give a caretaker a portal account. The reason is that POST /api/auth/password/forgot is public: a login-capable row carrying an email address is a route to a session, so granting one is an identity change rather than a record edit. resolveSignInGrant resolves the create-time decision through PeoplePermissionsService.can, which lets a superadmin bypass — 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.

Field-gated groups are checked twice. StaffSalary_READ/StaffSalary_UPDATE and StudentMedical_READ/StudentMedical_UPDATE are declared on the route via @Permissions(), and checked again inside StaffSalaryService/StudentMedicalService via PeoplePermissionsService.can — because the guard answers "may this actor call this handler", not "may this actor see this field", and the second question is the one that matters if either method is ever reached another way. A caller who reaches the handler but somehow fails the in-service check gets 403 PERMISSION_INSUFFICIENT.

None of the five people-domain permission modules (Students, Guardians, Staff, StaffSalary, StudentMedical) is held by any of the five seeded roles except superadmin by default — a school creates an administrator role that holds them explicitly. Staff and teacher are seeded with Students_READ/Guardians_READ/Staff_READ only (read-only directory access), per STAFF_PERMISSIONS in seed-auth.ts (see the feature doc's actor matrix). PersonClassifications_READ is the one exception seeded to staff and teacher alongside those three — both the student and staff person forms render an ethnicity and a mother-tongue select, and a colleague who cannot read the lists sees two empty boxes with no way to tell it is a permissions problem rather than an empty table; the write codes (PersonClassifications_CREATE/_UPDATE/_DELETE) stay administrator-only.

Headers parsed but not trusted: not applicable — no route in this module reads any identity-bearing header other than the standard Authorization: Bearer <jwt> consumed by JwtAuthGuard.

Malformed :id behaves differently by controller. StudentsController and StaffController apply ParseUUIDPipe to every :id param, so a non-UUID id is refused with a clean 400 VALIDATION_FAILED before any query runs. GuardiansController applies no such pipe to any of its eight :id routes — a malformed id reaches guardians.id = '<value>' as a raw comparison against a uuid column, Postgres raises invalid input syntax for type uuid (SQLSTATE 22P02), and AllExceptionsFilter — which only special-cases 23505 — falls through to a bare 500 SYS_INTERNAL_ERROR. A consumer building against GuardiansController should validate UUID shape client-side rather than relying on the API to reject it cleanly.

6. DTO and Model Reference

6.1 PersonDto (response — the identity block on every profile)

ethnicityId and motherTongueId round-trip: accepted on write via PersonInputDto (below), and projected back by PERSON_SELECTION (person-writer.service.ts:272-322) on every student, guardian, and staff read. The matching name — ethnicityName/motherTongueName — comes back alongside each id as a read-only field, resolved by a correlated subquery against ethnicities/mother_tongues rather than a LEFT JOIN, because the shared projection is read by six separate list and detail queries and a join added at one call site would have to be replicated at all six in the same order or the response shape silently diverges between them. The id is returned because it is what an edit form posts back on the next PATCH; the name is returned because it is what a person reads — 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. Neither name is ever accepted on write: PersonInputDto has no ethnicityName/motherTongueName field, and sending one is rejected outright by the global ValidationPipe's forbidNonWhitelisted, which refuses any field the DTO does not declare.

6.2 PersonInputDto (request — nested under every create/update body's person field)

person.canLogin is a create-time grant, not an editable field. It is one of two accepted spellings of the same decision — grantSignIn on the create body is the other — and both are checked against Users_UPDATE before anything is written. Absent means no: a person created without either flag gets a record and no account. Sending both with different values is refused with 400 PERSON_SIGN_IN_FLAGS_CONFLICT rather than resolved by precedence, because the caller has stated two intentions and the server cannot know which one is the mistake.

PATCH never writes it. PersonWriterService.buildUpdate emits no canLogin key whatever the body contains, so a person's sign-in access is changed only through POST/DELETE /:id/sign-in (8.10a, 8.10b and their guardian and staff equivalents), which check the identity permission and guard the write. A guardian entry inside CreateStudentDto.guardians or SetStudentGuardiansDto.guardians reads both spellings the same way, and refuses the same contradiction (6.8).

Omitted is not nulled, on update. PersonWriterService.buildUpdate (shared/person-writer.service.ts:85-128) emits a key only for a field the caller's person object actually contains (Object.hasOwn, not !== undefined) — so an explicit "lastName": null clears the field, while an absent lastName key leaves the stored value untouched. On create every optional field not sent becomes NULL — there is no prior value to preserve. Every string field is trimmed server-side, and an empty string after trimming is stored as NULL, never as "".

6.1a AddressDto and AddressInputDto (a Nepali address)

Every person carries two of these — permanentAddress and currentAddress — in place of the old five flat columns (addressLine, street, city, state, pinCode).

AddressDto (response, nested under permanentAddress/currentAddress):

The names are returned alongside the ids on purpose, not for convenience. Geography rows are retired with isActive: false, so a form's pick list is active-only; a person whose district was retired after their record was written would otherwise find their district missing from the select, the field rendering blank, and the next save of any unrelated field silently clearing it — and the municipality fill-order CHECK would then clear the municipality too. Returning the resolved name lets a form keep the person's current value in its options whether or not it is still active. It also answers a portal question: guardian and student roles hold zero catalogue permissions by design, so denormalising the name here means no Geography_READ grant is ever needed just to render a family's own address.

AddressInputDto (request, nested under permanentAddress/currentAddress on write):

The group is replaced WHOLE, never patched field by field, and this is not optional. PersonWriterService.buildUpdate distinguishes an omitted key from an explicit null one level up (Object.hasOwn), but that discipline does not extend through nesting on its own. If permanentAddress is present anywhere in the request body, all six columns are written from it and a missing key inside it means NULL; if the key is absent from the body, the whole group is left untouched. Sending { "permanentAddress": { "provinceId": null } } therefore clears the entire permanent address, not just the province — sending { "provinceId": null, "districtId": null, ... } explicitly for every column achieves the same result more legibly. The alternative (patching only the sent sub-fields) 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 that looks perfectly reasonable to the caller.

An all-null currentAddress means NOT RECORDED, never "same as permanent." There is deliberately no boolean flag for that — a family that has not given a separate present address simply has six null columns, and a client rendering the form must not infer or copy the permanent address into it.

6.3 BanAccountDto (body — every POST /:id/ban)

A body of only whitespace (" ") passes @MinLength(1) but is refused server-side after trimming — see 8's ban entries.

6.4 PasswordResetSentDto (response — every POST /:id/password-reset)

6.4a GrantSignInDto (body — every POST /:id/sign-in)

The default is true because granting somebody an account and not telling them leaves them holding credentials they cannot use and no way to learn they have them. Send false to prepare an account and invite later; calling the same route again with invite: true sends the invitation then.

DELETE /:id/sign-in takes no body — there is nothing to choose when revoking.

6.4b InvitationOutcomeDto (response — inside SignInAccessDto and every create response)

sent: false always carries a reason. An outcome saying only that something did not happen is the one thing an operator cannot act on. The four values, and what a consumer should do about each:

On a create response only no_email can appear, because the other three describe states a person being created cannot be in.

sent: true means ENQUEUED, not delivered. The notification event and its outbox row are committed in the same transaction as the grant; whether the email reached anybody is carried by the delivery row, and an unconfigured provider or a bounced address shows up there rather than here. A consumer must not report "invitation delivered" from this field.

Note that the Swagger schema for this field declares no_email alone. The other three values are produced by the same responses; read InvitationSkipReason in people-invitation.service.ts as the authority.

6.4c SignInAccessDto (response — every POST/DELETE /:id/sign-in)

6.4d CreatedStudentDto / CreatedGuardianDto / CreatedStaffDto (responses — the three POST creates)

Each extends its read DTO — StudentDto, GuardianDto, StaffDto — and adds one field:

The three values a consumer must distinguish:

• null — sign-in was not granted, so there was never anything to invite anybody to. This is the ordinary case; most people on a roll have a record and no account.
• { "sent": true, "to": "..." } — access was granted and an invitation was enqueued to that address.
• { "sent": false, "reason": "no_email" } — access was granted, but the person has no email address. Add one and grant again through 8.10a to send the invitation.

The field lives on a separate class rather than on StudentDto/GuardianDto/ StaffDto, because those are also returned by the list, the detail read, the PATCH and the restore — an invitation there would be permanently null on four responses that never had one.

6.5 StudentDto (response)

StudentClassSummaryDto carries classId (the class publicId), gradeName, sectionName, shift (morning | day) and the optional class name. It deliberately carries no capacity or occupancy: those belong to the class, and the one screen that needs them reads /classes/options, the same endpoint the capacity chart uses, so the two cannot disagree.

medicalConditions, allergies, and specialNeeds are never present here — they live only on StudentMedicalDto, behind StudentMedical_READ, at 6.7. Confirmed by the integration test asserting Object.keys(student) excludes both.

studentId vs admissionNumber. The two look similar and are not interchangeable.

Because student_id is never reissued and is unique across every row a school has ever created, it is the identifier safe to hold in a transcript, a ledger entry, or any external system that must keep pointing at the same pupil forever — admissionNumber is not, because the exact same string can legitimately belong to a different pupil later if the original record was removed.

6.6 StudentGuardianLinkDto (response — one entry on GET/PUT /students/:id/guardians)

6.7 StudentMedicalDto (response and, structurally, the update shape — behind StudentMedical_READ/_UPDATE, never part of StudentDto)

6.8 UpsertStudentGuardianDto (body — one entry inside CreateStudentDto.guardians and SetStudentGuardiansDto.guardians)

A guardian granted sign-in through this nested entry is invited here too, in the same transaction as the pupil's admission — the flag would otherwise mean "account without an invitation" on this path and "account with one" on the three top-level creates, and a parent is the person most likely to actually use the login.

Both spellings are read here too — grantSignIn on the entry, and person.canLogin inside it — and a contradiction between them is refused with 400 PERSON_SIGN_IN_FLAGS_CONFLICT, exactly as on the three top-level creates. Honouring only grantSignIn would make one word mean two things on two paths, with this the path that silently discarded the other.

Neither guardianId nor person is itself marked required by a class-validator conditional — supplying neither reaches StudentGuardiansService.resolveGuardian, which throws 400 GUARDIAN_NOT_FOUND at runtime rather than a DTO-level VALIDATION_FAILED.

6.9 CreateStudentDto (body — POST /students)

6.10 UpdateStudentDto (body — PATCH /students/:id)

Moving a pupil's class through this endpoint. Sending classId enrols or transfers, in the same transaction as the rest of the edit, through the same enroll() the class roster uses — so the previous enrolment is closed as transferred and the same activity record is written. Three rules apply:

• There is no value that clears a class. Taking a pupil out of one with nowhere to put them is a withdrawal — it needs a date and a reason and it changes the class's roll — so it stays on DELETE /classes/:publicId/enrollments/:studentId.
• The class must belong to the current session, or the write is refused with ENROLLMENT_SESSION_NOT_CURRENT. POST /classes/:publicId/enrollments does not apply this rule: it names its class in the URL, so choosing another year there is deliberate. Without it this endpoint would return 200, write a second active enrolment in a session currentClass does not read from, and appear to have done nothing.
• version now covers the class. Every enrolment write touches students.updated_at, so a transfer made from the class roster invalidates an already-open pupil edit form and its save is refused with PEOPLE_STALE_RECORD rather than silently moving the pupil back.

Additional failures this endpoint can now return: CLASS_NOT_FOUND, CLASS_INACTIVE, CLASS_AT_CAPACITY (retry with allowOverCapacity: true), ENROLLMENT_SESSION_NOT_CURRENT, ENROLLMENT_DATE_OUTSIDE_SESSION, ENROLLMENT_DATE_BEFORE_ADMISSION.

Cannot rename/re-allocate admissionNumber through this endpoint — the field is absent from UpdateStudentDto entirely; the global ValidationPipe's forbidNonWhitelisted rejects an attempt with a plain 400, not a domain error. Cannot touch health fields here either — use PATCH /students/:id/medical. Cannot touch guardians here — use PUT /students/:id/guardians.

6.11 UpdateStudentMedicalDto (body — PATCH /students/:id/medical)

No version field — this endpoint carries no optimistic-concurrency check at all, unlike the main student PATCH.

6.12 SetStudentGuardiansDto (body — PUT /students/:id/guardians)

6.13 ListStudentsQueryDto (query, extends QueryDto)

pagination cannot be turned off here — StudentsService.findAll throws 400 PAGINATION_LIMIT_INVALID when query.pagination === false, the same code the guardians and staff lists use for the identical shape of refusal: an unpaginated roll of every pupil's name, date of birth, address, and guardians is the largest of the three tables, so it is refused before the scope predicate is even built, not merely bounded.

6.14 GuardianDto (response)

No version field. Unlike StudentDto, a guardian's PATCH carries no optimistic-concurrency token at all — see 6.17.

6.15 GuardianChildDto (response — one entry on GET /guardians/:id/students)

This is the same underlying student_guardian row as 6.6, read from the guardian's side of the relationship — the inverse view, not a different table.

6.16 CreateGuardianDto (body — POST /guardians)

6.17 UpdateGuardianDto (body — PATCH /guardians/:id)

No version field, and no optimistic-concurrency check of any kind. GuardiansService.update reads the current row, applies the patch, and writes — two concurrent PATCH requests both succeed, and the second's write silently wins with no 409 ever returned. organizationName is always recomputed on write, from whichever of dto.person.firstName or the row's existing firstName applies, whenever kind resolves to "organization" — not only when kind itself is present in the body, because the name must stay in sync with firstName on every edit that could change either half of the pair.

6.18 ListGuardiansQueryDto (query, extends QueryDto)

pagination cannot be turned off — GuardiansService.findAll throws 400 PAGINATION_LIMIT_INVALID if ?pagination=false, because the restricted-scope predicate is a subquery per row and an unpaginated read over the whole roll is the query this endpoint must never run. The students and staff lists refuse pagination=false with the same error code, for the same shape of reason.

6.19 StaffDto (response), with StaffDepartmentRefDto / StaffDesignationRefDto

Send version back on the next write. It is required by both PATCH /staff/:id and PATCH /staff/:id/salary, and both advance it — so a client that saves through both in one flow must send the token the FIRST call returned, not the one it loaded the page with. Its scope is the staff row: a concurrent edit to the person's users row through ban, unban, password reset or the users module does not move it.

basicSalary, allowances, totalSalary, and every bank field are never present here — behind StaffSalary_READ, at 6.20.

6.20 StaffSalaryDto (response and, structurally, the update shape — behind StaffSalary_READ/_UPDATE, never part of StaffDto)

version is returned by the salary write as well as the read, so a client saving through both staff routes can chain the second call off the first. updatedAt is not part of this response at all — the salary projection carries version and renders it as the token.

Both are free text with no format validation beyond a length cap — SSF numbering changed shape when the scheme opened and CIT numbers vary by the office that issued them, so a regex would reject a real employee's real number, and the office would work around it by leaving the field blank, which is strictly worse than storing what they were given.

Money is a decimal string in every direction — a consumer that parses it to a JavaScript number risks precision loss on a large payroll figure and must reserialize it as a string, byte-for-byte, on any subsequent write.

6.21 CreateStaffDto (body — POST /staff)

salary on POST /staff is gated on KEY PRESENCE, not on the actor's permission for its contents. StaffService.create calls StaffSalaryService.resolveSalaryForCreate(actor, dto.salary, wantsSalary), where wantsSalary is Object.hasOwn(dto, "salary") && dto.salary !== undefined — so sending "salary": {} (or any object) in the body from an actor who does not hold StaffSalary_UPDATE is refused with 403 PERMISSION_INSUFFICIENT, not silently dropped. This is deliberate: silently ignoring the key would make a rejected write indistinguishable from a successful one that simply had nothing to save, and an actor who cannot write pay must not be able to probe whether the key is even accepted by watching for a difference in behavior. Omitting the salary key entirely (not sending it at all) never triggers this check, resolves to null, and creates the staff member with no salary/bank columns set. basicSalary/allowances still travel together or not at all, exactly as on PATCH /staff/:id/salary. PATCH /staff/:id — the general staff edit endpoint — does NOT accept salary at all (absent from UpdateStaffDto, 6.22 below); the only way to change salary/bank details after creation is PATCH /staff/:id/salary, so the permission boundary for editing pay is crossed in exactly one place on the write side.

Sending designationId without departmentId is not caught by any validator in this DTO or in StaffService.create. It reaches the database as an INSERT with department_id = NULL, designation_id = <value>, which violates the staff_designation_needs_department CHECK constraint (people.ts:339-342) — a 23514 that PersonWriterService.translate has no case for, so it falls to the default: throw error as Error branch and surfaces to the caller as a bare 500 SYS_INTERNAL_ERROR, not a validation error. Always send both together, or neither.

6.22 UpdateStaffDto (body — PATCH /staff/:id)

No version field — see 6.19. The same staff_designation_needs_department gap applies here: clearing departmentId to null while leaving an existing designationId in place violates the CHECK identically and surfaces as an unmapped 500. Changing role grants is not this endpoint's job — employmentStatus is an HR fact about the job; it never touches the staff/teacher role grant, which is only ever assigned at POST /staff and never revoked or re-evaluated on update.

6.23 UpdateStaffSalaryDto (body — PATCH /staff/:id/salary)

PATCH /staff/:id/salary binds PatchStaffSalaryDto, not this class. PatchStaffSalaryDto extends UpdateStaffSalaryDto and adds one required field:

The token lives on the subclass and not on UpdateStaffSalaryDto because CreateStaffDto.salary is typed as UpdateStaffSalaryDto. Requiring a version there would reject every staff admission carrying pay — for a row that does not exist yet — and would turn the deliberate 403 for salary: {} without StaffSalary_UPDATE into a 400 about a missing field, since validation runs before the service.

@IsNumberString accepts any numeric-looking string; it does not enforce the numeric(12,2) scale/precision or the 0–99999999.99 range — those are DB CHECKs (staff_basic_salary_range, staff_allowances_range) reached only after this validator passes, so an out-of-range or over-precise value produces the generic unique/check-violation path rather than a named error (see 8.35).

6.24 ListStaffQueryDto (query, extends QueryDto)

pagination cannot be turned off — StaffService.findAll throws 400 PAGINATION_LIMIT_INVALID when query.pagination === false, the same error code the students and guardians lists use for the identical shape of refusal, because an unbounded staff directory is a full-table read of everyone's employment record.

6.25 QueryDto — shared base

ListStudentsQueryDto additionally declares its own sortBy (not sort) as the actual allow-listed field — the inherited sort is accepted but functionally unused by StudentsService.orderBy, which reads query.sortBy. ListGuardiansQueryDto and ListStaffQueryDto use the inherited sort field directly against their own allow-lists instead.

6.26 GuardianLookupDto (body — POST /students/guardian-lookup)

Run through the global ValidationPipe like every other body in this module — whitelist/forbidNonWhitelisted apply, and a missing or blank phone is refused with 400 VALIDATION_FAILED rather than degrading to an empty result set. See 8.2.

7. Enum Reference

8. Endpoint Reference

8.1 GET /api/students

Purpose

Returns a paginated, filterable, searchable list of students, scoped to what the caller's active role may see. Called by the student roll screen, by a guardian's own "my children" view, and by a student's own "my record" view — the same endpoint serves all three, differentiated entirely by PeopleAccessService.scopeFor.

Source Evidence

Auth and Permissions

• Auth: Required (JwtAuthGuard).
• Guard chain: JwtAuthGuard → RoleGuard.
• Permission: Students_READ.
• Object-level scope: PeopleAccessService.scopeFor — all for superadmin; role-name-first below that, so an active role named guardian or student is scoped to that restriction (own children; own record) even if it also holds Students_READ; any other role gets all only by holding Students_READ, and otherwise sees only its own profile row. See 5.
• Guest support: None.
• Rate limit: None module-specific.
• Idempotency: N/A (read).

Request

GET /api/students?search=sita&recordStatus=active&hasGuardians=true&sortBy=admissionNumber&order=asc HTTP/1.1

Response

{
  "message": "Students fetched.",
  "data": [
    {
      "id": "01922e2b-1a2b-7c3a-9d2e-1a2b3c4d5e6f",
      "admissionNumber": "STU-2026-0041",
      "studentId": "SID-2026-0001",
      "imeisId": null,
      "admissionDate": "2026-04-15",
      "recordStatus": "active",
      "transportMode": "school_bus",
      "interestsHobbies": null,
      "isRecordComplete": true,
      "guardianCount": 1,
      "currentClass": {
        "classId": "01922e2a-7c3a-7b1e-9d2e-1a2b3c4d5e6f",
        "gradeName": "5",
        "sectionName": "A",
        "shift": "morning",
        "name": null
      },
      "person": {
        "id": "01922e2a-6b1e-7c3a-9d2e-1a2b3c4d5e6f",
        "firstName": "Sita",
        "middleName": null,
        "lastName": "Rai",
        "fullName": "Sita Rai",
        "email": null,
        "emailVerified": false,
        "phone": null,
        "phoneVerified": false,
        "image": null,
        "canLogin": true,
        "mustChangePassword": false,
        "dateOfBirth": "2012-03-04",
        "gender": "female",
        "bloodGroup": "O+",
        "disabilityType": null,
        "maritalStatus": null,
        "ethnicityId": 4,
        "ethnicityName": "Newar",
        "motherTongueId": 2,
        "motherTongueName": "Nepal Bhasa",
        "permanentAddress": {
          "provinceId": 3,
          "provinceName": "Bagmati",
          "districtId": 27,
          "districtName": "Kathmandu",
          "municipalityId": 118,
          "municipalityName": "Kathmandu Metropolitan City",
          "municipalityType": "metropolitan",
          "wardNo": 4,
          "tole": "Baneshwor",
          "houseNo": null
        },
        "currentAddress": {
          "provinceId": null,
          "provinceName": null,
          "districtId": null,
          "districtName": null,
          "municipalityId": null,
          "municipalityName": null,
          "municipalityType": null,
          "wardNo": null,
          "tole": null,
          "houseNo": null
        },
        "bio": null,
        "banned": false,
        "banReason": null,
        "createdAt": "2026-04-15T04:15:00.000Z",
        "updatedAt": "2026-04-15T04:15:00.000Z",
        "deletedAt": null
      },
      "createdAt": "2026-04-15T04:15:00.000Z",
      "updatedAt": "2026-04-15T04:15:00.000Z",
      "deletedAt": null,
      "version": "1776123300000"
    }
  ],
  "errorCode": null,
  "count": 1,
  "currentPage": 1,
  "totalPage": 1
}

count/currentPage/totalPage are always present — the controller passes a metadata object into ResponseDto whenever query.pagination is truthy (students.controller.ts:77-79), and pagination=false is refused outright rather than accepted, so the branch that would omit them is unreachable from this route.

Side Effects

• Cache: reads students:list:<key> first; on a hit, no database query runs. On a miss, writes the result to that key with a 120-second TTL.
• Known staleness, accepted: the list projects a class's grade, section and shift as text, so renaming a grade, a section or a class leaves the cached roll showing the old label for up to the 120-second TTL. Enrolment writes and a change of current session both drop that cache; a rename does not, because coupling the classes module's writes to the students cache would buy a two-minute label correction at the cost of a dependency between two modules.
• Database reads: SELECT on students INNER JOIN users, plus two correlated subqueries per row — guardianCount, and currentClass, which resolves the pupil's active enrolment in the current session down to grade, section and shift; a separate COUNT(*) when pagination is enabled (the class subquery is on the row query only, so it cannot affect the total). A search term additionally opens a transaction to pin the trigram threshold.
• No jobs, realtime events, notifications, audit logs, or external calls.

Error Cases

Edge Cases

• Empty search (?search=): trims to undefined and is dropped — the unfiltered (but still scoped) list returns, not zero rows.
• search containing %/_: escaped before entering the ILIKE half of the match; the trigram half takes the raw term.
• pagination=false is refused with 400 PAGINATION_LIMIT_INVALID, even for a superadmin — checked before the scope predicate is even built, because an unpaginated roll is every child's name, date of birth and home address in one response, and this is the largest of the three people tables.
• size above 100: rejected with 400, not clamped.
• A guardian or student viewing this list sees only what their scope predicate allows — never a 403, just a shorter list (or zero rows) than an administrator would see for the same query.
• Ties on the sort column (e.g. a bulk import sharing one updatedAt) never drop or duplicate rows across pages — id is appended as a deterministic tie-breaker on every ordering.
• hasGuardians=false returns students with zero live guardian links — a student whose only guardian was soft-deleted counts as hasGuardians=false even though a student_guardian row still exists.

Example Requests

curl -X GET "$API_URL/api/students?recordStatus=active&sortBy=admissionNumber&order=asc" \
  -H "Authorization: Bearer TOKEN"

8.2 POST /api/students/guardian-lookup

Purpose

Finds existing guardians sharing a phone number, for the admission form's create-or-select step — called before an operator types a name, so the second child of a family attaches to the same guardian row instead of duplicating a parent. A POST, deliberately: a phone number identifying a specific family belongs in a request body, not in access logs, proxy logs, or browser history from a URL.

Source Evidence

Auth and Permissions

• Auth: Required.
• Guard chain: JwtAuthGuard → RoleGuard.
• Permission: Guardians_READ.
• Object-level scope: PeopleAccessService.scopeFor(actor, "guardians", …) — a restricted actor's lookup is silently narrowed to guardians already within their own scope, never a 403.
• Guest support: None.
• Rate limit: None module-specific.
• Idempotency: N/A (read).

Request

{
  "phone": "+977-9841002233"
}

Validated by the global ValidationPipe like every other body in this module: phone is required, must be a string, non-blank, and at most 40 characters. whitelist/forbidNonWhitelisted apply, so an unrecognized extra field in the body is rejected rather than silently accepted.

Response

{
  "message": "Guardians fetched.",
  "data": [
    {
      "guardianId": "01922e2c-2b3c-7c3a-9d2e-1a2b3c4d5e6f",
      "fullName": "Ram Bahadur Rai",
      "phone": "+977-9841002233",
      "email": null,
      "linkedStudentCount": 1
    }
  ]
}

Returned as a plain array with no pagination metadata — capped at 25 rows (.limit(25)), never paginated.

Side Effects

• Database reads: guardians INNER JOIN users filtered on an exact phone match, plus a correlated subquery per row for linkedStudentCount (live students only).
• No cache, no writes, no jobs, no external calls.

Error Cases

Edge Cases

• A household sharing one number returns every guardian on it, by design — the caller picks the right one rather than the API guessing, since a shared number is the normal case for a family, not an anomaly.
• Returns a list even when it contains zero, one, or several entries; never a 404 for "no match" — an empty array is the correct answer to "nobody has this number yet".
• The exact-match semantics mean a phone number stored with different formatting (spaces, no country code) will not match — there is no normalization on this filter beyond validation.
• A blank or missing phone no longer silently returns an empty list — it is rejected with 400 VALIDATION_FAILED before the query ever runs, since matching on an empty string would otherwise read as "no parent on file", which is the one answer an admissions operator must not be given by accident.

Example Requests

curl -X POST "$API_URL/api/students/guardian-lookup" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+977-9841002233"}'

8.3 POST /api/students

Purpose

Admits a student: one users row, one students row, and zero or more guardian links, all in a single transaction — each guardian entry either links an existing guardian (found via 8.2) or creates a new one from scratch. Called by the admission form's submit action.

Source Evidence

Auth and Permissions

• Auth: Required.
• Guard chain: JwtAuthGuard → RoleGuard.
• Permission: Students_CREATE.
• Object-level scope: N/A — create has no existing row to scope against.
• Guest support: None.
• Rate limit: None module-specific.
• Idempotency: None — no idempotency key; a resubmitted identical request admits a second student unless admissionNumber collides.

Request

Minimal valid request (no guardians — permitted, flags the record incomplete):

{
  "person": { "firstName": "Sita", "lastName": "Rai" },
  "admissionDate": "2026-04-15"
}

Full valid request, linking one new guardian as primary:

{
  "person": {
    "firstName": "Sita",
    "lastName": "Rai",
    "dateOfBirth": "2012-03-04",
    "gender": "female",
    "bloodGroup": "O+",
    "city": "Kathmandu",
    "state": "Bagmati"
  },
  "admissionDate": "2026-04-15",
  "transportMode": "school_bus",
  "guardians": [
    {
      "person": {
        "firstName": "Ram Bahadur",
        "lastName": "Rai",
        "phone": "+977-9841002233"
      },
      "relationship": "father",
      "isPrimary": true,
      "isLegalGuardian": true,
      "isEmergencyContact": true,
      "canPickup": true,
      "livesWith": true
    }
  ]
}

Second child of the same family, linking the existing guardian by id instead:

{
  "person": { "firstName": "Hari", "lastName": "Rai" },
  "admissionDate": "2026-04-15",
  "guardians": [
    {
      "guardianId": "01922e2c-2b3c-7c3a-9d2e-1a2b3c4d5e6f",
      "relationship": "father",
      "isPrimary": true
    }
  ]
}

Response

Same shape as 8.1's single item, wrapped as data, with message: "Student admitted.".

The response also carries invitation. The create responses are CreatedStudentDto, CreatedGuardianDto and CreatedStaffDto — the read DTO plus one nullable field, described in 6.4d. It is null unless sign-in access was granted; { "sent": true, "to": "..." } when an invitation was enqueued; and { "sent": false, "reason": "no_email" } when access was granted to somebody with no email address on file.

Side Effects

• Database writes, in one transaction: one INSERT into users; one INSERT into students (allocating an admission number atomically if none was supplied); for each guardian entry, either a lookup-and-reuse or an INSERT into users + guardians; one INSERT per guardian into student_guardian, all initially is_primary = false, followed by a single UPDATE setting the primary flag on the one entry marked isPrimary (a two-pass write, since the primary-uniqueness index is not deferrable).
• Cache: every cached student list is invalidated (students:* prefix sweep).
• When sign-in access is granted to somebody with an email address — the pupil, or a guardian entry carrying grantSignIn — the same transaction also writes an account_invite verification record and enqueues the invitation email through the notification outbox. Both commit with the person or not at all; a fire-and-forget call after the commit would lose the invitation on a restart between the two, leaving somebody who exists, believes they were invited, and has nothing scheduled.
• No other jobs, realtime events, notifications, or external calls.

Error Cases

If the transaction fails for any reason, nothing is written — no orphaned users row, no half-admitted student, no dangling guardian link; confirmed by the integration test asserting zero students/users rows after a rejected primary-guardian validation.

Edge Cases

• At least one guardian is required. isRecordComplete/guardianCount still describe the live-link state after admission (a guardian later soft-deleted can bring guardianCount back to 0), but the admission request itself can no longer submit zero guardians — this overrides an earlier decision, still visible in the schema's own comments, to permit an intentionally incomplete admission with none.
• Supplying admissionNumber explicitly is for importing an existing roll — a fresh admission should omit it and let PeopleCodeService allocate one, timezone-correct against the school's academic year. The same applies to studentId: omit it to auto-allocate, or supply one (format SID-YYYY-NNNN) when migrating a roll that already quotes one — see §6.5's comparison table.
• Two office staff admitting simultaneously never collide on the admission number — allocation is one atomic upsert (code_counters), not a max()+1 read.
• An organisation guardian (kind: "organization" on the link, orthogonal to relationship) derives guardians.organizationName from person.firstName — send the organisation's whole name there, with no lastName. Any of the three slots (father, mother, local_guardian) may hold an organisation.
• Reusing guardianId links to that guardian's current data; it does not re-apply any person fields also present in the same entry (they are ignored when guardianId is set — only person is read when creating a new guardian). grantSignIn on such an entry is ignored for the same reason: the guardian already exists, and their sign-in access is changed through 8.23a.
• Admission does not create an account. Without grantSignIn (or its older spelling person.canLogin) the pupil gets a record and no login, which is the right outcome for most of a roll. Granting one requires Users_UPDATE on top of Students_CREATE, because a login-capable row with an email address is a route to a session — POST /api/auth/password/forgot is public.
• A grant to somebody with no email address still succeeds; the response carries invitation: { "sent": false, "reason": "no_email" }. Add an address later and call 8.10a to invite them.

Example Requests

curl -X POST "$API_URL/api/students" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"person":{"firstName":"Sita","lastName":"Rai"},"admissionDate":"2026-04-15"}'

8.4 GET /api/students/:id

Purpose

Returns one student. Called by the student detail screen, and by a guardian's or student's own record view when the id in scope is theirs.

Source Evidence

Auth and Permissions

• Auth: Required. Guard chain: JwtAuthGuard → RoleGuard. Permission: Students_READ. Object-level scope: PeopleAccessService.assertCanAccess — out-of-scope answers 404, never 403. Guest support: none. Rate limit: none module-specific. Idempotency: N/A (read).

Request

Response

Same shape as one item of 8.1's data array, with message: "Student fetched.".

Side Effects

Database read only: students INNER JOIN users, plus the guardianCount and currentClass subqueries. No cache (single-item reads are not cached; only list results are).

Error Cases

Edge Cases

• A soft-deleted student's id answers 404 here even for a caller with full scope — this endpoint never returns a deleted row; list it via ?recordVisibility=removed (or all) instead. ?includeDeleted=true no longer has this effect — see Section 10.
• A guardian requesting another family's child gets byte-for-byte the same 404 STUDENT_NOT_FOUND as a nonexistent id — there is no way to distinguish "wrong family" from "never existed" from the response alone, by design.

Example Requests

curl -X GET "$API_URL/api/students/01922e2b-1a2b-7c3a-9d2e-1a2b3c4d5e6f" \
  -H "Authorization: Bearer TOKEN"

8.5 PATCH /api/students/:id

Purpose

Updates a student's identity fields or record-level fields (admission date, record status, transport mode, IMEIS id, interests). Called from the student edit screen. Cannot touch health data, guardians, or the admission number — each has its own endpoint or is immutable here.

Source Evidence

Auth and Permissions

• Auth: Required. Guard chain: JwtAuthGuard → RoleGuard. Permission: Students_UPDATE. Object-level scope: assertCanAccess — out-of-scope is 404. Guest support: none. Rate limit: none module-specific. Idempotency: not naturally idempotent — a version token is required, and a resubmitted identical body after the first succeeds fails the second time with 409 PEOPLE_STALE_RECORD because the token has already moved.

Request

Minimal valid request:

{
  "version": "1776123300000",
  "transportMode": "public_transport"
}

Response

Same shape as 8.4, with message: "Student updated." and a new version.

Side Effects

• Database reads: the row locked FOR UPDATE to read the current version counter (the version check), so two concurrent PATCHes serialize rather than racing.
• Database writes: an UPDATE on users only for the fields the person object actually carried; an UPDATE on students for the record-level fields present, always touching updatedAt even when only person changed — not because it is the token (it is not; students.version is), but because it keeps the patch non-empty so the statement, and therefore the bump_row_version trigger, always fires, and leaving it alone on a person-only edit would hand every other viewer a token that still validates against a record that has, in fact, moved.
• Database writes, when the body carries classId: an INSERT into student_class_enrollments, and an UPDATE closing the pupil's previous active enrolment as transferred — both in the same transaction as the row above, through the same enroll() the class roster uses. It also reads classes, grades, sections and academic_sessions to resolve and validate the class, and takes FOR UPDATE on the target class row (and the previous one, in ascending id order) to count occupancy.
• Cache: every cached student list invalidated.
• No jobs, realtime events, notifications, or external calls. An enrolment write does defer one activity record.

Error Cases