Classes - API Reference

Audience: Frontend engineers, mobile engineers, backend engineers, QA, and API consumers. Scope: Admin-facing APIs owned by AcademicStructureModule (grades, sections, rooms, classes, and the class-side enrolment routes) and, for one read route, StudentsController. No public or /api/mobile/... route exists in this module.

1. Documentation Evidence

2. Module Summary

3. Concepts and Terminology

4. API Surface Map

No alias routes, no restore endpoints (none of sections/rooms/classes has deleted_at), and no create/update/delete route for grades at all — verified against the full contents of every controller file. ClassEnrollmentsController declares a bare @Controller() with no class-level path prefix; every route it owns states its full path in the method decorator ("classes/:publicId/students", "classes/:publicId/enrollments", "enrollments/:id"), which is why the last four rows above have two different top-level prefixes (/classes/... and /enrollments/...) from the same controller class.

5. Auth, Identity, and Permissions

• Auth is mandatory on every route. JwtAuthGuard rejects a missing/invalid token with 401 AUTH_UNAUTHENTICATED before RoleGuard ever runs.
• Every handler declares a permission. RoleGuard's fail-open branch never applies here — every handler in every controller in this module declares a @Permissions(...), and route-permissions.spec.ts asserts the same in CI.
• Grades has no permission module of its own. PERMISSION_MODULES lists Classes, Sections, Rooms — no Grades entry exists. GET /api/grades is gated by Classes_READ, and there is no other route to gate: no POST/PATCH/DELETE /api/grades exists in this codebase.
• Two permission surfaces, not one. Classes_*/Sections_*/Rooms_* gate the class-setup screens. Students_READ/Students_UPDATE gate every roster/enrolment/history route in this document, including the four declared on ClassEnrollmentsController — a caller who holds full Classes_* grants but no Students_* grants can manage every class in the school but cannot touch a single enrolment.
• Students_READ/Students_UPDATE are not the whole story — object-level scope is the actual control. PeopleAccessService.scopeFor/applyScope narrow every roster and history read to the pupils the caller's role permits; PeopleAccessService.assertCanAccess refuses every enrolment write on an out-of-scope pupil with 404, deliberately never 403 — a 403 on a specific id would confirm that id exists, which turns the pupil id space into an enumeration oracle. A client integrating against this module must treat every 404 from an enrolment route as potentially meaning "exists, but not visible to you," not only "does not exist."
• The seeded staff/teacher roles hold every _READ code in this module but no Students_UPDATE. packages/db/src/seed/seed-auth.ts's STAFF_PERMISSIONS (shared by reference with TEACHER_PERMISSIONS) includes Classes_READ, Sections_READ, Rooms_READ, and Students_READ — but not Students_UPDATE. A caller integrating a teacher-facing screen should not assume that role can enrol or withdraw a pupil; only an explicitly administrative role currently can.
• Active-role scoping. Permissions resolve from the caller's currently-active role only. A user holding several roles who has not selected one is refused with 403 AUTH_ACTIVE_ROLE_REQUIRED; a user with no role at all gets 403 PERMISSION_ROLE_NOT_ASSIGNED.
• Superadmin bypass. A role with is_superadmin = true skips both the permission list and the object-level scope check entirely, keyed on the boolean flag, never on the role's name string.
• Permission catalog mechanics. Classes, Sections, Rooms are each declared once in PERMISSION_MODULES, and the full catalog is generated as every module crossed with every action in PERMISSION_ACTIONS (CREATE, READ, UPDATE, DELETE, RESTORE). Classes_RESTORE, Sections_RESTORE, and Rooms_RESTORE all exist as valid, seeded, grantable permission codes even though no route in this module ever checks any of them — none of sections/rooms/classes has deleted_at.
• Deploy-time grant gap. pnpm --filter @skoolsewa/api permissions:sync creates the permission rows for this module but grants them only to roles named "superadmin" or "admin" — verified against sync-permissions.ts:90, and this product seeds no role literally named "admin". pnpm --filter @skoolsewa/db db:seed:prod is the command that actually applies the staff/teacher grants a client integration should expect to see live.
• 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.

6. DTO and Model Reference

6.1 GradeDto (response)

6.2 ListGradesQueryDto (query, extends QueryDto)

6.3 SectionDto (response)

6.4 CreateSectionDto (body)

6.5 UpdateSectionDto (body)

6.6 ListSectionsQueryDto (query, extends QueryDto)

6.7 RoomDto (response)

6.8 CreateRoomDto (body)

6.9 UpdateRoomDto (body)

6.10 ListRoomsQueryDto (query, extends QueryDto)

6.11 QueryDto — shared base

This is the one deviation from the school module's QueryDto usage worth calling out explicitly: LookupsService in the school module does branch on query.sort; no service in this document does. sort/order are inherited fields on every list query DTO in this module and are accepted without error, but every list endpoint's ordering is fixed and structural (position, then name, then id for grades/sections/rooms; grade/section/shift/id for classes; enrolment date descending for a pupil's history). A client sending ?sort=name&order=asc receives a 200 with no error, and the response is not sorted by name.

6.12 ClassAcademicSessionDto (nested response)

6.13 ClassTeacherDto (nested response)

6.14 ClassDto (response)

6.15 CreateClassDto (body)

6.16 UpdateClassDto (body)

academicSessionId, gradeId, sectionId, and shift are permanently absent from this DTO — not merely optional. A class's identity is immutable after creation; the composite foreign key from student_class_enrollments carries ON UPDATE restrict with no exception. Sending any of the four in the body produces 400 VALIDATION_FAILED ("property X should not exist") from the global forbidNonWhitelisted validator, before ClassesWriteService ever runs.

6.17 ListClassesQueryDto (query, extends QueryDto)

6.18 ClassOptionsQueryDto (query, not a QueryDto subtype)

Deliberately not a QueryDto subtype — this endpoint is always unpaginated by construction, so there is no pagination/page/size/sort/order/search to accept.

6.19 ClassOptionDto / ClassOptionsPayloadDto (response)

ClassOptionDto carries no room and no class teacher — this is the endpoint's whole reason to exist alongside GET /classes, so a caller who needs only "which classes exist and how full are they" never receives staff identity.

ClassOptionsPayloadDto — the endpoint's data field — is { items: ClassOptionDto[], truncated: boolean }, an object, not an array. truncated has nowhere else to live: ResponseDto's pagination fields (count/currentPage/totalPage) only populate when a pagination object with numeric count/page/size is passed to its constructor, which never happens here since the endpoint is unpaginated by definition — a caller cannot page past the cap and must be told when it was hit some other way.

6.20 EnrollmentClassDto / EnrollmentDto (response)

EnrollmentDto:

6.21 ClassRosterStudentDto / ClassRosterEntryDto (response)

ClassRosterStudentDto — deliberately narrower than StudentDto: no date of birth, address, phone, guardian, or anything from the medical columns (those are gated by StudentMedical_READ and a roster has no use for them).

ClassRosterEntryDto:

6.22 CreateEnrollmentDto (body)

6.23 UpdateEnrollmentDto (body)

classId is deliberately not a field on this DTO at all. Moving a pupil between classes is always POST /classes/:publicId/enrollments, which takes the capacity lock and writes the predecessor row; an in-place classId change here would bypass both. Sending it produces 400 VALIDATION_FAILED — unknown field.

6.24 ListRosterQueryDto (query, extends QueryDto)

6.25 ListStudentEnrollmentsQueryDto (query, extends QueryDto)

7. Enum Reference

"completed" is not a value of enrollment_status — see 5.2 in the backend doc for why.

8. Endpoint Reference

8.1 GET /api/grades

Purpose

Returns every grade — Nursery, LKG, UKG, and 1-12 by default, plus whatever an operator has added directly to the table (there is no product route to do so). Called by the class-setup screen and the admission form's grade select.

Source Evidence

Auth and Permissions

• Auth: Required.
• Guard chain: JwtAuthGuard → RoleGuard.
• Permission: Classes_READ (grades has no permission module of its own).
• Guest support: None.
• Rate limit: None module-specific.
• Idempotency: N/A (read).

Request

GET /api/grades?isActive=true&pagination=false HTTP/1.1

Response

{
  "message": "Grades fetched.",
  "data": [
    { "id": 1, "publicId": "018f2a1e-...", "name": "Nursery", "code": "NURSERY", "sortOrder": 0, "isActive": true, "createdAt": "2026-01-10T04:15:00.000Z", "updatedAt": "2026-01-10T04:15:00.000Z" },
    { "id": 4, "publicId": "018f2a1f-...", "name": "1", "code": "G1", "sortOrder": 3, "isActive": true, "createdAt": "2026-01-10T04:15:00.000Z", "updatedAt": "2026-01-10T04:15:00.000Z" }
  ],
  "errorCode": null
}

count/currentPage/totalPage are omitted here because pagination=false was requested.

Side Effects

None. A plain, uncached SELECT.

Error Cases

Edge Cases

• No route to create/update/delete a grade — ? on a POST/PATCH/DELETE to this path is a plain 404 Not Found (no handler registered), not a domain error.
• sort/order accepted, silently ignored — ordering is always sortOrder, name, id.
• pagination=false: capped at UNPAGINATED_HARD_CAP (1000), a ceiling far above the realistic 15-row seeded set.

Example Requests

curl -X GET "$API_URL/api/grades" \
  -H "Authorization: Bearer TOKEN"

8.2 GET /api/sections

Purpose

Lists sections, paginated and optionally filtered. Called by the section-setup screen and any dropdown needing the full list (typically pagination=false&isActive=true).

Source Evidence

Auth and Permissions

• Permission: Sections_READ. Guard chain and guest support as in 8.1.

Request

GET /api/sections?search=a&isActive=true HTTP/1.1

Response

{
  "message": "Sections fetched.",
  "data": [
    { "id": 1, "publicId": "018f2a20-...", "name": "A", "sortOrder": 0, "isActive": true, "createdAt": "2026-01-10T04:15:00.000Z", "updatedAt": "2026-01-10T04:15:00.000Z" }
  ],
  "errorCode": null,
  "count": 1,
  "currentPage": 1,
  "totalPage": 1
}

Side Effects

None — uncached read.

Error Cases

Same as 8.1, substituting Sections_READ.

Edge Cases

• Empty search (?search=): filter dropped entirely, matching the school module's behavior.
• size above 100: silently clamped.
• Fixed ordering: sortOrder, lower(name), id; sort/order accepted, ignored.

Example Requests

curl -X GET "$API_URL/api/sections?pagination=false&isActive=true" \
  -H "Authorization: Bearer TOKEN"

8.3 POST /api/sections

Purpose

Creates a new section. Called from the section-setup screen's "add" action.

Source Evidence

Auth and Permissions

• Permission: Sections_CREATE.
• Idempotency: None — a resubmitted identical request creates a second section unless the name collides.

Request

Minimal valid request:

{ "name": "E" }

Full valid request:

{ "name": "E", "sortOrder": 4 }

Response

{
  "message": "Section created.",
  "data": {
    "id": 5, "publicId": "018f2a25-...", "name": "E", "sortOrder": 4,
    "isActive": true, "createdAt": "2026-02-01T09:00:00.000Z", "updatedAt": "2026-02-01T09:00:00.000Z"
  },
  "errorCode": null
}

Side Effects

• Database: SELECT (name-uniqueness pre-check) then INSERT, both inside one transaction (so a concurrently-omitted sortOrder is computed against a consistent snapshot).
• No cache, no jobs, no realtime, no audit call beyond the automatic interceptor.

Error Cases

Edge Cases

• sortOrder omitted: computed as COALESCE(max(sort_order), -1) + 1 — a school's very first section (empty table) still succeeds, because of the COALESCE.
• Two sections sharing a sortOrder: allowed, ties break on lower(name).
• Name held only by a retired section: reusable, since the unique index is partial on is_active.

Example Requests

curl -X POST "$API_URL/api/sections" \
  -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"E"}'

8.4 PATCH /api/sections/:publicId

Purpose

Renames, reorders, or retires/reactivates a section.

Source Evidence

Auth and Permissions

• Permission: Sections_UPDATE.

Request

{ "sortOrder": 2 }

Response

Same shape as 8.3's create response, reflecting the applied patch.

Side Effects

SELECT (lookup, and a name pre-check only if the name actually changed case-insensitively) then UPDATE. No cache invalidation — this module caches nothing.

Error Cases

Edge Cases

• Renaming to the same name, different case ("A" → "a"): a no-op, not a self-clash.
• Retiring a section still referenced by a class: allowed unconditionally — no reference check on PATCH, only on DELETE.

Example Requests

curl -X PATCH "$API_URL/api/sections/018f2a20-..." \
  -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
  -d '{"isActive":false}'

8.5 DELETE /api/sections/:publicId

Purpose

Permanently removes a section created in error. Blocked while any class still references it.

Source Evidence

Auth and Permissions

• Permission: Sections_DELETE.

Response

{ "message": "Section deleted.", "data": null, "errorCode": null }

Side Effects

DELETE, catching the real foreign-key violation (23503) and translating it into a named 409.

Error Cases

Edge Cases

• Retired section: deletable exactly like an active one — retirement status has no bearing on deletability.

Example Requests

curl -X DELETE "$API_URL/api/sections/018f2a20-..." \
  -H "Authorization: Bearer TOKEN"

8.6 GET /api/rooms

Purpose

Lists rooms, optionally filtered by search text, building, floor, or isActive. Called by the room-setup screen and the class-creation form's room select.

Source Evidence

Auth and Permissions

• Permission: Rooms_READ.

Request

GET /api/rooms?building=Main+Block&floor=1&pagination=false HTTP/1.1

Response

{
  "message": "Rooms fetched.",
  "data": [
    { "id": 10, "publicId": "018f2a30-...", "roomNumber": "101", "name": "Science Lab", "floor": 1, "building": "Main Block", "isActive": true, "createdAt": "2026-01-10T04:15:00.000Z", "updatedAt": "2026-01-10T04:15:00.000Z" }
  ],
  "errorCode": null
}

Side Effects

None — uncached read.

Error Cases

Same shape as 8.1, substituting Rooms_READ.

Edge Cases

• search matches roomNumber, building, and name together — a search for the room's name text finds it even without matching the number.
• floor=0 (ground floor): honored as a real filter value, not treated as "no filter."

Example Requests

curl -X GET "$API_URL/api/rooms?isActive=true&pagination=false" \
  -H "Authorization: Bearer TOKEN"

8.7 POST /api/rooms

Purpose

Creates a new room.

Source Evidence

Auth and Permissions

• Permission: Rooms_CREATE.

Request

Minimal valid request:

{ "roomNumber": "101", "floor": 1, "building": "Main Block" }

Full valid request:

{ "roomNumber": "101", "name": "Science Lab", "floor": 1, "building": "Main Block" }

Response

{
  "message": "Room created.",
  "data": { "id": 11, "publicId": "018f2a31-...", "roomNumber": "101", "name": "Science Lab", "floor": 1, "building": "Main Block", "isActive": true, "createdAt": "2026-02-01T09:00:00.000Z", "updatedAt": "2026-02-01T09:00:00.000Z" },
  "errorCode": null
}

Error Cases

Edge Cases

• Same number, different building: accepted — uniqueness is scoped to the building.
• name omitted vs. sent as "": "" is rejected by the DTO's Matches/ValidateIf combination before the service runs — an explicit null, or omission, is required to leave it unset.

Example Requests

curl -X POST "$API_URL/api/rooms" \
  -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
  -d '{"roomNumber":"101","floor":1,"building":"Main Block"}'

8.8 PATCH /api/rooms/:publicId

Purpose

Renames, relocates, or retires/reactivates a room.

Source Evidence

Auth and Permissions

• Permission: Rooms_UPDATE.

Request

{ "roomNumber": "102", "floor": 2 }

Error Cases

Edge Cases

• The (building, roomNumber) pair is re-checked only when it actually changes and the result stays/becomes active — sending the room's own current values back is always a no-op-safe request.
• name: null: clears it. name: "": rejected with 400.

Example Requests

curl -X PATCH "$API_URL/api/rooms/018f2a30-..." \
  -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
  -d '{"name":null}'

8.9 DELETE /api/rooms/:publicId

Purpose

Permanently removes a room created in error. Blocked while any class still references it.

Source Evidence

Auth and Permissions

• Permission: Rooms_DELETE.

Error Cases

Edge Cases

• This is the one delete guard in the whole module that is not a translated database error — see the backend doc's 6.3 for the full reasoning.

Example Requests

curl -X DELETE "$API_URL/api/rooms/018f2a30-..." \
  -H "Authorization: Bearer TOKEN"

8.10 GET /api/classes

Purpose

Lists classes for a given academic session (defaulting to whichever is marked current), with every filter combination the class-setup screen needs, and each row's live occupancy count. Refuses pagination=false — see the edge cases.

Source Evidence

Auth and Permissions

• Permission: Classes_READ.

Request

GET /api/classes?academicSessionId=7&gradeId=5&shift=morning HTTP/1.1

Response

{
  "message": "Classes fetched.",
  "data": [
    {
      "id": 3, "publicId": "018f2a40-...",
      "academicSession": { "id": 7, "publicId": "018f2a41-...", "name": "2026-27", "isCurrent": true },
      "grade": { "id": 5, "publicId": "018f2a1e-...", "name": "5", "code": "G5", "sortOrder": 5, "isActive": true, "createdAt": "...", "updatedAt": "..." },
      "section": { "id": 1, "publicId": "018f2a20-...", "name": "A", "sortOrder": 0, "isActive": true, "createdAt": "...", "updatedAt": "..." },
      "shift": "morning",
      "name": null,
      "capacity": 40,
      "enrolledCount": 37,
      "room": { "id": 10, "publicId": "018f2a30-...", "roomNumber": "101", "name": "Science Lab", "floor": 1, "building": "Main Block", "isActive": true, "createdAt": "...", "updatedAt": "..." },
      "classTeacher": { "id": "018f2a50-...", "fullName": "Sita Sharma", "employeeCode": "EMP-0007", "employmentStatus": "active", "isTeaching": true },
      "isActive": true, "createdAt": "...", "updatedAt": "..."
    }
  ],
  "errorCode": null,
  "count": 1, "currentPage": 1, "totalPage": 1
}

Side Effects

SELECT joined across academic_sessions, grades, sections, rooms, staff, users, designations, plus a COUNT(*), plus one grouped occupancy query via ClassOccupancyService.countForMany. No cache.

Error Cases

Edge Cases

• pagination=false is always refused. The row embeds the class teacher's full name and employee code — staff identity a caller holding only Classes_READ should not receive unbounded, mirroring /students//staff's own refusal. Use 8.11 for an unpaginated, person-data-free alternative.
• No academicSessionId given, no session current: { "data": [], "count": 0, "currentPage": 1, "totalPage": 0 }, not an error.
• sort/order accepted, ignored — ordering is always grade.sortOrder, section.sortOrder, shift, id.
• search matches classes.name and grades.name/grades.code/sections.name together — an unnamed class is still findable by grade/section text.

Example Requests

curl -X GET "$API_URL/api/classes?gradeId=5&shift=morning" \
  -H "Authorization: Bearer TOKEN"

8.11 GET /api/classes/options

Purpose

The unpaginated, person-data-free class list that serves both the admission form's grade → section → shift cascade and the capacity chart. Called instead of 8.10 whenever the caller needs "which classes exist and how full are they" without staff identity attached.

Source Evidence

Auth and Permissions

• Permission: Classes_READ (same as the full list).

Request

GET /api/classes/options?academicSessionId=7 HTTP/1.1

Response

{
  "message": "Class options fetched.",
  "data": {
    "items": [
      { "publicId": "018f2a40-...", "grade": { "...": "GradeDto" }, "section": { "...": "SectionDto" }, "shift": "morning", "name": null, "capacity": 40, "enrolledCount": 37, "isActive": true }
    ],
    "truncated": false
  },
  "errorCode": null
}

data is an object, not an array — the one endpoint in this document shaped this way. A client must read data.items as the list, and check data.truncated rather than relying on pagination metadata, which this endpoint never returns.

Side Effects

SELECT on classes joined only to grades/sections (no room, no teacher, no staff join at all), filtered to active-only, limited to UNPAGINATED_HARD_CAP + 1 rows to detect truncation with no second COUNT(*), then one grouped occupancy query.

Error Cases

Same shape as 8.10, minus PAGINATION_LIMIT_INVALID (not applicable — this endpoint is always unpaginated).

Edge Cases

• Excludes retired classes unconditionally, unlike the full list, which defaults to showing both.
• Over UNPAGINATED_HARD_CAP (1000) active classes in the resolved session: truncated: true, and the response silently omits the excess.
• No current session and none given: { "items": [], "truncated": false }.

Example Requests

curl -X GET "$API_URL/api/classes/options?academicSessionId=7" \
  -H "Authorization: Bearer TOKEN"

8.12 GET /api/classes/:publicId

Purpose

Returns a single class's full detail, including its live occupancy.

Source Evidence

Auth and Permissions

• Permission: Classes_READ.

Response

Same shape as one row of 8.10's data array.

Error Cases

Edge Cases

• Route ordering: this route is registered after @Get("options"), so /api/classes/options is never matched here as publicId = "options".

Example Requests

curl -X GET "$API_URL/api/classes/018f2a40-..." \
  -H "Authorization: Bearer TOKEN"

8.13 POST /api/classes

Purpose

Creates a new class: one grade, one section, one shift, in one academic session.

Source Evidence

Auth and Permissions

• Permission: Classes_CREATE.
• Idempotency: None — a resubmitted identical request is refused with CLASS_IDENTITY_TAKEN, not silently deduplicated, so a client that retries a genuinely-failed request safely gets a 409 rather than a second class.

Request

Minimal valid request:

{ "academicSessionId": 7, "gradeId": 5, "sectionId": 1, "shift": "morning", "capacity": 40 }

Full valid request:

{
  "academicSessionId": 7, "gradeId": 5, "sectionId": 1, "shift": "morning",
  "capacity": 40, "name": "5A Morning",
  "classTeacherId": "018f2a50-...", "roomId": "018f2a30-..."
}

Response

Same shape as 8.12, reflecting the created class with enrolledCount: 0.

Side Effects

• Reads: session/grade/section (existence + active), room (if given, existence + active), staff+designation (if given, existence + not soft-deleted + isTeaching).
• Writes: one INSERT inside a transaction.
• No cache, no jobs, no realtime.

Error Cases

Edge Cases

• Same identity as a retired class: refused — identity uniqueness is not partial on is_active.
• Same room/teacher, different shift: accepted.
• classTeacherId/roomId omitted: no error — both are optional.

Example Requests

curl -X POST "$API_URL/api/classes" \
  -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
  -d '{"academicSessionId":7,"gradeId":5,"sectionId":1,"shift":"morning","capacity":40}'

8.14 PATCH /api/classes/:publicId

Purpose

Edits a class's name, capacity, room, class teacher, or active flag. Identity fields can never be part of this request.

Source Evidence

Auth and Permissions

• Permission: Classes_UPDATE.

Request

{ "capacity": 35 }

{ "capacity": 20, "allowOverCapacity": true }

Response

Same shape as 8.12.

Side Effects

SELECT ... FOR UPDATE (locks the row for the duration of the transaction), an occupancy re-count only if capacity is present, room/teacher resolution only if either field is present, then UPDATE.

Error Cases

Edge Cases

• Sending an identity field: always 400, regardless of whether it would have matched the current value.
• Re-sending the class's own current roomId/classTeacherId: not re-validated for active status — otherwise a class holding a since-retired resource could never be edited at all, including to deactivate it.
• roomId/classTeacherId: null: clears the assignment.
• isActive: false: allowed unconditionally, with no enrolment check.

Example Requests

curl -X PATCH "$API_URL/api/classes/018f2a40-..." \
  -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
  -d '{"isActive":false}'

8.15 DELETE /api/classes/:publicId

Purpose

Permanently removes a class created in error. Blocked while any enrolment — of any status — references it.

Source Evidence

Auth and Permissions

• Permission: Classes_DELETE.

Error Cases

Edge Cases

• The recommended correction for a mistaken class with pupils already enrolled: deactivate (PATCH {"isActive": false}), not delete — identity is not freed either way.

Example Requests

curl -X DELETE "$API_URL/api/classes/018f2a40-..." \
  -H "Authorization: Bearer TOKEN"

8.16 GET /api/classes/:publicId/students

Purpose

A class's roster, narrowed to the pupils the caller's role can see. Called by the class detail screen's roster tab.

Source Evidence

Auth and Permissions

• Permission: Students_READ.
• Guest support: None.
• Object-level scope applies. See 5.

Request

GET /api/classes/018f2a40-.../students?status=active HTTP/1.1

Response

{
  "message": "Class roll fetched.",
  "data": [
    { "enrollmentId": "018f2a60-...", "student": { "id": "018f2a61-...", "studentId": "SID-2026-0005", "admissionNumber": "2026/0005", "fullName": "Anisha Thapa", "recordStatus": "active" }, "status": "active", "enrolledOn": "2026-04-15", "endedOn": null }
  ],
  "errorCode": null,
  "count": 1, "currentPage": 1, "totalPage": 1
}

Side Effects

SELECT joined across student_class_enrollments/students/users, with the caller's object-level scope ANDed into the WHERE clause. No cache.

Error Cases

Edge Cases

• pagination=false is always refused — a class roll is every enrolled child's name in one response, for the same reason /students refuses it.
• A caller's scope narrower than the class: sees fewer rows than the class actually holds, never an error.
• status omitted: defaults to "active".
• A pupil soft-deleted or recordStatus: "inactive": excluded even if their enrolment row is still active — the same filter ClassOccupancyService applies.

Example Requests

curl -X GET "$API_URL/api/classes/018f2a40-.../students?status=withdrawn" \
  -H "Authorization: Bearer TOKEN"

8.17 POST /api/classes/:publicId/enrollments

Purpose

Enrols a pupil into a class, or — if the pupil already holds an active enrolment elsewhere in the same session — transfers them. One route does both; the backend decides which case applies.

Source Evidence

Auth and Permissions

• Permission: Students_UPDATE.
• Object-level scope applies before the class is even resolved — PeopleAccessService.assertCanAccess runs before ClassEnrollmentsService.enroll is called.
• Idempotency: The one endpoint in this module with real idempotency built in. Resubmitting an identical enrol request against the same target class for an already-active pupil is a no-op, returning the existing row unchanged.

Request

{ "studentId": "018f2a61-..." }

{ "studentId": "018f2a61-...", "enrolledOn": "2026-04-20", "allowOverCapacity": true }

Response

{
  "message": "Pupil enrolled.",
  "data": {
    "id": "018f2a70-...", "status": "active", "enrolledOn": "2026-04-20", "endedOn": null,
    "class": { "publicId": "018f2a40-...", "name": null, "shift": "morning", "grade": { "...": "GradeDto" }, "section": { "...": "SectionDto" }, "academicSession": { "...": "ClassAcademicSessionDto" } },
    "createdAt": "...", "updatedAt": "..."
  },
  "errorCode": null
}

Side Effects

• Reads: class context, pupil existence/deletedAt/admissionDate, the pupil's active row this session (if any), both classes locked FOR UPDATE in ascending id order, live occupancy under that lock.
• Writes: predecessor UPDATE on a transfer, then INSERT, both inside one transaction.
• Cache: students:list:* cleared.
• Audit: recordActivity (ENROLL or TRANSFER), naming the pupil, the old/new class, and — on an override — the capacity numbers.

Error Cases

Edge Cases

• Re-submitting the same enrol request for a pupil already active in the target class: no-op, the existing row is returned unchanged.
• Pupil already active in a different class, same session: treated as a transfer — the predecessor is closed transferred and a fresh active row opened, atomically.
• Two simultaneous cross-transfers (X→Y and Y→X): both classes always locked in ascending id order regardless of which request calls which class "target" — deadlock-free by construction.
• enrolledOn omitted: defaults to today in Asia/Kathmandu, not UTC.
• Class retired between the initial read and the lock being granted: caught by the second isActive check, taken under the lock.

Example Requests

curl -X POST "$API_URL/api/classes/018f2a40-.../enrollments" \
  -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
  -d '{"studentId":"018f2a61-...","allowOverCapacity":true}'

8.18 DELETE /api/classes/:publicId/enrollments/:studentId

Purpose

Withdraws a pupil from this class — records that they left, distinct from removing a mistaken entry.

Source Evidence

Auth and Permissions

• Permission: Students_UPDATE, plus object-level scope.

Response

{
  "message": "Pupil withdrawn.",
  "data": { "id": "018f2a70-...", "status": "withdrawn", "enrolledOn": "2026-04-20", "endedOn": "2026-09-08", "class": { "...": "EnrollmentClassDto" }, "createdAt": "...", "updatedAt": "..." },
  "errorCode": null
}

Side Effects

Class locked FOR UPDATE; UPDATE on the pupil's active row (status, endedOn); students:list:* cache cleared; recordActivity (WITHDRAW).

Error Cases

Edge Cases

• endedOn is computed as max(enrolledOn, today), never plain "today" — a future-dated active enrolment withdrawn on its own start date would otherwise violate the dates-ordered CHECK.
• A pupil enrolled by mistake: withdrawal is the wrong tool — see 8.20.

Example Requests

curl -X DELETE "$API_URL/api/classes/018f2a40-.../enrollments/018f2a61-..." \
  -H "Authorization: Bearer TOKEN"

8.19 PATCH /api/enrollments/:id

Purpose

Corrects an enrolment's date and/or status without going through enrol/withdraw — for example, backfilling a historical record.

Source Evidence

Auth and Permissions

• Permission: Students_UPDATE, plus object-level scope, resolved by reading the enrolment's studentId first.

Request

{ "enrolledOn": "2026-04-16" }

{ "status": "withdrawn" }

Error Cases

Edge Cases

• classId in the body: always 400 — unknown field. Moving a pupil is always POST /classes/:publicId/enrollments.
• status set from active to transferred/withdrawn, no endedOn given: computed the same max(enrolledOn, today) way as withdraw.
• enrolledOn moved past an already-set endedOn: endedOn pulled forward to match, rather than left to violate the CHECK.

Example Requests

curl -X PATCH "$API_URL/api/enrollments/018f2a70-..." \
  -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
  -d '{"status":"withdrawn"}'

8.20 DELETE /api/enrollments/:id

Purpose

Removes an enrolment entered in error — the wrong class was picked, or a duplicate slipped past a race. Leaves no trace in the transferred/withdrawn counters, distinct from withdrawal.

Source Evidence

Auth and Permissions

• Permission: Students_UPDATE, plus object-level scope.

Response

{ "message": "Enrolment removed.", "data": null, "errorCode": null }

Side Effects

Owning class locked FOR UPDATE; hard DELETE; students:list:* cache cleared; recordActivity (ENROLLMENT_DELETE).

Error Cases

Edge Cases

• Removing an active row: allowed — no different from removing a closed one.
• Why this exists alongside withdraw: offering only "withdraw" would force an operator to record a fictional departure for a pupil who never actually left the class — see the feature doc's 12.3.

Example Requests

curl -X DELETE "$API_URL/api/enrollments/018f2a70-..." \
  -H "Authorization: Bearer TOKEN"

8.21 GET /api/students/:id/enrollments

Purpose

A pupil's own class history, newest first — the one active row per academic year, plus any transfers and withdrawals. Called by the pupil profile screen's enrolment-history section.

Source Evidence

Auth and Permissions

• Permission: Students_READ.
• Object-level scope applies, resolved exactly as every other single-record route on StudentsController: assertCanAccess before the read.

Request

GET /api/students/018f2a61-.../enrollments?academicSessionId=7 HTTP/1.1

Response

{
  "message": "Class enrolments fetched.",
  "data": [
    { "id": "018f2a70-...", "status": "active", "enrolledOn": "2026-04-20", "endedOn": null, "class": { "...": "EnrollmentClassDto" }, "createdAt": "...", "updatedAt": "..." }
  ],
  "errorCode": null,
  "count": 1, "currentPage": 1, "totalPage": 1
}

Side Effects

SELECT joined across student_class_enrollments/classes/grades/sections/academic_sessions. No cache.

Error Cases

Edge Cases

• Route ownership. Lives on StudentsController, not a class controller — matching the convention :id/guardians and :id/medical already set on the same controller. Putting it here would give AcademicStructureModule a /students/* prefix nothing else in this repo uses.
• sort/order/search accepted, ignored — ordering is always enrolledOn DESC, id DESC.
• No enrolments yet (pupil admitted, not yet placed): data: [].
• academicSessionId given: narrows to that session's rows only, typically one active plus any transfers/withdrawals within it.

Example Requests

curl -X GET "$API_URL/api/students/018f2a61-.../enrollments" \
  -H "Authorization: Bearer TOKEN"

9. Flow Diagrams

9.1 Route Ownership

9.2 Request Sequence — enrol/transfer

9.3 Error Branch — mutation endpoints

10. Pagination, Sorting, Filtering, and Search

Shared pagination utility: PaginationUtil throughout — normalize() clamps page/size, getDrizzleParams() returns {limit, offset} or undefined, buildMetadata() builds the envelope's {count, page, size}.

No broad-search detection or relevance scoring exists anywhere in this module — every search filter is a plain ILIKE '%term%' (escaped via escapeLikePattern) against one or more fixed columns, never a ranked or full-text search.

Cache behavior per query: none — every list in this module is read live, on every request (see the backend doc's 8. Caching).

Empty result behavior: every list endpoint returns { "data": [], "count": 0 } (or the array/object equivalent) rather than an error, including when the resolved academic session has no classes, when a search matches nothing, or when a filter combination is impossible.

11. Caching, Jobs, and External Integrations

13. Mandatory Deep API Documentation Pack

13.1 Route-by-Route Completeness Matrix