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.
• Class roll numbers — a pupil's position in their class's register, assigned when they are enrolled and editable afterwards by an administrator. The sole writer is RollNumberService (enrollments-core/roll-numbers/roll-number.service.ts), called from ClassEnrollmentsService.enroll on every admission and from ClassEnrollmentsController on the two roll-number-specific routes — see 6.9 and 7.6/7.7.
• 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, ActivityModule, and AttendanceSharedModule (for CalendarDayService.sessionContaining; that module declares no controller and imports nothing, so it cannot close a cycle). 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.

AcademicStructureModule exports two services. ClassesReadService is not currently imported by any other module — it exists for a future module that needs to resolve a class by id without duplicating the join logic in 6.4. RoomOccupancyService IS consumed elsewhere: the assets module's AssetCatalogModule imports AcademicStructureModule specifically to inject it into AssetRoomsLookupController, so the asset register's room picker (/api/asset-catalog/rooms) and this module's own GET /api/rooms describe a room's classes and buildings through the identical query rather than two copies of the same join — see 6.10. This is the one cross-module edge into AcademicStructureModule from outside its own controllers, and it runs one direction only: nothing in AcademicStructureModule imports anything from the assets module, so no cycle is created.

RollNumberService reads school_profile directly, not through SchoolProfileService. RollNumberService.policy (roll-numbers/roll-number.service.ts:63-76) selects rollNumberStrategy/rollNumberAutoRenumber off the schoolProfile table with its own injected Database, rather than calling SchoolProfileModule's exported service. EnrollmentsCoreModule importing SchoolProfileModule for one two-column read would add a second cross-domain import to a module this document's own composition rules keep deliberately minimal, and SchoolProfileService.get() additionally resolves the school's principal on every call — work this policy read has no use for. The cost is that a PATCH /api/school-profile write invalidates SchoolProfileService's own school:profile cache key (/docs/developer/school/backend) but RollNumberService.policy never reads that cache at all — it is a live, uncached row read on every enrolment and every renumber call, so the two paths cannot disagree on staleness, only on whichever value is currently committed.

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
    room-occupancy.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
    roll-number.dto.ts
    query-boolean.ts
  __tests__/
    grades.service.integration.spec.ts
    sections.service.integration.spec.ts
    rooms.service.integration.spec.ts
    rooms-occupancy.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
  roll-numbers/
    roll-number.service.ts
  __tests__/
    fixtures.ts
    class-enrollments.service.integration.spec.ts
    class-occupancy.service.integration.spec.ts
    roll-number.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.

roll_number, precisely — nullable, partial-unique, and freed on departure. Three legitimate states carry no number (classes.ts:440-443): a row imported before the school configured its numbering, a pupil an administrator has deliberately unnumbered pending a renumber, and a closed enrolment whose class was later renumbered without it. student_class_enrollments_class_roll_unique is partial on both status = 'active' and roll_number IS NOT NULL — so any number of rows may carry no number at all — and it is scoped to class_id alone, per class rather than per academic session, which is correct because a class row is itself identity-scoped to one session: two DIFFERENT classes may each legitimately hold a roll number 1 (classes.ts:510-515,522), and a departed pupil's number becomes immediately reusable within the same class while their closed row keeps the number it had, for history. The index is also the module's concurrency control for automatic assignment: two admissions into the same class computing the same max + 1 collide here with 23505, and RollNumberService.assignNext retries once against a re-read maximum rather than taking a class-wide advisory lock — see 6.9. student_class_enrollments_roll_number_positive admits NULL explicitly and rejects 0 or a negative value; a CHECK evaluates to NULL (not false) on a NULL input regardless, but stating the admission keeps a reader from having to know that rule to read the constraint.

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". The same shape guards a room still holding an asset (assets.room_id).

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

classes and assetCount are computed, never stored and never cached. findAll loads both through RoomOccupancyService for every row on the current page — one query for classes, one for assets, never one per room — on every call, including a cache hit. create/update call the same service for the single row they return. See 8 for why the occupancy is kept out of the cache.

RoomOccupancyService is injected through Nest's DI container (AcademicStructureModule provides and exports it). Tests that construct RoomsService or AssetRoomsLookupController directly pass an instance built on the same db.

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.

6.9 RollNumberService

Assignment appends; it never renumbers, unless the school has asked it to. assignOnEnroll reads the school's policy and branches: autoRenumber: true resequences the whole class by strategy on every admission; the default (false) hands the new pupil max(roll_number) + 1 among the class's live roll and moves nobody else. The service's own docblock states the reason for the default: a roll number has already been read out in class, written on exercise books, and recorded against attendance history by the time the next pupil joins, so treating alphabetical as a continuously-maintained order would shift every later pupil's number on every mid-year admission.

The unique index is the concurrency control, not an advisory lock. Two admissions into one class at the same instant can both read the same nextFreeNumber. assignNext does not take a SELECT ... FOR UPDATE on the class or an advisory lock — the class-roll unique index refuses the loser's UPDATE with 23505, and assignNext retries exactly once against a freshly re-read maximum, which terminates because the retry's read sees the row the first transaction committed. A class-wide lock would serialize every admission in the school for a counter this cheap.

renumber writes in two phases because the unique index is checked per row, not at statement end. Writing new numbers directly into the existing roll collides with the class's own current numbering — giving roll 1 to the pupil who currently holds 2 violates student_class_enrollments_class_roll_unique against whoever still holds 1, since a plain unique index cannot be deferred to statement end. Phase one clears every live row's roll_number to null; phase two writes 1..n in the resolved order. Both phases run inside the caller's transaction — the enrolment transaction for an auto-renumber, or the explicit transaction ClassEnrollmentsController.renumber opens — so a failure between the phases never leaves a class permanently unnumbered.

renumber's sort order, precisely. alphabetical compares firstName, then middleName, then lastName, then studentId last as a stable tiebreak for two identically-named pupils — localeCompare with sensitivity: "base". admission_order compares admissionNumber then studentId. Either order excludes a soft-deleted or record-inactive pupil from the roll entirely — the same predicate ClassOccupancyService and the roster apply — so a departed child never consumes a position in the renumbered sequence.

A collision on setManual answers a typed 409, not a 500. Drizzle wraps the driver error, so neither .code nor .constraint sits at the top level of what a catch receives — isUniqueViolation walks .cause via pgErrorCode/pgErrorText (apps/api/src/common/utils/pg-constraint.util.ts) to find the SQLSTATE and the constraint name at whatever depth the driver buried them, capped at five levels as a cycle guard. The service's own docblock notes this was caught by an integration test, not by inspection — the happy path is unaffected by the bug the first version of this function had, which read only the top level and turned a genuine roll-number collision into an unmapped 500.

resolveClassId and setManual's missing-enrolment branch both throw UnprocessableEntityException, not NotFoundException — so both surface as 422, not 404, despite naming an error code (CLASS_NOT_FOUND, ROLL_NUMBER_ENROLLMENT_INACTIVE) that reads like a not-found. Verified at roll-number.service.ts:249-254 and :316-321 respectively — this is the code's actual behavior, not a documentation simplification.

6.10 RoomOccupancyService

The one service two controllers in two different modules call for the same three facts about a room: which classes sit in it, which buildings exist, and how many assets it holds. Before this service existed, AssetRoomsLookupController (assets module) carried its own copy of the class-batch query; this service is that query moved to the ONE place both callers reach, so a future change to the label rule or the ordering only has one implementation to edit.

Every requested id is guaranteed a key in the returned Map, even with no matches. classesByRoom/assetCountByRoom seed the map with every id in roomIds ([]/0 respectively) before running a single query, so a caller never writes map.get(id) ?? fallback defensively — the fallback is already the value for a room with nothing. This matters because RoomsService.findAll/.withOccupancy and AssetRoomsLookupController.list both build their response by mapping over rows and reading straight out of these maps.

classesByRoom's label rule. A class's own name, when set and non-blank, is the label; otherwise "<grade name> — <section name> — <Morning|Day>", the same words the Classes screen uses, so a double-shift school's two classes sharing a room are told apart. The asset room lookup (GET /api/asset-catalog/rooms) calls this same method, so a room's classes read identically in both places.

executor defaults to the injected pooled Database, never this.db called from inside a caller's transaction. Every method takes executor?: DbExecutor as its last parameter and resolves executor ?? this.db internally, so a caller already inside a db.transaction(async (tx) => ...) block passes tx and stays on one connection; a caller outside a transaction omits it and gets the pooled connection.

Two controllers construct this service two different ways, and both are deliberate. RoomsController/RoomsService receive it through ordinary Nest DI, because AcademicStructureModule provides and exports it. AssetRoomsLookupController also receives it through DI in the running app (AssetCatalogModule imports AcademicStructureModule for exactly this), but both RoomsService and AssetRoomsLookupController declare their RoomOccupancyService constructor parameter with a default value — roomOccupancy: RoomOccupancyService = new RoomOccupancyService(db) — so the handful of tests written before this service existed, which construct RoomsService/AssetRoomsLookupController directly with new and only the arguments they already knew about, keep compiling and keep passing: the default only fires when the argument is undefined, which is exactly the direct-construction case and never the DI case.

No import cycle. AssetCatalogModule importing AcademicStructureModule is the only edge between the two module trees, and it runs one direction only — AcademicStructureModule's own imports (EnrollmentsCoreModule, PeopleModule, RoleModule, ActivityModule) touch nothing under the assets module, so there is no path back.

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

7.6 Set or clear one pupil's roll number

Shuffles nobody else, and unnumbering is a legitimate state. This route moves only the one enrolment named in the path — rollNumber: null clears it, and the pupil then sorts last on the roster (ClassRosterService's NULLS LAST order) until an administrator runs a renumber. An administrator who wants the whole class resequenced uses 7.7, never this route.

7.7 Renumber a class's roll

The only operation that moves an existing pupil's number. Every other write in this module either appends (assignOnEnroll with auto-renumber off) or edits one row in isolation (7.6). This route is the deliberately explicit act of resequencing a whole class — the service's own docblock states why it is not automatic: a roll number has already been read out in class and recorded against attendance history by the time a resequence would otherwise fire.

Soft-deleted and record-inactive pupils are excluded, so a departed child never consumes a position. renumber's own SELECT carries the identical students.deletedAt IS NULL AND students.recordStatus = 'active' predicate ClassOccupancyService and the roster both apply — verified at roll-number.service.ts:184-191.

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 for concurrent roll-number assignment), and the guest-vs-logged-in branch (not applicable — no route in this module accepts an unauthenticated caller).

8. Caching

RoomsService.findAll is cache-aside; every other list in this module reads the database live. GradesService, SectionsService, ClassesReadService, and ClassRosterService inject no RedisCacheService and answer every findAll/findOne/findOptions straight from Postgres, on every request — grades/sections are edited rarely enough that caching would buy little, and the class list and roster must reflect a live, second-by-second occupancy figure that caching would immediately stale. RoomsService is the one exception: its list is keyed by every filter/page combination, so a ?building= filter caller and an unfiltered caller never collide on one key, and any write to rooms clears the entire prefix rather than trying to invalidate one key.

Only the room rows are cached; occupancy is read on every call. Which classes use a room and how many assets sit in it change through writes to classes and assets in other modules, which cannot know this cache key's shape. So findAll caches the room rows and totalCount alone, and on every call — cache hit or miss — adds classes and assetCount through RoomOccupancyService in one batch query each. The room's own fields (number, floor, building, isActive) are served from the cache and stay exact, because every write to them goes through RoomsService and clears the whole prefix.

ClassEnrollmentsService's students:list invalidation is the module's other cache interaction, and it is entirely one-directional. It 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.

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 — and both roll-number routes (PATCH /enrollments/:id/roll-number, POST /classes/:publicId/enrollments/renumber) are gated on Students_UPDATE, the same code as every other enrolment write, not a separate roll-number permission. A caller holding full Classes_* grants but no Students_* grants can see and edit every class, but cannot touch a single enrolment, a single roll number, 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, set/clear a roll number) are called explicitly by ClassRosterService and ClassEnrollmentsController — never by ClassEnrollmentsService or RollNumberService, neither of which can 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.
• A class-wide write has no class-level scope to check, so POST /classes/:publicId/enrollments/renumber checks every pupil individually, before writing. ClassEnrollmentsController.renumber calls RollNumberService.liveStudentIds and runs assertPupilInScope in a loop over every one of them before opening the transaction that calls RollNumberService.renumber — a caller who may not see even one child on that roll must not be able to move that child's number, and there is no coarser "may this caller touch this class's roster" check that would substitute. PATCH /enrollments/:id/roll-number needs no such loop; it names exactly one pupil, resolved the same way every other single-pupil enrolment write is.
• 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.

RollNumberService.assignOnEnroll's own exhausted-retry collision has no branch in translateEnrollmentError. It runs inside ClassEnrollmentsService.enroll's try block (class-enrollments.service.ts:294), so an error it raises reaches translateEnrollmentError (enrollments-core/shared/class-enrollments.errors.ts) — verified: that function's branches match only student_class_enrollments_one_active_per_session_unique, ..._dates_ordered, ..._ended_matches_status, and ..._class_session_fk; there is no branch for student_class_enrollments_class_roll_unique. In practice this is unreachable through normal use — assignNext already retries once internally against a re-read maximum, and only a second collision on the same class within one request would re-throw past that retry. A second collision that does occur here falls through to AllExceptionsFilter's generic 23505 → 409 RESOURCE_ALREADY_EXISTS, not an unmapped 500, because the SQLSTATE is still 23505 — but the client sees the generic code rather than a roll-number-specific one, unlike a collision on the dedicated PATCH .../roll-number route, which RollNumberService.setManual catches itself and reports as ROLL_NUMBER_TAKEN.

14. Observability

15. Testing and Validation

Eight 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__/roll-number.service.integration.spec.ts (describe("RollNumberService (real database)")) — first-pupil assignment to 1; appending the next free number without moving anybody already numbered; freeing a departed pupil's number while their closed row keeps it; refusing a number another live pupil already holds; refusing a number below 1; permitting a clear to null; refusing to edit a closed enrolment's number; renumbering 1..n in admission order (compacting gaps) and alphabetically; excluding a soft-deleted pupil and a record_status-inactive pupil from a renumber; auto-renumbering the whole class on enrolment when the policy asks for it, versus leaving everyone alone when it does not; and two classes each independently holding roll number 1.

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