Exams Backend Documentation

1. Documentation Evidence

2. Backend Scope and Boundaries

Owns

• The school's own catalogue of examination types (exam_types) and configurable grading scales with GPA bands (grading_scales, grading_scale_bands).
• Examination authoring: create, update (period, name, notes), delete (draft-only, no class scope), class-scope replacement, attachments (administrator-only or audience-visible).
• Lifecycle: publish, unpublish, cancel, reinstate, complete (early or hourly-swept), archive, unarchive — one service, one transition per call, database-enforced concurrency.
• The routine builder: per-class, per-subject routine entries (date, time, room), assessment components (theory/practical/internal/viva/project/other), invigilator assignment, a swap operation that relocates two papers in one transaction, and a publish-preview/conflicts report.
• Marks: the sheet read/write against the live class roll, a five-state submission workflow (draft → submitted → returned/approved → finalized), and append-only corrections to already-finalized marks.
• Results: synchronous or queued computation of every pupil's per-subject and overall outcome, withhold/release of an individual result, and a separate results-publication gate from the exam's own lifecycle.
• Time-driven work: a 15-minute reminder sweep keyed on the live schedule, an hourly lifecycle sweep that auto-completes ended exams and emits "tomorrow"/"today" notifications.
• Notifications: one ExamNotifierService resolving recipients from live rows and the module's own rule tables, calling the shared NotificationService; one ExamNotificationScopeService doing every recipient-resolution query.
• Settings: which channels/audiences each of the seven notification events uses, and the reminder-offset list (with its own scratch-slot replace algorithm).
• The teacher, student and guardian portal surfaces for exams, results, marks entry and invigilation duties — sharing no code with the admin controllers beyond the read-only exam-shared-resolvers/exam-conflict utilities and, for marks, delegating the write itself to the admin-side marks services under a narrower predicate.
• A calendar projection (ExamCalendarProjectionService) that other modules read from — the calendar has no exam rows of its own.

Does Not Own

• Classes, sections, rooms, class-subjects, academic sessions, staff and student enrolment (academic-structure, people modules) — exams reference them but never write them.
• Storage bytes themselves (@skoolsewa/storage's StorageManager) — the module owns exam_attachments metadata and calls the manager directly; nothing here is ever signed.
• The outbox and BullMQ infrastructure (OutboxService, @skoolsewa/jobs) — the module is a producer/consumer, not the owner.
• Notification delivery mechanics (channel senders, per-user preference resolution) — NotificationService and its channel drivers own that; this module supplies templates, recipients and rule configuration.
• Authentication and role/permission evaluation (JwtAuthGuard, RoleGuard) — the module supplies @Permissions() codes for its admin surface and its own audience assertions for the portal surface.
• Timezone arithmetic itself — SchoolClockService and apps/api/src/utils/school-time/school-time.util.ts own composing a date and a minute-of-day into an instant; every exam service that needs "now" or "is this instant past" calls through them.
• The academic calendar's own day classification (academic_calendar_days) — read, never written, by ExamCalendarProjectionService and the publish-preview's school-day warning.

Source of Truth

3. Module Composition

There is no aggregate ExamsModule. Eight admin leaf modules, one workers module, and three portal leaf modules are each composed directly by app.module.ts / mobile.module.ts, mirroring how ADMIN_MODULES and MOBILE_CHILDREN must each name a module that declares its own controllers.

4. File and Directory Map

apps/api/src/modules/exams/
  authoring/
    admin/              exams.controller.ts, exam-lifecycle.controller.ts, exam-classes.controller.ts, exam-attachments.controller.ts, exams-admin.module.ts
    core/               exam-detail/write/lifecycle/classes/attachments/calendar-projection services, exam-display-status.util.ts, exam-attachments.multer.ts, dto/
  dashboard/
    admin/              exam-dashboard.controller.ts, exam-dashboard-admin.module.ts
    core/               exam-dashboard.service.ts, dto/
  grading/
    admin/              grading-scales.controller.ts, exam-grading-admin.module.ts
    core/               grading-scales.service.ts, dto/
  marks/
    admin/              exam-marks.controller.ts, exam-marks-workflow.controller.ts, exam-mark-corrections.controller.ts, exam-marks-admin.module.ts
    core/               exam-marks-sheet/workflow/mark-corrections services, exam-marks-gate.util.ts, dto/
  portal/
    core/               exam-portal-reads.service.ts, exam-portal-download.util.ts, exam-portal-core.module.ts, dto/
    guardian/           guardian-exams-portal.controller.ts, guardian-exams-portal.service.ts, guardian-exams-portal.module.ts
    student/            student-exams-portal.controller.ts, student-exams-portal.service.ts, student-exams-portal.module.ts
    teacher/            teacher-exams-portal.controller.ts, teacher-exam-marks-portal.controller.ts, teacher-exams-portal.service.ts,
                        teacher-exam-duties.service.ts, teacher-exam-marks-portal.service.ts, teacher-exam-scope.util.ts, teacher-exams-portal.module.ts, dto/
  results/
    admin/              exam-results.controller.ts, exam-results-admin.module.ts
    core/               exam-results.service.ts, exam-results-compute.service.ts, exam-result-rules.ts (+.spec.ts), exam-results-core.module.ts, dto/
  routine/
    admin/              exam-routine.controller.ts, exam-routine-entry.controller.ts, exam-day.controller.ts, exam-routine-admin.module.ts
    core/               exam-routine-read/write/swap services, exam-components-write.service.ts, exam-invigilators-write.service.ts,
                        exam-publish-preview-read.service.ts, exam-day-read.service.ts, exam-routine-core.module.ts, dto/
  settings/
    admin/              exam-notification-settings.controller.ts, exam-reminder-rules.controller.ts, exam-notification-rules.service.ts,
                        exam-reminder-rules.service.ts, exam-settings-admin.module.ts, dto/
  shared/
    exam-conflict.util.ts, exam-shared-resolvers.service.ts, exam-write.errors.ts, exams-shared.module.ts, dto/
  types/
    admin/              exam-types.controller.ts, exam-types-admin.module.ts
    core/               exam-types.service.ts, dto/
  workers/
    exam.scheduler.ts, exam-lifecycle-sweep.service.ts, exam-reminder-sweep.service.ts, exam-notification-scope.service.ts,
    exam-notifier.service.ts, exam-notify-format.util.ts, exam-result-compute.contract.ts, exam-result-compute.adapter.ts,
    exams-queue.processor.ts, exam-workers.module.ts
  __tests__/            10 integration specs + fixtures

5. Data Model

5.1 Schema Source

packages/db/src/schema/school/exams.ts

One file holds all 17 tables and 8 enums for this domain. The three GiST exclusion constraints, the two bump_row_version trigger attachments' companion DDL, and the two guard triggers live in packages/db/src/migrations/0030_exam_module_constraints_and_seeds.sql, because drizzle-kit has no builder for either an EXCLUDE constraint or a trigger.

5.2 Tables and Collections

exam_types

The school's own catalogue — Terminal, Unit Test, Pre-Board — a table rather than a pgEnum so a school can add or retire a type without a migration. Thirteen rows are seeded (FIRST_TERM … SCHOLARSHIP).

No index on is_active: the table holds a few dozen rows, and the two partial unique indexes already cover the active-row lookups. Hard DELETE is refused by exams.exam_type_id's ON DELETE restrict the moment a type is filed against.

grading_scales

Extra constraint: grading_scales_id_uses_gpa_unique — unique(id, uses_gpa), not uniqueIndex, because it is the target of grading_scale_bands' composite FK and drizzle-kit emits every ADD CONSTRAINT … FOREIGN KEY before every CREATE INDEX; a uniqueIndex here would not yet exist when the referencing FK is created, failing a clean-database migration with SQLSTATE 42830. No index on is_active: a school keeps a handful of scales.

grading_scale_bands

A band has a floor and no ceiling — see the design-decisions section. uses_gpa is a copy of the parent scale's, carried by a cascading composite FK so grading_scale_bands_gpa_complete can be a plain single-row CHECK.

Index: grading_scale_bands_scale_idx on (scale_id, min_percent) — the scan lookupBand mirrors (greatest min_percent <= pct).

exams

One examination: definition, period (an envelope, not a per-subject schedule), lifecycle and publication stamps.

Indexes: exams_session_status_idx (academic_session_id, status), exams_dates_idx (start_date, end_date), exams_type_idx, exams_grading_scale_idx. exams_id_session_unique and exams_id_status_unique are unique(...) constraints, not uniqueIndex, for the same FK-ordering reason as grading_scales_id_uses_gpa_unique.

exam_classes

Which classes sit this examination.

Unique: exam_classes_exam_class_unique (exam_id, class_id) — one scope row per class. exam_classes_id_exam_class_unique (id, exam_id, class_id) is the composite FK target for exam_routine_entries. Indexes on exam_id, class_id.

exam_routine_entries

One subject examination for one class: when it is sat, where, by whom it is invigilated.

Unique: exam_routine_entries_schedule_unique (id, exam_date, start_minute, end_minute, exam_status) — the composite FK target exam_invigilators carries by cascade. exam_routine_entries_one_paper_per_subject (exam_class_id, class_subject_id) — one paper per subject per class per exam; two papers are two components, not two entries. Indexes: exam_routine_entries_exam_idx, exam_routine_entries_class_subject_idx, exam_routine_entries_date_idx, exam_routine_entries_class_status_idx (class_id, exam_status) (the audience read), exam_routine_entries_room_idx partial on non-null room_id. Three GiST exclusions (migration 0030) — see §6.1.

exam_assessment_components

Theory, practical, internal, viva, project, other — every mark ceiling in the system. Mandatory: a subject examination with no component cannot be published.

Composite unique exam_assessment_components_id_entry_unique (id, routine_entry_id) is the FK target that carries a mark's routine entry membership. exam_assessment_components_id_max_unique (id, max_marks) is what carries the ceiling onto every exam_marks row — the mechanism behind "a mark can never exceed its ceiling"; see §6.2. Index: exam_assessment_components_entry_idx (routine_entry_id, sort_order).

exam_invigilators

Who invigilates which paper. The four schedule columns are copies of the parent's, cascade-maintained, which is the mechanism behind "moving a paper re-arms the invigilator exclusion" (§6.1).

Unique exam_invigilators_entry_staff_unique (routine_entry_id, staff_id) — its leading column also serves every per-entry lookup. Index: exam_invigilators_staff_date_idx (staff_id, exam_date). One GiST exclusion — see §6.1.

exam_marks_submissions

The marks workflow record for one subject examination — one row per routine entry.

Index: exam_marks_submissions_state_idx.

exam_marks

One pupil's mark for one component. The database guarantee described in §6.2.

Unique exam_marks_component_student_unique (component_id, student_id). Indexes: exam_marks_entry_student_idx (routine_entry_id, student_id), exam_marks_student_idx. Both FKs to exam_assessment_components are declared RESTRICT deliberately and must agree: Postgres evaluates both on a parent delete, so a RESTRICT on either aborts before the other's CASCADE could run — "restrict on one, cascade on the other" is not a mixture, it is restrict. An earlier draft had CASCADE here, which would have let a full-replacement components PUT silently delete every mark for a class.

exam_mark_corrections

The record of a change to a finalized mark. Append-only, enforced by a trigger (§9).

Index: exam_mark_corrections_mark_idx (mark_id, corrected_at).

exam_results

One computed overall result per pupil per examination.

Unique exam_results_exam_student_unique (exam_id, student_id) — the onConflictDoUpdate target for recompute. Indexes: exam_results_exam_status_idx (exam_id, status), exam_results_student_idx, exam_results_stale_idx (exam_id) WHERE is_stale.

exam_subject_results

One subject's contribution to a result — a snapshot, not a pointer.

Unique exam_subject_results_result_entry_unique (result_id, routine_entry_id) — its leading column also serves every per-result read. Index: exam_subject_results_entry_idx.

exam_notification_rules

Which channels and audiences each of the seven examination notification events uses.

exam_reminder_rules

When reminders are sent, as offsets before a paper starts.

Three rows seeded: 4320 min (3 days), 1440 min (1 day), 180 min (3 hours). Minimum spacing between two ENABLED offsets is one tick (15 min) — a service rule (EXAM_REMINDER_RULES_TOO_CLOSE), because a CHECK cannot span rows.

exam_reminder_dispatches

What the reminder sweep has already sent — the dedupe key IS the schedule.

Unique exam_reminder_dispatches_key (routine_entry_id, rule_id, exam_date, start_minute) — inserting this row IS how the sweep claims "already sent", and its leading column serves the per-entry lookups. No other index.

exam_attachments

Instructions, seating plans, circulars.

Index: exam_attachments_exam_idx (exam_id, sort_order). EXAM_ATTACHMENT is a private UploadType and must never be added to packages/storage/src/upload-type.ts's PUBLIC_TYPES — a public type is stored under public/, which the bucket policy grants anonymous s3:GetObject; verified current (PUBLIC_TYPES holds only AVATAR, LANDING, THUMBNAIL, PRODUCT_VIDEO).

5.3 Relationship Diagram

6. Services and Responsibilities

The module has 34 service/util files. This section groups them by area; §16.1 gives the full submodule coverage matrix.

6.1 ExamSharedResolversService (shared/exam-shared-resolvers.service.ts)

6.2 ExamLifecycleService (authoring/core/exam-lifecycle.service.ts)

Every transition follows the same shape: one conditional UPDATE … WHERE public_id = ? AND status IN (fromStatuses) AND version = ?. A zero-row result triggers a disambiguating re-read that never decides whether the write happens — only which error message to show (already-published vs. wrong-state vs. version conflict). bump_row_version (trigger) owns version/updated_at; the service never sets either.

6.3 ExamWriteService (authoring/core/exam-write.service.ts)

Widening the exam's period is never checked; narrowing it is refused when a routine entry would fall outside the new bound.

6.4 ExamClassesService / ExamAttachmentsService / ExamCalendarProjectionService / ExamDetailService

6.5 Routine services (routine/core/*)

Explain: input normalization happens at the DTO boundary (class-validator); validation order is always resolve-then-authorize-then-write; transaction boundaries wrap every write that touches more than one table; idempotency is explicit for complete() and for the invigilator/component full-replacement PUTs; retry behavior belongs to BullMQ for the async paths, not to these synchronous services; response mapping always re-reads the row after a write rather than echoing the request.

6.6 Marks services (marks/core/*)

6.7 Results services (results/core/*)

ExamResultComputeAdapter reads the exam's academic session lock state before dispatching a queued compute; when the year is locked it leaves the results as they are and logs a warning ([exam-result-compute] exam {examId} is in a locked academic year; results left as they are) instead of running computeNow. This is a soft skip rather than a thrown error, because the compute here runs from a worker, not from a request an administrator is watching.

6.8 GradingScalesService, ExamTypesService, ExamDashboardService, settings services

7. Runtime Flows

7.1 Publish an exam

7.2 Routine entry patch that touches a published exam's schedule

Include: success path (row 5-6 above); permission failure (missing ExamPublish_UPDATE on a schedule-touching write to a published entry); missing entity (EXAM_ROUTINE_ENTRY_NOT_FOUND); duplicate/concurrent write (EXAM_ROUTINE_ENTRY_STATE_CHANGED); a genuine schedule collision (EXAM_ROOM_CONFLICT/EXAM_CLASS_CONFLICT/EXAM_INVIGILATOR_CONFLICT, named against the exam's own siblings via loadPublishedSiblingCandidates when the collision is with a sibling of the same exam rather than a different one).

7.3 Swap two papers (deferred constraints)

The transient overlap between the two UPDATEs is legal only because the two exclusions are DEFERRABLE INITIALLY IMMEDIATE and this transaction explicitly defers them. SET CONSTRAINTS … IMMEDIATE forces the real check before the method returns, so a genuine collision with an unrelated third paper still raises 23P01 here, synchronously, rather than surfacing at an unrelated later commit.

7.4 Submit marks

Branch notes: guest/logged-in is not applicable (every exam route requires a session); the guest-equivalent branch here is "not this teacher's paper", which answers the identical 404 as "does not exist" — a 403 would confirm the paper exists. Cache miss/hit is not applicable — the module has no cache (§8). Async enqueue failure: outbox.enqueue writes inside the same transaction as the state flip, so a dispatcher outage never loses the submission, only delays its notification.

7.5 Compute results — synchronous vs. queued

runLocked takes pg_advisory_xact_lock keyed on the exam before re-reading the roll — a request and a queued job racing on one exam serialize rather than writing over each other's exam_results rows. See §9's design-decision note on why computeNow, never compute, is the worker's entry point.

7.6 Reminder sweep tick

Include: success path (above); a rescheduled paper re-arms by itself because its new (exam_date, start_minute) was never claimed; a cancelled/unpublished exam still claims the row (so it never re-fires) but sends nothing, checked by re-reading exams.status inside the same transaction as the claim; a per-candidate exception is caught, logged and does not stop the rest of the sweep.

8. Caching

The module declares no cache. No CacheKeyUtil import appears anywhere under apps/api/src/modules/exams/, and no Redis read/write occurs in any of the 34 service files read for this page. Every read — the marks sheet, the routine, the publish preview, the portal dashboards — goes to PostgreSQL directly, on every request. This is a deliberate absence, not a gap: the module's write paths are already gated by the version optimistic-concurrency column and, for schedule conflicts, by the database's own GiST exclusions, so a stale cache read would be the one path capable of showing a slot as free after it had just been taken.

9. BullMQ, Schedulers, and Async Work

Both sweeps exclude a locked academic year. ExamLifecycleSweepService and ExamReminderSweepService both filter their candidate query on isNull(academicSessions.lockedAt) — a locked year is historical, so its exams are neither auto-completed nor still sent reminders. exam_reminder_dispatches' own claim row is not enough on its own to stop a reminder for a locked year, because the claim only prevents a duplicate of a dispatch that already ran; the lockedAt filter is what stops a new one starting.

Every enqueue goes through the transactional outbox. Every outbox.enqueue call site above runs inside the same db.transaction as the business write it accompanies — a direct queue.add() in a request handler is a defect this repo has already paid for once (a queue sweep that silently never ran). The outbox row this module writes carries aggregateType, aggregateId, eventType, targetQueue: QueueName.EXAMS, jobName: ExamJob.<member>, an optional dedupeKey, and payload.

compute vs. computeNow. ExamsQueueProcessor's handler map is Record<ExamJob, handler>, so ExamJob.RESULT_COMPUTE needs a compile-time handler even though the computation logic belongs to the results area — ExamResultComputeRunner (an abstract-class DI token) is the seam, and ExamResultComputeAdapter binds it to ExamResultsComputeService. The adapter calls computeNow, never compute: compute is the request path and itself enqueues ExamJob.RESULT_COMPUTE when the roll exceeds EXAM_SYNC_COMPUTE_MAX_STUDENTS. A worker bound to compute would re-enqueue the very job it is running, and because the enqueue carries a per-exam dedupeKey, the repeat write would be swallowed as idempotent rather than looping visibly — the queue would drain, every gate would stay green, and no result would ever be computed for exactly the large exams the asynchronous path exists to serve. computeNow always runs inline because the worker is already off the request path and has no response-time budget to protect.

Concurrency 1. ExamsQueueProcessor declares @Processor(QueueName.EXAMS, { concurrency: 1 }) — every job here is either a whole-school sweep or a single exam's notification fan-out, both idempotent by construction (a claimed dispatch row, a collapse/repeatable dedupe key), so nothing needs to run concurrently with itself.

10. Realtime and Events

The module emits no Socket.IO/SSE realtime event. The only "realtime" signal is exam.marks_submitted, and it travels through the ordinary notification pipeline (kind: "exam.marks_submitted", channels: ["in_app"], audience {kind:"role", rolePublicIds} resolved from every role currently holding ExamMarksVerify_READ) rather than the module registry modules/realtime/shared/realtime.contract.ts uses — that registry currently carries exactly one live mapping (feedback.submitted) and this module does not add to it.

11. Security, Auth, and Abuse Controls

Guards. JwtAuthGuard is global; every exam route requires a session. RoleGuard enforces every admin controller's @Permissions() code (see §13's permission table). The three portal modules carry no @Permissions() at all.

Permission catalogue (13 modules). ExamTypes, Exams, ExamPublish, ExamCancel, ExamRoutines, ExamMarks, ExamMarksVerify, ExamMarksCorrect, ExamResults, ExamResultPublish, ExamGrading, ExamNotificationSettings, ExamView (packages/db/src/authorization/permission-catalog.ts). ExamPublish and ExamResultPublish are the only two also listed in SUPERADMIN_ONLY_MODULES — both authorize a change that reaches an already-published/family-visible row, and a grant can never be revoked (grantToRoles uses onConflictDoNothing), so both start with admin restricted to superadmin and widen only by deliberate role creation. ExamView appears on zero API routes — it is the audience-screen code that makes the exams tile safe to hand to a pupil.

ExamMarks must never be granted to STAFF_PERMISSIONS/TEACHER_PERMISSIONS. It is the unscoped whole-school code; a teacher's own marks access is the scoped portal route (TeacherExamMarksPortalService), which asserts a live staff row and then filters class_subjects.teacher_id = :myStaffId. The permission catalogue's own comment names the one-line "fix" an executor might reach for — adding the code to the teacher role — as exactly the mistake this predicate exists to avoid, because the grant, once made, can never be taken back.

Portal routes carry no @Permissions() and assert their audience instead. TeacherExamsPortalController, TeacherExamMarksPortalController, StudentExamsPortalController and GuardianExamsPortalController — 20 handlers across the four — are each registered as a key in NO_PERMISSION_ADMIN_HANDLERS (apps/api/src/common/authorization/role.guard.ts) and mirrored in apps/api/test/structure/route-permissions.spec.ts; verified identical in both files this session. Missing the role.guard.ts entry makes the handler 403 for every caller including superadmin, with a fully green integration suite (the specs call services directly and never pass through the guard). Missing the spec entry fails test:structure instead. Both are required because each is the only place a different failure mode is caught.

The teacher predicate is a plain eq, never IS NOT DISTINCT FROM. subjectTeacherExists/invigilatorExists (teacher-exam-scope.util.ts) and the identical inline predicate in TeacherExamMarksPortalService.isAuthorized all compare class_subjects.teacher_id = :staffId with an ordinary equality — IS NOT DISTINCT FROM would match every unassigned (NULL) row, handing every teacher every unassigned subject's papers.

The submitted_by_staff_id OR-arm is deliberate. A teacher's access to a marks sheet is class_subjects.teacher_id = me OR exam_marks_submissions.submitted_by_staff_id = me. Reassigning a subject must not simultaneously strip the previous teacher of a submission they already made and hand the new teacher every past examination's marks — the snapshot column exists for exactly this, and the predicate is what makes the snapshot load-bearing rather than decorative.

404, never 403, on a scoped miss. Every portal read — resolveExamInScope, TeacherExamsPortalService.resolveExamInScope, TeacherExamMarksPortalService.assertAccess — answers the identical EXAM_NOT_FOUND/EXAM_ROUTINE_ENTRY_NOT_FOUND whether the exam does not exist, is not in the caller's scope, or (on the result route) has not had its results published yet. A 403 on any one of those would disclose that the exam exists and that the specific pupil sat it — an id space over a school's own children must not become an enumeration oracle.

Guardian order of operations. GuardianExamsPortalService.resolveChild calls guardianPortal.resolveOwnChildId before any exam predicate runs. A foreign childId is refused by the guardian's own ownership check first; only after it succeeds does ExamPortalReadsService ever see the request.

EXAM_ATTACHMENT is a private upload type, verified absent from PUBLIC_TYPES in packages/storage/src/upload-type.ts this session. A public type is served from the public/ prefix, which the bucket policy grants anonymous s3:GetObject — a question paper there would be readable by the whole internet before the exam is sat. The generic upload-proxy route is also closed to it (ownership-only, and an exam attachment's owner is the administrator who uploaded it), so the only path a pupil, teacher or guardian reaches an audience-visible attachment through is the portal download route, which checks the exam is published/scoped and visibility='audience' before opening the stream.

Download headers. setExamAttachmentDownloadHeaders sets X-Content-Type-Options: nosniff, Cache-Control: private, no-store, a sandboxed Content-Security-Policy: sandbox; default-src 'none', and always Content-Disposition: attachment — a question paper or seating plan is never rendered inline in the API's own origin.

Fail-closed defaults. EXAM_ATTACHMENT.visibility defaults to administrator_only; a pupil never sees an attachment unless an administrator explicitly flips it to audience. exam_notification_rules.notify_invigilators is CHECK-refused outside its three applicable events. exam_attachment.storage_key uploads are never client-named — the caller supplies a file, StorageManager decides the key.

A locked academic session makes an exam's whole record read-only, enforced at the database. Once academic_sessions.locked_at is set, Postgres triggers refuse INSERT/UPDATE/DELETE on exams, exam_classes, exam_routine_entries, exam_assessment_components, exam_invigilators, exam_marks_submissions, exam_marks, exam_results, exam_subject_results and exam_attachments — every one of them resolved back to the exam's academic_session_id (packages/db/src/migrations/0038_year_lock_records.sql). The refusal is a fixed trigger message, ACADEMIC_SESSION_LOCKED, caught by AllExceptionsFilter's GUARD_MESSAGES map and returned as 409 ACADEMIC_SESSION_LOCKED with the message "That academic year is locked, so its records can no longer change. An administrator can unlock the year to make a correction." exam_mark_corrections carries no trigger of its own — the edit to the exam_marks row a correction accompanies is what the lock actually refuses. A write nested inside a cascade (pg_trigger_depth() > 1, e.g. a pupil's erasure) always passes, so archiving or erasing a person does not require unlocking their exam history first.

ExamDetailService reads academicSessions.lockedAt alongside the exam row and exposes it on ExamDetailDto.academicSessionLocked, so the admin screen can render the exam read-only without a separate lock lookup.

Rate limits / anti-abuse. No exam-specific rate limiter exists; the module relies on the platform-wide guards (JwtAuthGuard, upload size/type validation in StorageManager) for abuse resistance. There is no bulk-export or unbounded-read route in this module — every list route is either paginated (PaginationUtil) or capped at PaginationUtil.UNPAGINATED_HARD_CAP with a truncated flag rather than an unbounded fetch.

13. Error Handling

55 EXAM_*/GRADING_SCALE_* codes are declared under the "EXAMINATIONS AND RESULTS" heading in apps/api/src/common/types/error-codes.ts (counted directly against the file this session — an earlier estimate of 62 does not match the current tree; the code is the source of truth).

14. Observability

15. Testing and Validation

Validation commands:

pnpm --filter @skoolsewa/api test          # unit + integration, real Postgres/Redis/Mongo
pnpm --filter @skoolsewa/api test:structure       # route/guard/tag fingerprint
pnpm rules                                  # error-codes, module-size, module-shape, job-ids, env-orphans
find apps packages -name '*.tsbuildinfo' -not -path '*/node_modules/*' -delete && pnpm check-types

16. Mandatory Backend Deep-Dive Pack

16.1 Submodule Coverage Matrix

16.2 UML and Architecture Diagram Pack

16.3 Code Flow Narrative

ExamLifecycleService.publish (the module's most consequential write):

ExamResultsComputeService.compute → runLocked:

16.4 Data Layer Deep Dive

Every table's full field-level detail is in §5.2. This subsection adds the index-rationale table the format requires.

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 the module directory is represented or explicitly marked non-runtime (DTO files summarized by directory, not individually — their shapes belong to the API doc).
• Every controller, service, provider, processor, scheduler, helper, mapper, DTO, enum, and schema is documented.
• Every method with business behavior has a code-flow narrative (§16.3 covers the two highest-complexity methods in full; §6's tables cover every other method's reads/writes/side-effects/errors).
• Every table/collection/cache object/job payload has field-level detail (§5.2, §9).
• Every index, constraint, relation, and delete behavior has rationale (§5.2, §16.4).
• Every lifecycle/status transition has a state diagram and transition table (§16.2, §6.2).
• Every read/write/action/job flow has sequence and activity diagrams (§7, §9).
• Every business invariant is cataloged (§16.5).
• Every cache key, invalidation path, queue job, realtime event, and external call is documented (§8 states the absence of a cache; §9, §10).
• Every architectural tradeoff is documented with alternatives and revisit triggers (§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, schema file, job, cache key, and event is covered (§3, §4, §5, §9, §10; no cache exists, stated in §8).
• Every database table/collection has a field table and relationship diagram (§5.2, §5.3).
• Every runtime flow has a diagram and branch notes (§7).
• API, feature/flows, and TDD docs are linked (below).
• No claim is made without a source file or documented source reference — every table, constraint, permission code and error code in this page was read directly from the current tree this session.

See Also

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