Classes Backend Documentation

1. Documentation Evidence

2. Backend Scope and Boundaries

Owns

• Grades — Nursery, LKG, UKG and grades 1-12, a read-only reference list with no permission module of its own; gated under Classes_READ. GradesService/GradesController.
• Sections — the A/B/C/D-style subdivisions a grade is split into, full CRUD, hard-deleted and reference-guarded like the school module's lookup tables. SectionsService/SectionsController.
• Rooms — physical rooms (number, floor, building), full CRUD, hard-deleted and reference-guarded. RoomsService/RoomsController.
• Classes — the concrete unit a school runs: one grade, one section, one shift, in one academic session, with a capacity, an optional room, and an optional class teacher. Read is split into list/options/single-row (ClassesReadService); writes are create/update/delete (ClassesWriteService).
• Student class enrolments — which pupil sits in which class, and when they stopped. The sole writer is ClassEnrollmentsService, deliberately outside AcademicStructureModule in a leaf module (EnrollmentsCoreModule) — see 3 for why.
• Class occupancy — the one shared, live-computed definition of "how full is this class," used by capacity checks, the class list, the options endpoint, and the roster. ClassOccupancyService.
• A class's roster — ClassRosterService, which is the one read path in this module that applies the people-domain object-level scope.
• Name/number-uniqueness enforcement for sections (case-insensitive, active-only) and rooms (case-insensitive, scoped to building, active-only), and identity/room/teacher-exclusivity enforcement for classes (see 5.2).
• Delete-time referential checks that produce a mapped error instead of an unmapped foreign-key failure, or — for rooms specifically — instead of a silent ON DELETE set null.

Does Not Own

• Academic sessions. packages/db/src/schema/school/academic-sessions.ts and its own module own the year a class belongs to; this module only references academic_sessions.id and reads startDate/endDate/isCurrent off it.
• Staff and their designations. packages/db/src/schema/school/people.ts owns staff; this module only reads a staff row (and its designation's isTeaching flag) to validate and display a class teacher. A teacher is a staff row with a teaching designation — there is no teacher entity and no Teachers permission module.
• Students. packages/db/src/schema/school/people.ts owns students, created/updated/soft-deleted by the people module. This module reads students.deletedAt/admissionDate/recordStatus to validate an enrolment and to filter occupancy and the roster, but never writes any of those columns.
• Object-level access scoping. PeopleAccessService/PeoplePermissionsService (in PeopleModule) own scopeFor/applyScope/assertCanAccess; this module's roster service and enrolment controller call into them rather than reimplementing scope logic.
• Activity/audit recording infrastructure. ActivityRecordService (in ActivityModule) owns the Mongo write; ClassEnrollmentsService calls it for detail the automatic interceptor cannot see, but does not own the mechanism.
• Authentication. JwtAuthGuard is imported, not implemented, by every controller in this module.
• Redis connectivity. RedisCacheService is imported by ClassEnrollmentsService for exactly one purpose — invalidating the student list cache another module owns — never for caching this module's own reads (see 8. Caching).

Source of Truth

3. Module Composition

The import list is load-bearing, and so is what is absent. AcademicStructureModule imports EnrollmentsCoreModule, PeopleModule, RoleModule, and ActivityModule. PeopleModule itself imports EnrollmentsCoreModule — so StudentsService can write an enrolment inside the same transaction as a pupil, on a path this document does not otherwise cover. That composition only works because EnrollmentsCoreModule is a leaf: it imports ActivityModule and nothing else, giving the graph

ActivityModule ← EnrollmentsCoreModule ← PeopleModule ← AcademicStructureModule

which is acyclic. Had ClassEnrollmentsService needed PeopleAccessService directly, EnrollmentsCoreModule would need to import PeopleModule, closing the graph into a PeopleModule ↔ AcademicStructureModule cycle. Nest refuses that at InstanceLoader unless both sides use forwardRef, and there is no forwardRef anywhere in this application — this codebase's one prior module cycle produced ReferenceError: Cannot access 'MONGODB' before initialization at boot, with check-types and build both green. So authorization for every enrolment write lives at the controller boundary, and ClassEnrollmentsService is a pure domain writer. RoleModule is imported for RoleGuard's dependency on RoleService, applied at controller level on every controller in this module.

ClassesReadService is the one export of AcademicStructureModule — verified: no other module currently imports AcademicStructureModule, so this export is not yet consumed elsewhere, but exists for a future module that needs to resolve a class by id without duplicating the join logic in 6.4.

4. File and Directory Map

apps/api/src/modules/academic-structure/
  academic-structure.module.ts
  grades/
    grades.controller.ts
    grades.service.ts
  sections/
    sections.controller.ts
    sections.service.ts
  rooms/
    rooms.controller.ts
    rooms.service.ts
  classes/
    classes.controller.ts
    classes-read.service.ts
    classes-write.service.ts
    class-roster.service.ts
  enrollments/
    class-enrollments.controller.ts
  dto/
    index.ts
    grade.dto.ts
    section.dto.ts
    room.dto.ts
    class.dto.ts
    enrollment.dto.ts
    query-boolean.ts
  __tests__/
    grades.service.integration.spec.ts
    sections.service.integration.spec.ts
    rooms.service.integration.spec.ts
    classes-read.service.integration.spec.ts
    classes-write.service.integration.spec.ts

apps/api/src/modules/enrollments-core/
  enrollments-core.module.ts
  class-enrollments.service.ts
  class-enrollments.mapper.ts
  class-occupancy.service.ts
  __tests__/
    fixtures.ts
    class-enrollments.service.integration.spec.ts
    class-occupancy.service.integration.spec.ts

packages/db/src/schema/school/
  classes.ts       # class_shift, enrollment_status enums; grades, sections, rooms, classes,
                    # student_class_enrollments tables and their relations

packages/db/src/seed/
  seed-reference-data.ts   # seedAcademicStructure() — 15 grades, 4 sections, empty-table-guarded

5. Data Model

5.1 Schema Source

packages/db/src/schema/school/classes.ts
  classShiftEnum            # "morning" | "day"
  enrollmentStatusEnum      # "active" | "transferred" | "withdrawn"
  grades
  sections
  rooms
  classes
  studentClassEnrollments

Every text column in this file is constrained by ~ '^[^[:space:]](.*[^[:space:]])?$', not col = btrim(col). Two reasons the schema's own docblock states: btrim(x) with one argument strips spaces only — a tab or newline still satisfies col = btrim(col), and lower('A ') does not collide with 'a' under the case-folded unique indexes below, so the hole the check exists to close would stay open. It also rejects an all-whitespace value, which a plain char_length(col) > 0 would accept. The POSIX class [[:space:]] is deliberate too — \s inside a Drizzle sql template literal is a JavaScript NonEscapeCharacter, so the cooked string contains a bare s and the constraint would silently become "must not start with the letter s"; [[:space:]] needs no backslash and cannot be mangled that way. The one accepted limit: glibc's [[:space:]] under en_US.UTF-8 does not classify U+00A0 NO-BREAK SPACE as whitespace, so a name padded with one is still representable — the realistic inputs (a pasted trailing space, a tab, a newline) are covered, and the constraint probe asserts exactly which of these it rejects rather than assuming.

5.2 Tables and Collections

grades

Both unique indexes are partial on is_active — retiring "UKG" and recreating it later must not be blocked by a full unique index naming a row the admin screen (which filters is_active) does not list.

sections

No code column, unlike grades. A section has no stable machine identity worth preserving across a rename — "A" renamed to "Alpha" is the same section under a new label, and nothing external quotes it. That absence is exactly why the seed guards on an empty table rather than using ON CONFLICT — see 15 and seed-reference-data.ts.

rooms

rooms_building_number_unique — unique on (lower(building), lower(room_number)), partial WHERE is_active. Scoped to the building, not global — two buildings each having a "101" is the normal case, and a global unique index would force an operator to invent prefixes the school does not otherwise use.

classes

A class the school runs: one grade, one section, one shift, in one academic session.

The four identity columns are immutable after creation, and this is not tidiness. academic_session_id, grade_id, section_id, and shift are absent from UpdateClassDto. The composite unique constraint classes_id_session_unique ((id, academic_session_id)) is the target of student_class_enrollments' composite foreign key, which carries no ON UPDATE action — Postgres's default NO ACTION refuses any change to academic_session_id the instant one enrolment exists, surfacing as an unmapped 23503 (a 500). designations.department_id carries the identical warning for the identical construction, and prescribes the identical answer: deactivate and recreate.

Why identity uniqueness is total and room/teacher uniqueness is partial. classes_identity_unique — unique on (academic_session_id, grade_id, section_id, shift) — is a plain unique index with no WHERE is_active clause, unlike every other unique index in this file. An earlier design put AND is_active on all three, plus a service rule refusing to deactivate a class holding enrolments — and the two rules cancelled each other: after one pupil enrolled, the class could be neither deactivated (the service rule) nor hard-deleted (ON DELETE restrict from the enrolment row), so it was permanently stuck in exactly the case the partial index existed to unstick. A class's identity is its name within its year, and history must not be ambiguous — two rows that were ever "2026-27 / Grade 5 / A / morning" would make every past roster unresolvable, so identity stays reserved forever and deactivation is always permitted with no enrolment check at all. A room and a class teacher are resources, not identity, and a retired class must release them — so classes_room_per_shift_unique and classes_teacher_per_shift_unique do keep WHERE ... AND is_active, each scoped to (academic_session_id, shift, ...) so the same room or the same person can run a morning class and a day class but never two of the same shift.

student_class_enrollments

Which pupil sits in which class, and when they stopped.

Why academic_session_id is denormalised here, and made safe by a composite FK. The invariant this table exists to enforce is "one active enrolment per pupil per session," and Postgres cannot build a partial unique index across a join — the session lives on classes, the pupil lives on this row. Without a local copy, the rule is unenforceable in the database and becomes a service convention, exactly the shape of invariant that survives review and then fails under concurrency. The copy is made safe, not merely conventional, by student_class_enrollments_class_session_fk — (class_id, academic_session_id) → classes(id, academic_session_id), ON DELETE restrict ON UPDATE restrict — the same construction staff already uses for (department_id, designation_id). A composite FK is MATCH SIMPLE by default, which skips validation entirely when any column of the pair is NULL — the hole that let (NULL, <a designation>) into staff and required a companion CHECK there. Both class_id and academic_session_id on this table are NOT NULL, so that skip condition is unreachable and no companion CHECK is needed — verified, not assumed, by the constraint probe.

The one-active-per-session invariant, precisely. student_class_enrollments_one_active_per_session_unique — unique on (student_id, academic_session_id), partial WHERE status = 'active'. A pupil accumulates any number of closed rows per session and at most one open one, which is exactly what makes a transfer representable: close the predecessor, open the successor, and the partial index never sees two 'active' rows at once.

The two coherence CHECKs. student_class_enrollments_dates_ordered — ended_on IS NULL OR ended_on >= enrolled_on — rejects a closed enrolment whose end predates its own start. student_class_enrollments_ended_matches_status — (status = 'active' AND ended_on IS NULL) OR (status <> 'active' AND ended_on IS NOT NULL) — an active row carrying an end date, and a closed row carrying none, are both incoherent: the first claims the pupil is both in the class and has left it; the second claims they left and names no date.

No completed status

An earlier design had one, defined as "the session ended with the pupil in this class," and nothing anywhere wrote it — no route, no job, no scheduled task. An enum value with no writer is a dead branch that makes a missing feature look implemented: every check constraint and every query mentioning it would read as though year rollover were handled. An enrolment in a past session simply stays active, and that is unambiguous because the row names its own session and academic_sessions.is_current says which year is now. Closing a year belongs to a promotion feature that will add the value back together with the thing that writes it.

5.3 Relationship Diagram

Index rationale

6. Services and Responsibilities

6.1 GradesService

Read-only, and deliberately so — the service's own docblock states this is a lookup gated like its parent (Classes_READ), not PersonClassifications' exception to that rule. Ordering is fixed: sortOrder, lower(name), id — query.sort/query.order (both inherited from QueryDto) are never read. search is honored via escapeLikePattern-escaped ILIKE. Pagination follows the standard PaginationUtil shape, including the UNPAGINATED_HARD_CAP fallback for pagination=false — grades is a reference table like the school module's lookups, not a person table.

6.2 SectionsService

sortOrder on create. When omitted, computed inside the same transaction as the insert as COALESCE(max(sort_order), -1) + 1. The COALESCE is load-bearing: max() over an empty table is NULL, and NULL + 1 into a NOT NULL column is a 23502 on a school's very first section without it.

Validation order. Existence before uniqueness before write, matching every other lookup service in this codebase. A rename that only changes casing is accepted as a no-op, not rejected as a self-clash — checked via nextName.toLowerCase() !== existing.name.toLowerCase().

Hard delete, guarded by an explicit ON DELETE restrict. classes_section_id_sections_id_fk genuinely rejects a delete while a class points at the section; translate() maps that 23503 onto SECTION_IN_USE by matching the constraint name walked from the driver error's .cause chain (Drizzle's wrapper does not itself carry .constraint).

No caching. Unlike the school module's LookupsService, no method here calls RedisCacheService — every read is live.

6.3 RoomsService

Why ROOM_IN_USE cannot come from a caught 23503, and this is the one delete guard in the module that differs structurally from the others. classes.room_id is ON DELETE set null — deleting a room a class points at succeeds at the database and silently blanks the class's room instead of raising a foreign-key violation. The refusal here is therefore an explicit SELECT ... FROM classes WHERE room_id = $1 LIMIT 1 pre-check, run before the DELETE, not a translated exception. translate() still matches classes_room_id_rooms_id_fk defensively in case the schema ever tightens the FK to restrict, but that branch is not reachable today — verified by reading the schema's actual onDelete: "set null".

Search matches three fields at once. roomNumber, building, and name are all ILIKE-searched together via or(...), unlike sections/grades which search only name.

6.4 ClassesReadService

loadDto is public, not private, and that is the whole reason ClassesWriteService never opens a second connection to shape its own response. It accepts a DbExecutor — either the pooled Database or an open transaction — so ClassesWriteService.create/.update can pass their own tx and observe the just-written, not-yet-committed row rather than racing a second pooled connection against the open transaction (the exact bug class this repo's DbExecutor docblock names as having shipped once, in blog-post-media.service.ts).

pagination=false is refused on findAll, but not on findOptions. The full list embeds the class teacher's full name and employee code — staff identity a caller holding only Classes_READ should not receive unbounded. findOptions carries no such field (no room, no teacher) and is unpaginated by construction, capped at UNPAGINATED_HARD_CAP + 1 rows fetched (one over, to detect truncation with no second COUNT(*)) then sliced back to the cap.

Session resolution returns null, not an exception, when no session is current. resolveSessionId returns undefined-means-"use current" / null-means-"none is current" to its two callers, both of which return an empty result rather than throw — nothing in the schema requires exactly one is_current = true row to exist at any given moment.

Fixed ordering, sort/order unused. Every list is ordered grade.sortOrder, section.sortOrder, shift, id — ListClassesQueryDto inherits sort/order from QueryDto, but findAll's orderBy clause never reads either field.

search reaches beyond the class's own (nullable) name. Because classes.name can be NULL, matching only it would make every unnamed class unsearchable — the search also matches grades.name, grades.code, and sections.name.

6.5 ClassesWriteService

Why validation and conflict mapping are split. "Not found"/"retired" is read before the write, because no database constraint can turn a bad gradeId into anything better than an unmapped foreign-key violation — a 500. "Already taken" (identity, room, teacher) is left to the database's own unique indexes and translated after the fact, which is what actually makes the check atomic under a race — a service-level pre-check-then-insert without a transaction has the identical TOCTOU gap the school module's LookupsService documents for department/designation names.

Code flow — create(), precisely. 1) Resolve and active-check the session, then the grade, then the section — each is a distinct round trip, in that order, because a bad session should fail before a bad grade is even looked up. 2) If roomId is given, resolve it and active-check it, but only if it is being newly set — this branch has no "unchanged" exception because create has no prior state. 3) If classTeacherId is given, resolve the staff row (joined to its designation for isTeaching), and assert it is neither soft-deleted nor non-teaching. 4) Insert inside a transaction, catching any unique-index violation into translate(). 5) Reload the fresh row via ClassesReadService.loadDto rather than constructing the response by hand, so the response always reflects exactly what the database now holds (including enrolledCount: 0, computed the same way every other read computes it, not hardcoded).

Code flow — update(), precisely. The entire method runs inside one transaction. 1) SELECT ... FOR UPDATE on the target row — this lock is what makes the capacity/occupancy check mean anything: without it, one operator could lower capacity while another enrols the pupil that pushes the class over it, with no override ever recorded, because the two operations would race past each other's read. 2) name/isActive are applied unconditionally if present. 3) If capacity changed, ClassOccupancyService.countFor runs inside the same lock, and the write is refused unless the new capacity covers the live roll or allowOverCapacity is set. 4) roomId/classTeacherId, if present, are resolved, but the retired-active check fires only when the resolved id differs from what is already stored — re-sending the class's own current room/teacher is always accepted, even if that room/teacher has since been retired or lost its teaching flag, because otherwise a class holding a now-invalid resource could never be edited again, including to deactivate it. 5) The patch is applied and loadDto reloads the fresh row on the same tx, so the response reflects the just-committed (within the still-open transaction) state.

remove() has no explicit pre-check, unlike rooms. student_class_enrollments_class_session_fk is ON DELETE restrict (not set null), so an actual foreign-key violation is reachable and correctly reflects "this class has enrolments" — no explicit existence-check query is needed before the DELETE, only a translate() branch on the constraint name.

Transactions. create and update both wrap their reads-then-writes in db.transaction(...); remove does not need one, since its only guard is the database's own FK.

6.6 ClassRosterService

The permission is a precondition, PeopleAccessService.scopeFor is the control. Students_READ alone does not decide who may read a roster — scope.kind (defaulting to self per role) is resolved and ANDed into the query's WHERE exactly as StudentsService.findAll applies it. The service's own docblock states this is not a theoretical concern: an operator who builds a narrow-scoped role and grants it Students_READ would otherwise get the correct (empty-or-narrow) result from GET /students but the entire class roll from this route if the scope were skipped here — an incident this repo's own history records twice.

The row filters match the occupancy count, deliberately. students.deletedAt IS NULL AND students.recordStatus = 'active' — the exact same pair ClassOccupancyService applies. Without this alignment, a class's roster and its capacity figure on the same screen could disagree in a way nobody could explain from the UI.

Fixed ordering, unused sort/order/search. Ordered students.studentId, students.id always; ListRosterQueryDto inherits sort/order/search from QueryDto but none is read.

6.7 ClassEnrollmentsService

Marked SPLIT-EXEMPT in its own file header: five methods — enroll, withdraw, updateEnrollment, removeEnrollment, listForStudent — sharing one lock discipline, one constraint-translation table, and one cache-invalidation path, deliberately kept in one file rather than scattered across single-import modules.

Deliberately no authorization — see 3. Every method trusts its caller to have already resolved assertCanAccess; the controller does this before calling in, and StudentsService's own update path does the same on a separate route this document does not otherwise cover.

Code flow — enroll(), in full. 1) Resolve the target class's context — session id, dates, capacity, shift, and the grade/section names the eventual capacity-error message will quote. A missing class is 404 CLASS_NOT_FOUND; a retired one (checked here, on the unlocked read) is 409 CLASS_INACTIVE. 2) Read the pupil's admissionDate/deletedAt; a soft-deleted pupil is refused with ENROLLMENT_STUDENT_DELETED — restoring the record is the only path forward. 3) Resolve enrolledOn — input.enrolledOn, or today in Asia/Kathmandu via getCurrentNepalDateString() — and validate it against both the class's session date range and the pupil's own admission date; either failure is a distinct, named 409. 4) Read the pupil's current active row in this session, in any class — at most one can exist, guaranteed by the partial unique index. If it is already this class, return it unchanged (idempotent re-submission). 5) If it is a different class, this is a transfer; a back-dated enrolledOn earlier than the predecessor's own is refused as ENROLLMENT_DATE_INVALID before it reaches Postgres, since closing the predecessor with an earlier endedOn would otherwise violate ..._dates_ordered as an unmapped 500 on the single most common flow in the module. 6) Lock both classes (or just the target, if this is a fresh enrolment) in ascending id order — this is what makes a simultaneous X→Y / Y→X cross-transfer deadlock-free regardless of which request calls which class the "source." 7) Re-check the target's isActive after the lock is granted, not trusted from the unlocked read in step 1 — a concurrent deactivation between the two reads must still be caught. 8) Recompute occupancy under the lock via ClassOccupancyService.countFor, and refuse with CLASS_AT_CAPACITY (numbers named in the message text) unless there is room or allowOverCapacity is set. 9) Inside a try, close the predecessor (if any) and insert the new row; any constraint violation reaching the catch goes through translate(). 10) Invalidate the students-list cache. 11) Call recordActivity with the module Students, the action ENROLL or TRANSFER, the pupil's id as resourceId, a changes entry naming the old/new class, and metadata carrying capacity/enrolledBefore/allowOverCapacity — the audit interceptor sees only the actor/module/action/status of the HTTP request, never this level of detail.

Code flow — withdraw(). Resolves the class, locks it, finds the pupil's active row in it (a 404 ENROLLMENT_NOT_FOUND if none), and closes it with endedOn = max(enrolledOn, today) — never plain "today," because a future-dated active enrolment withdrawn on its own start date would otherwise violate the dates-ordered CHECK with a naive "today."

Code flow — updateEnrollment(). Locks the enrolment's owning class (for the same reason every other write does — serializing against a concurrent capacity edit or a concurrent enrol/transfer touching the same class), then applies enrolledOn/status independently. If status is set and the row was active, endedOn is computed the same max(enrolledOn, today) way as withdraw; otherwise, if the resulting endedOn would precede the resulting enrolledOn, it is pulled forward to match rather than left to violate the CHECK.

Code flow — removeEnrollment(). Locks the owning class, then hard-deletes the row — no status transition, no trace left in the transferred/withdrawn counters. Exists because offering only withdraw would force an operator to record a fictional departure for a pupil enrolled into the wrong class by mistake.

listForStudent() has no authorization and no lock — it is a plain read. Ordered enrolledOn DESC, id DESC always (tie-broken on id for stable pagination); query.sort/order/search (all inherited from QueryDto) are never read. Mapped through toEnrollmentDto in the separate mapper file — split out to keep this service under the repo's per-file line-count convention, not for any behavioral reason.

Cache invalidation is coarse and deliberate. Every write clears the entire students:list:* prefix, not a scoped subset — a student-list row shows "current class," and StudentsService itself clears the same prefix on every student write; an enrolment written from this service bypasses that path entirely and must invalidate the identical keys or the list would serve a stale class for the remainder of the TTL.

6.8 ClassOccupancyService

The one shared definition, used everywhere a seat is counted. Both filters on students are required and neither is obvious: deletedAt IS NULL exists because students soft-deletes and ON DELETE cascade never fires for a soft delete, so a deleted pupil would otherwise keep inflating every class's count forever; recordStatus = 'active' exists because a pupil marked inactive (a distinct enum from soft-delete) is not attending, and counting them holds a seat nobody occupies.

countForMany is the one grouped-query path, on purpose. A class absent from the grouped result (because it has zero live enrolments) is pre-seeded into the returned map with 0 before the query even runs, so a missing key reads 0, never undefined — every caller can safely .get(id) ?? 0 without that fallback ever actually firing on a class with real pupils. A loop calling countFor once per row would be an N+1 that no gate in this repo would catch, because every individual call would itself pass.

7. Runtime Flows

7.1 List classes (session resolution, filters, live occupancy)

7.2 Create a class

7.3 Update a class (capacity guard, locked)

7.4 Enrol or transfer a pupil (the module's most complex flow)

7.5 Withdraw a pupil

Include, for every enrolment flow above: success path, validation failure, permission failure (guard, before the controller runs), missing-entity, duplicate-request (idempotent re-submission for enroll), race/concurrency behavior (ascending-lock-order for cross-transfers; the partial unique index for concurrent fresh enrolments), and the guest-vs-logged-in branch (not applicable — no route in this module accepts an unauthenticated caller).

8. Caching

This is the module's only cache interaction, and it is entirely one-directional. No service in AcademicStructureModule or EnrollmentsCoreModule calls getSoft/setSoft — every findAll/findOne/findOptions across grades, sections, rooms, and classes reads the database live, on every request, unlike the school module's LookupsService/PersonClassificationsService/SchoolProfileService, all three of which are cache-aside. ClassEnrollmentsService injects RedisCacheService for exactly one reason: an enrolment changes what a students:list row shows for "current class," and StudentsService clears that same prefix on its own writes — an enrolment written from this module bypasses StudentsService entirely and must invalidate the identical keys, or the student list would serve a stale class for the remainder of whatever TTL StudentsService set.

Why no list in this module is cached. Not stated explicitly anywhere in the code; verified by the absence of any RedisCacheService injection in GradesService, SectionsService, RoomsService, ClassesReadService, or ClassRosterService. Every read here is either infrequent relative to writes (grades/sections/rooms, edited rarely) or must reflect a live, second-by-second occupancy figure that caching would immediately stale (classes, the roster) — caching the class list specifically would also require invalidating it on every enrolment write from a module (EnrollmentsCoreModule) that does not otherwise know this module's cache-key shape.

9. BullMQ, Schedulers, and Async Work

Not applicable. No queue, job, or scheduler touches any table in this module — verified by the absence of any BullMQ import across every file listed in 4.

10. Realtime and Events

Not applicable. No service in this module emits a Socket.IO event or any other realtime signal.

11. Security, Auth, and Abuse Controls

• Guards. Every controller carries @UseGuards(JwtAuthGuard, RoleGuard) at the class level (grades.controller.ts, sections.controller.ts, rooms.controller.ts, classes.controller.ts, class-enrollments.controller.ts) — no @Public() route exists anywhere in this module.
• Every handler declares a permission. RoleGuard's fail-open branch (a handler with zero @Permissions() on a non-administrative controller) never applies here — every handler in every controller declares one, and route-permissions.spec.ts (referenced in each controller's own class comment) asserts the same in CI.
• Two distinct permission surfaces meet in this module. Classes_*/Sections_*/Rooms_* gate the class-setup screens; Students_READ/Students_UPDATE gate every enrolment route, including the class-side roster and enrol/withdraw routes declared on ClassEnrollmentsController. A caller holding full Classes_* grants but no Students_* grants can see and edit every class, but cannot touch a single enrolment or read a roster.
• Grades has no permission module of its own. GET /api/grades is gated by Classes_READ — verified against PERMISSION_MODULES in packages/db/src/authorization/permission-catalog.ts, which lists Classes, Sections, Rooms but not Grades.
• The object-level access boundary — the actual control behind Students_*. PeopleAccessService.scopeFor/applyScope (read paths: the roster, a pupil's enrolment history) and PeopleAccessService.assertCanAccess (write paths: enrol, withdraw, correct, remove) are called explicitly by ClassRosterService and ClassEnrollmentsController — never by ClassEnrollmentsService, which cannot reach PeopleModule without recreating the module cycle documented in 3. assertCanAccess throws 404, never 403, on an out-of-scope pupil — deliberately, since a 403 on a specific id would confirm that id exists, turning the pupil id space into an enumeration oracle for any caller who can guess or iterate ids.
• Permission source. Classes, Sections, Rooms are each declared once in PERMISSION_MODULES; the full catalog is the cartesian product of every module and every action in PERMISSION_ACTIONS (CREATE, READ, UPDATE, DELETE, RESTORE). Classes_RESTORE, Sections_RESTORE, and Rooms_RESTORE all exist as valid, grantable, seeded permission codes — but no route in this module ever checks any of them, since none of sections/rooms/classes has deleted_at and every deletion is a hard delete.
• Superadmin bypass. Keyed on the is_superadmin boolean, never on a role's display name, checked before the permission list and before the object-level scope check — a superadmin's assertCanAccess call always succeeds regardless of scope.
• Active-role scoping. Permissions and scope both resolve from the caller's currently-active role only, never the union of every role held.
• Deploy-time grant gap. pnpm --filter @skoolsewa/api permissions:sync creates the Classes_*/Sections_*/Rooms_* permission rows on a deploy, but its own role-selection predicate grants them only to roles named "superadmin" or "admin" — verified: sync-permissions.ts:90 selects role.name IN ("superadmin", "admin"), and this product seeds no role literally named "admin" (verified: no name: "admin" insert exists in seed-auth.ts). pnpm --filter @skoolsewa/db db:seed:prod is the command that actually applies the STAFF_PERMISSIONS/TEACHER_PERMISSIONS grants (Classes_READ, Sections_READ, Rooms_READ) an operator running only permissions:sync after adding this module would not otherwise see land.
• Input normalization. Every writable string field (sections.name, rooms.roomNumber/building/name, classes.name) is validated by a Matches(NO_SURROUNDING_WHITESPACE) DTO rule mirroring the schema's own POSIX-class CHECK, and trimmed server-side before comparison or persistence. ILIKE search terms are always escaped through escapeLikePattern.
• Sensitive data redaction. ClassDto/ClassOptionDto deliberately differ in what staff/pupil-adjacent data they carry — the options endpoint carries neither a room nor a teacher, specifically so it can be reached without the disclosure the full list represents; ClassRosterStudentDto is narrower than StudentDto (no DOB, address, phone, guardian, or medical fields) since a roster has no use for them.
• Audit logs. No recordActivity call accompanies any grade/section/room/class create/update/delete — those rely entirely on the automatic ActivityAuditInterceptor. Every enrolment write does call recordActivity explicitly, for detail (the pupil id, the old/new class, the capacity numbers on an override) the automatic interceptor cannot see — see 14. Observability.
• Fail-closed behavior. Every domain error in this module — not-found, retired, identity/room/teacher conflicts, capacity, scope — is fail-closed. There is no fail-soft path anywhere in this module except the students-list cache invalidation, which is fail-soft by inheriting RedisCacheService's own contract.

13. Error Handling

Every response above 400 is wrapped by AllExceptionsFilter into { statusCode, errorCode, message, timestamp?, path? } — timestamp/path outside production only. A CHECK violation with no matching branch in a translate() function is a 500, not a 409 — AllExceptionsFilter has no 23514 branch — which is exactly why every constraint from migration 0011 is named explicitly in the two translate() functions above and independently verified by the constraint probe.

14. Observability

15. Testing and Validation

Seven real-database integration suites cover this module, all against TEST_DATABASE_URL via createTestDatabase()/closeTestDatabase(), none mocking DatabaseModule, Drizzle, or any @skoolsewa/* package:

• academic-structure/__tests__/grades.service.integration.spec.ts — GradesService's read-only list behavior.
• academic-structure/__tests__/sections.service.integration.spec.ts — SectionsService CRUD, including the transactional sortOrder computation and the partial-unique-index reuse-after-retirement behavior.
• academic-structure/__tests__/rooms.service.integration.spec.ts — RoomsService CRUD, including the explicit ROOM_IN_USE pre-check (not a caught FK).
• academic-structure/__tests__/classes-read.service.integration.spec.ts — list/options/single-row reads, session resolution, and occupancy joins.
• academic-structure/__tests__/classes-write.service.integration.spec.ts — create/update/delete, including the capacity-below-enrolled guard and the room/teacher retired-active re-check-only-if-changed behavior.
• enrollments-core/__tests__/class-occupancy.service.integration.spec.ts — the shared occupancy predicate, including the soft-deleted/record-inactive pupil exclusion.
• enrollments-core/__tests__/class-enrollments.service.integration.spec.ts — enrol/transfer/withdraw/correct/remove, including the ascending-lock-order deadlock avoidance and the date-validation branches.

enrollments-core/__tests__/fixtures.ts supplies shared setup (a session, a grade, a section, a room, a staff member, a pupil) across the enrolment and occupancy suites, avoiding per-test duplication of that fixture graph.

The repo-wide route-permissions.spec.ts covers this module indirectly: it asserts every administrative-surface handler declares a @Permissions() decorator, which all five controllers satisfy.

The constraint probe — packages/db/src/scripts/probe-class-module-constraints.sql — is the authoritative statement of what the database permits, run in one transaction and rolled back, exercising 57 accept/reject cases across every unique index and CHECK constraint migration 0011 adds, in both directions:

psql "$TEST_DATABASE_URL" -f packages/db/src/scripts/probe-class-module-constraints.sql

Validation commands:

pnpm --filter @skoolsewa/api build
pnpm --filter @skoolsewa/db build
pnpm --filter @skoolsewa/api test:structure

16. Mandatory Backend Deep-Dive Pack

16.1 Submodule Coverage Matrix

No provider, processor, scheduler, or mapper exists in either module directory beyond what is listed above — verified against the file map in 4.

16.2 UML and Architecture Diagram Pack

State diagrams: see 7.1 and 7.2 in the features and flows doc — a boolean flag for classes/sections/rooms, and the one real multi-value state machine in this module for enrollment_status.

16.3 Code Flow Narrative

Covered per-method in 6. Services and Responsibilities and per-flow in 7. Runtime Flows, in full detail for create()/update() on classes and every method on ClassEnrollmentsService — the only methods in this module whose branching exceeds a straightforward lookup → validate → write → (invalidate) shape.

16.4 Data Layer Deep Dive

Covered in full in 5.2 (field tables, nullability, business meaning, the immutability and total/partial-uniqueness reasoning) and the index rationale table immediately after it. No JSON column, money unit, or versioning field exists anywhere in this module's tables. Seed data dependency: grades (15 rows: Nursery, LKG, UKG, 1-12) and sections (4 rows: A, B, C, D) are populated by seedAcademicStructure() in seed-reference-data.ts, guarded on an empty table, not ON CONFLICT DO NOTHING — see 16.6 for why. rooms and classes start genuinely empty; every row a school sees is one an admin (or a future import, not currently part of this module) created.

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 both module directories is represented (see 4).
• Every controller, service, and DTO is documented; no processor/scheduler/mapper exists beyond class-enrollments.mapper.ts, which is documented.
• Every method with business behavior has a code-flow narrative (6, 7).
• Every table has field-level detail (5.2).
• Every index/constraint/relation/delete behavior has rationale (5.2, index rationale table).
• Both lifecycles are documented — is_active as a flag for classes/sections/rooms, enrollment_status as a real state machine.
• Every read/write flow has a sequence diagram (7).
• Every business invariant is cataloged (16.5).
• Cache behavior — including its near-total absence — is documented precisely (8).
• Every architectural tradeoff is documented with alternatives and a revisit trigger (16.6).
• Every operational failure mode has a runbook entry (16.7).

18. Backend Completion Checklist

• Module boundaries are documented (2).
• Every controller, service, DTO, and schema file is covered.
• Every database table has a field table and relationship diagram.
• Every runtime flow has a diagram and branch notes.
• API and features/flows docs are linked below.
• No claim is made without a source file reference, including the constraint probe as the authoritative statement of accept/reject behavior.

See Also

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