Classes Features and Flows

1. Documentation Evidence

2. Feature Summary

3. Actor Matrix

4. Capability Matrix

5. User-Facing Flows

5.1 List grades

Summary

An admin, staff member, or teacher opens a grade select — the admission form, the class-setup screen — and the full grade list loads. There is no create, update, or delete for a grade anywhere in this module; grades are seed data.

Preconditions

• Valid JWT with an active role holding Classes_READ — grades have no permission module of their own.

Main Flow

Sequence Diagram

Branches and Edge Cases

5.2 List, create, rename, reorder, retire, and delete a section

Summary

An admin manages the A/B/C/D-style subdivisions a grade is split into, from a section-setup screen. The shape mirrors departments/designations in the school module: hard delete, guarded by whatever still references the row.

Preconditions

• Sections_READ/_CREATE/_UPDATE/_DELETE as appropriate.
• Create/rename: no other active section shares the name, case-insensitively.
• Delete: no class currently references this section.

Main Flow

Sequence Diagram

Branches and Edge Cases

5.3 List, create, update, and delete a room

Summary

An admin manages the school's physical rooms — number, floor, building — typically maintained by facilities staff who have no reason to create classes.

Preconditions

• Rooms_READ/_CREATE/_UPDATE/_DELETE as appropriate.
• Create/rename: no other active room shares (building, roomNumber), case-insensitively.
• Delete: no class currently references this room.

Main Flow

Sequence Diagram

Branches and Edge Cases

5.4 List and filter classes

Summary

An admin, staff member, or teacher opens the class-setup or class-listing screen for a given academic session (defaulting to whichever session is marked current) and sees every class with its live enrolment count, room, and class teacher.

Preconditions

• Classes_READ.
• pagination must not be false — see the edge case below.

Main Flow

Sequence Diagram

Branches and Edge Cases

5.5 Read the class options list

Summary

The admission form's grade → section → shift cascade, and the capacity chart, both call the same unpaginated, person-data-free endpoint rather than the full class list — the admission clerk does not hold Students_READ scope over every pupil in the school, but does need to know which classes exist and how full they are.

Preconditions

• Classes_READ.

Main Flow

Sequence Diagram

Branches and Edge Cases

5.6 Read a single class

Summary

An admin opens a class's detail view — from the list, or by direct link — and sees the full ClassDto, including its live enrolment count.

Preconditions

• Classes_READ.
• The class exists.

Main Flow

Branches and Edge Cases

5.7 Create a class

Summary

An admin sets up a new class: one grade, one section, one shift, in one academic session, with a capacity and optionally a room and a class teacher.

Preconditions

• Classes_CREATE.
• The academic session, grade, and section all exist and are active.
• No existing class already has this exact (session, grade, section, shift) identity — including one that has since been retired.
• If a room is given: it exists and is active, and no other active class already holds that room in the same session and shift.
• If a class teacher is given: the staff member exists, is not soft-deleted, holds a teaching designation, and is not already class teacher of another active class in the same session and shift.

Main Flow

Sequence Diagram

Branches and Edge Cases

5.8 Update a class

Summary

An admin edits a class's name, capacity, room, class teacher, or active flag. The four identity fields — session, grade, section, shift — can never be part of this request.

Preconditions

• Classes_UPDATE.
• The class exists.
• Lowering capacity below the live enrolment count requires allowOverCapacity: true.

Main Flow

Sequence Diagram

Branches and Edge Cases

5.9 Delete a class

Summary

An admin permanently removes a class created in error. Blocked while any enrolment — of any status — still references it.

Preconditions

• Classes_DELETE.
• No student_class_enrollments row references this class.

Main Flow

Branches and Edge Cases

5.10 View a class's roster

Summary

An admin, staff member, or teacher opens a class and sees the pupils currently (or previously, by status filter) enrolled — scoped to exactly the pupils their role is permitted to see, never the class's full roll unconditionally.

Preconditions

• Students_READ.
• The class exists.
• pagination must not be false.

Main Flow

Sequence Diagram

Branches and Edge Cases

5.11 Enrol or transfer a pupil into a class

Summary

One route does both jobs. Admitting a new pupil and moving an already-enrolled pupil to a different class in the same session are the same call — the backend decides which case applies from what it finds.

Preconditions

• Students_UPDATE.
• The target pupil is inside the caller's object-level scope.
• The target class exists and is active.
• The pupil is not soft-deleted.
• The enrolment date falls within the class's academic session and on or after the pupil's admission date.
• The class has room, or allowOverCapacity: true is set.

Main Flow

Sequence Diagram

Branches and Edge Cases

5.12 Withdraw a pupil from a class

Summary

An admin records that a pupil has left the school (or this class) — distinct from deleting an enrolment entered by mistake.

Preconditions

• Students_UPDATE.
• The target pupil is inside the caller's object-level scope.
• An active enrolment for this pupil in this class exists.

Main Flow

Sequence Diagram

Branches and Edge Cases

5.13 Correct an enrolment's date or status

Summary

An admin fixes a typo'd enrolment date, or manually flips a status without going through the enrol/withdraw endpoints — for example, backfilling a historical record during data migration.

Preconditions

• Students_UPDATE.
• The target pupil (resolved from the enrolment row) is inside the caller's scope.
• The enrolment exists.

Main Flow

Branches and Edge Cases

5.14 Remove an enrolment entered in error

Summary

An admin deletes a row that should never have existed — the wrong class was picked, or a duplicate submission slipped past a race. Distinct from withdrawal: this leaves no trace in the transferred/withdrawn counters.

Preconditions

• Students_UPDATE.
• The target pupil (resolved from the enrolment row) is inside the caller's scope.
• The enrolment exists.

Main Flow

Branches and Edge Cases

5.15 View a pupil's own class history

Summary

A pupil's profile screen shows every class they have ever held an enrolment in, across every session, newest first — the one active row per year plus any transfers and withdrawals.

Preconditions

• Students_READ.
• The caller's scope covers this pupil.

Main Flow

Branches and Edge Cases

5.16 See and change a pupil's class from the pupil's own screens

The class module makes a pupil's class settable from the class roster. These three surfaces put it where the office actually looks a pupil up.

Where it appears

What "the pupil's class" means. Their active enrolment in the current academic session. Both halves matter. Without status = 'active' a pupil who transferred out still reads as being in the class they left; without the session pin they read as being in last year's class all through the gap between sessions — a confident wrong answer where null is the correct one. A pupil with no class, and every pupil while no session is current, reads null. That is an ordinary state: a pupil can be admitted before their class is decided.

currentClass carries classId, gradeName, sectionName, shift and the optional class name. It deliberately carries no capacity or occupancy — those belong to the class, and the one screen that needs them reads /classes/options, the same endpoint the capacity chart uses, so the two can never disagree.

Changing it. PATCH /students/:id with a classId enrols or transfers, in the same transaction as the rest of the pupil's edit, through the same enroll() the class roster uses. So a transfer made here closes the previous enrolment as transferred and writes the same activity record as one made from the roster.

Three rules are worth knowing before using it:

• Omitting classId leaves the class alone, and no value clears it. Taking a pupil out of a class with nowhere to put them is a withdrawal — it needs a date and a reason and it changes the class's roll — so it stays on the class roster where those are in view.
• The class must belong to the current session. A class from another session is refused with ENROLLMENT_SESSION_NOT_CURRENT. The roster route does not apply this rule: it names its class in the URL, so choosing another year there is a deliberate act. This form sends a bare id, and without the rule it would return 200, write a second active enrolment in a session the pupil record does not read from, and appear to have done nothing.
• The pupil's version now covers their class. Every enrolment write touches students.updated_at, so a transfer made from the class roster invalidates a pupil edit form that was already open. Saving it is refused with PEOPLE_STALE_RECORD rather than silently moving the pupil back.

Errors it can return: CLASS_NOT_FOUND, CLASS_INACTIVE, CLASS_AT_CAPACITY (retry with allowOverCapacity: true), ENROLLMENT_SESSION_NOT_CURRENT, ENROLLMENT_DATE_OUTSIDE_SESSION, ENROLLMENT_DATE_BEFORE_ADMISSION, PEOPLE_STALE_RECORD.

Cache. The roll is cached for 120 seconds. Every enrolment write drops that cache, and so does a change of which session is current — without the second, moving is_current would leave every pupil showing last year's class for two minutes.

6. Admin Flows

6.1 Create

Sections, rooms, and classes each have their own POST — see 5.2, 5.3, 5.7. Grades do not — see 12.3 for why there is no POST /api/grades.

6.2 List / Read Detail

Grades/sections/rooms have list-only surfaces (no single-resource "read one" route — the list is the only read). Classes have both: 5.4 for the list and 5.6 for a single row, plus the person-data-free 5.5 variant.

6.3 Update

See 5.2, 5.3, 5.8. Every update is a PATCH with independently optional fields; a class's four identity fields are permanently excluded from the update DTO.

6.4 Reorder

Applies to grades and sections only, via sort_order — grades are seed-managed and have no reorder route; sections can set sortOrder explicitly on create or update. Rooms and classes carry no position column — a room list is ordered by building/floor/number, and a class list by grade/section/shift, both fixed.

6.5 Activate/deactivate

Covered by isActive on sections/rooms/classes — see 5.2, 5.3, and the isActive branch of 5.8. For a class specifically, deactivation is unconditional — it never checks for existing enrolments, and it never frees the class's identity, only its room and class-teacher slots (see 7).

6.6 Soft delete

Not applicable. None of grades, sections, rooms, or classes has a deleted_at column — is_active is the retirement mechanism instead, for the same reason as the school module's lookup tables: a soft-deleted row never fires ON DELETE restrict/set null correctly.

6.7 Restore

Not applicable — there is nothing to restore. The permission catalog still generates Sections_RESTORE/Rooms_RESTORE/Classes_RESTORE (every module gets every action by the catalog's own generation rule), but no route in this module ever checks any of them. Grades has no _RESTORE code because grades has no permission module at all.

6.8 Hard delete

See 5.2, 5.3, and 5.9. Every one names the exact blocking reference rather than surfacing an unmapped foreign-key failure — the room case is the sharpest version of this, since classes.room_id ON DELETE set null would otherwise let the delete succeed and silently blank a class's room.

6.9 Export/import

Not owned by this module. apps/api/src/common/types/error-codes.ts defines import-time codes for other reference tables, but no IMPORT_UNKNOWN_GRADE/SECTION/ROOM/CLASS code exists in this document's error section — bulk import of pupils into classes, if it exists elsewhere, is outside this module's scope.

6.10 Moderation

Not applicable. Nothing in this module requires approval or a review queue — every mutation an actor with the right permission (and, for enrolments, the right scope) makes takes effect immediately.

6.11 Manual retry

Not applicable. No job, queue, or async operation exists in this module to retry — every operation is a single synchronous request/response, wrapped in a database transaction where correctness requires it (class creation, class update, every enrolment write).

6.12 Enrolment desk (this module's distinctive admin surface)

The four enrolment-specific routes — enrol/transfer (5.11), withdraw (5.12), correct (5.13), and remove (5.14) — are the one part of this module with no equivalent in the school module's lookup CRUD. All four share one row-lock discipline (the owning class is always locked FOR UPDATE before the write), one constraint-translation table, and the same PeopleAccessService.assertCanAccess boundary check performed by the caller, not the service.

7. Lifecycle and State Transitions

7.1 A class's isActive flag

Not a state machine — a boolean, exactly like sections/rooms/the school module's lookup tables. The distinguishing fact for a class specifically is what deactivation does not do:

7.2 A student's enrolment status

A real, enforced state machine — the only one in this module, and one of very few in this codebase enforced partly by a database CHECK rather than by the service alone.

There is deliberately no completed status. Year rollover and promotion are a deferred feature; an enrolment in a past academic session simply stays active forever, which is unambiguous because the row names its own session and academic_sessions.is_current says which year is now.

9. Data and Side Effects by Flow

Every enrolment write also produces an explicit ActivityRecordService.recordActivity call — ENROLL/TRANSFER/WITHDRAW/ENROLLMENT_UPDATE/ENROLLMENT_DELETE — in addition to whatever the global ActivityAuditInterceptor records automatically from the route's own @Permissions() and status code. See the backend doc's Observability section for why both exist.

10. Error and Recovery Flows

11. Diagrams Required Per Module

• Actor capability diagram: 3. Actor Matrix and 4. Capability Matrix.
• High-level module flow diagram: the route-ownership diagram in the API doc §9.1.
• Sequence diagram for each major flow: provided per-flow in 5.
• State machine diagrams for both lifecycles: 7.1 and 7.2.
• Data side-effect diagram for write flows: 9.
• Error branch diagram: 6.8 and the API doc's §9.3.

12. Mandatory Feature and Flow Deep-Dive Pack

12.1 Feature Inventory With Minor Behaviors

Rules from the format are honored above: no restore/retry/fallback/cache-miss/duplicate-action/permission-failure behavior has been grouped away, even where the underlying rule might look too small to mention on its own.

12.2 Business Process Diagram Pack

12.3 Business Rules and Policy Traceability

12.4 Tradeoffs and Product Rationale

12.5 Flow Edge-Case Matrix

12.6 Flow-to-Data Trace

12.7 Experience Quality Checklist

• The doc explains what the actor is trying to accomplish (define the year's classes; place, move, and remove pupils from them correctly).
• The doc explains what the backend does that the actor does not see (row locking, the ascending-lock-order deadlock avoidance, the occupancy/roster shared filter, the identity-vs-resource uniqueness asymmetry).
• The doc covers every minor flow and branch, including ones a casual read of the controllers would group away (re-sent-unchanged room/teacher skipping re-validation, sort/order being silently ignored everywhere in this module).
• The doc includes admin, staff/teacher, and (explicitly, by absence) guest and worker/system coverage.
• The doc explains business logic, tradeoffs, and rationale (§12.3, §12.4).
• The doc maps every flow to API routes and backend side effects (§12.6, and every flow's Main Flow table).
• The doc includes diagrams appropriate to each flow type (sequence per flow, two state diagrams, one error-branch flowchart, two flow-to-data diagrams).
• The doc covers edge cases and failure recovery (§10, §12.5).

13. Completion Checklist

• Every feature, minor action, and submodule capability is listed (§4, §12.1).
• Every actor has allowed and forbidden behavior listed (§3) — including the actors that do not exist for this module (guest, worker/system), stated explicitly rather than omitted.
• Every major and minor flow includes steps, branches, and diagrams (§5).
• Both real lifecycles (isActive on classes, enrollment_status) have transition tables and state diagrams (§7).
• Every flow links to the API and backend docs.
• No claim in this document is unverified against the current source files cited in the backend and API docs, including the constraint probe's accept/reject cases.

See Also

• API doc: /docs/developer/classes/api
• Backend doc: /docs/developer/classes/backend