Exams - API Reference

Audience: Frontend engineers (the admin panel), teacher/student/guardian-portal engineers, backend engineers, QA. Scope: Admin, teacher-portal, student-portal, and guardian-portal surfaces owned by the Exams module, plus the one teacher-schedule aggregator route that surfaces exam invigilation duties. 80 routes total (58 admin, 22 audience).

1. Documentation Evidence

2. Module Summary

3. Concepts and Terminology

On version — read this before writing an integration against any write route. Unlike a module where every entity's version is a uniform opaque string, this module has two genuinely different mechanisms, and mixing them up produces a type error the compiler will not catch on either side of the wire:

• String tokens, bumped by a database trigger, never re-parsed as a number. exams, exam_types, grading_scales, exam_marks_submissions, exam_marks, exam_results, exam_notification_rules, exam_reminder_rules — every one of these stores version as bigint, but the service layer stringifies it on read (String(row.version), or the shared versionOf()/matchesVersion() helpers in apps/api/src/modules/people/shared/row-version.ts) and every DTO types the field string. A stale token is refused with EXAM_VERSION_CONFLICT (or, for the marks submission state machine specifically, EXAM_MARKS_SUBMISSION_VERSION_CONFLICT).
• Plain integers, incremented by the service itself, never touched by a trigger. exam_routine_entries and exam_assessment_components type version as a JSON number on the wire (@IsInt() @Min(0) on every request DTO that carries one — PatchExamRoutineEntryDto, SwapExamRoutineEntriesDto, PutExamComponentDto), and the service computes the next value itself (set.version = dto.version + 1) inside the same UPDATE's WHERE clause. A client must send back the exact integer last read, and the server — not a trigger — decides the next one. ExamRoutineWriteService.patch names the refusal EXAM_ROUTINE_ENTRY_STATE_CHANGED, not EXAM_VERSION_CONFLICT, because the same WHERE clause also re-checks exam_status (a publish landing between a caller's read and their edit is exactly as much a conflict as a stale counter).

A frontend or mobile client that formats every version field as a string before sending it back will send "3" where the routine-entry and component routes expect the JSON number 3 — and the global ValidationPipe's @IsInt() on those DTOs rejects a string with a 400, not a silent coercion.

4. API Surface Map

Note on Nest route resolution: ExamsController, ExamLifecycleController, ExamClassesController and ExamAttachmentsController all share the base path exams. Static segments (publish, classes, attachments) are declared as literal children of :publicId, and ExamsController's own GET :publicId is registered after nothing collides with it, so no controller's route is shadowed. ExamRoutineController is declared with the controller-level path exams/:publicId (not exams), giving it routine, conflicts and publish-preview as literal children one level under the id — Express distinguishes these from ExamsController's bare :publicId by segment count, never by declaration order between the two classes. ExamResultsController similarly declares exams/:publicId/results as its controller-level path, with compute, publish and unpublish registered before the trailing :studentPublicId parameter route inside that class. ExamRoutineEntryController declares swap before :publicId, so a literal path segment can never be swallowed as an id.

5. Auth, Identity, and Permissions

Every endpoint requires a valid session (JwtAuthGuard is global with no @Public() opt-out anywhere in this module). No guest/anonymous access exists on any exams route. No route in this module carries an IP-throttle guard — not the attachment upload, not any of the six attachment-download routes across the three audiences — which is a deliberate difference from modules (such as Assignments) that throttle their upload/download surface; verified by grepping every controller file in modules/exams/ and modules/mobile/teacher/ for IpThrottlerGuard/Throttle, with zero matches.

The admin surface is permission-gated; the audience surface is not. A portal handler declares no @Permissions() at all. RoleGuard returns true for it purely because its handler key sits on the NO_PERMISSION_ADMIN_HANDLERS allowlist — before the guard ever reads request.user or checks activeRole. From that point on, the ONLY control standing between the caller and the data is the route's own call into assertPortalAudience/assertTeacherStaffRow/assertStaffRow, followed by the query the service builds. Teacher and staff roles both carry scopeKind: "all" and hold Students_READ by default (TEACHER_PERMISSIONS = STAFF_PERMISSIONS), so scoping a portal route through the general-purpose PeopleAccessService.scopeFor would silently hand every pupil's exam data to any staff session — which is exactly why every read here builds its own predicate instead.

A 404 on the audience surface is deliberately ambiguous. ExamPortalReadsService.resolveExamInScope throws one EXAM_NOT_FOUND for three different truths: the exam does not exist at all; it exists but the pupil's class was never in its scope; and (on the result route specifically) the exam exists and is in scope but results are not yet published, or the pupil's own result row is withheld. A 403 on any of these would itself leak information — "this exam exists and your child sat it" — to a caller probing an id space over a school's examinations. resolveAudienceAttachment follows the identical pattern for attachment downloads: "exam not in your scope", "attachment does not exist", and "attachment exists but its visibility is administrator_only, not audience" answer three different codes (EXAM_NOT_FOUND, EXAM_ATTACHMENT_NOT_FOUND, EXAM_ATTACHMENT_NOT_AUDIENCE_VISIBLE) but every one of them is a 404. No consumer should try to distinguish these from the status code or message alone.

Each audience's actual scope, precisely:

• Student: every exam whose exam_classes includes a class the pupil is active-enrolled in for THAT exam's own academic session — never "the current session" — so a promoted pupil keeps reading a past, still-published exam. draft exams are never visible; every other status was, at some point, a live decision for that pupil.
• Guardian: identical scope, applied per linked child, after the child-binding check.
• Teacher: every exam where the caller is the CURRENT class_subjects.teacher_id (isActive: true) for at least one routine entry, OR is listed in exam_invigilators for at least one entry. The marks read/write/submit routes narrow further — see §6.13's callout — to class_subjects.teacher_id = me OR exam_marks_submissions.submitted_by_staff_id = me, so a reassigned teacher keeps access to marks they already submitted without regaining access to a subject's future papers.

6. DTO and Model Reference

6.1 CreateExamDto

There is no clientRequestId/idempotency key on exam creation — unlike Assignments' POST, a replayed POST /exams creates a second draft exam rather than returning the first.

6.1a UpdateExamDto

Every field optional except version, which the class marks ! (required) despite @ApiPropertyOptional on the decorator — a documentation artifact in the source, not a real optionality; the DTO always requires it.

academicSessionId is absent from this DTO and cannot be changed after create — exam_classes' composite foreign key proves every attached class belongs to the exam's own session, so moving an exam between sessions would need to re-validate or silently orphan every attached class. No route in this module moves an exam between sessions.

6.2 ExamListItemDto / ExamDetailDto (response)

6.3 ExamClassRefDto / ReplaceExamClassesDto

ReplaceExamClassesDto.classIds: uuid[], @IsUUID(each:true), @ArrayUnique() — a full replacement of the exam's class scope, validated against classes in the exam's OWN academic session. Removing a class that already has recorded marks anywhere under it is refused whole: 409 EXAM_CLASS_HAS_RECORDED_MARKS, naming every offending class.

6.4 ExamAttachmentUploadDto / ExamAttachmentDto

Files land under uploads/exam-attachment/<uploaderUserId>/… (never public/) — private storage, matching the notice-attachment pattern; nothing about this route is ever a signed URL. The audience download routes read the bytes only after their own visibility check (§5).

6.5 VersionDto / CancelExamDto (lifecycle request bodies)

Every lifecycle POST except cancel takes only { version: string }. cancel extends it:

6.6 ExamTypeDto / CreateExamTypeDto / UpdateExamTypeDto

Response (ExamTypeDto) adds id (internal int PK — the one deliberate exception on this table, matching PermissionDto.id), publicId, version (string), createdAt, updatedAt. DELETE is a genuine hard delete (ON DELETE restrict from exams.exam_type_id), refused with 409 EXAM_TYPE_IN_USE while any exam still references it, and — unlike every other delete route in this module — takes no version at all: DELETE /api/exam-types/:publicId carries no body and no ?version= query param.

6.7 GradingScaleDto and bands

Response GradingScaleDto: id (this is the scale's publicId, aliased — there is no separate internal-id field on the wire here), name, usesGpa, conditionalPassMaxFailedSubjects, isActive, isDefault, bands[], version (string).

GradingScaleBandDto (response, one per band): gradeLabel, minPercent, maxPercent (derived — the next-higher band's minPercent minus 0.01, or null for the top band; never stored, because "a band has a floor and no ceiling" is the schema's own construction), gradePoint (number | null), isPassing, sortOrder.

GradingScaleBandInputDto (request, for PUT :id/bands): gradeLabel (≤8 chars), minPercent (0..100, 2 decimals), gradePoint (optional, 0..5), isPassing (boolean), sortOrder (optional int). maxPercent is never accepted as input — sending it is silently dropped by whitelist... actually, the global forbidNonWhitelisted pipe means sending it 400s the whole request, since it is not a declared field.

ReplaceGradingScaleBandsDto: { version: string; bands: GradingScaleBandInputDto[] } (1-30 entries) — a full replacement inside one transaction (delete every existing band, insert the new set), versioned against the SCALE's own token since bands carry none of their own. PATCH/DELETE/PUT .../bands all use EXAM_VERSION_CONFLICT for a stale token (this module has no dedicated GRADING_SCALE_VERSION_CONFLICT code).

6.8 Routine entry DTOs

CreateExamRoutineEntryDto (POST /exams/:publicId/routine):

Creating the entry ALSO inserts one default assessment component, copying class_subjects.max_marks/pass_marks — a simple subject is publishable with no further setup.

PatchExamRoutineEntryDto: every schedule/room/text field optional (an absent field keeps its stored value), plus a required version (int). classId/classSubjectId are never patchable — changing the subject a paper is for is a delete-and-recreate. Changing examDate/startMinute/endMinute/roomId on an entry whose exam is published/completed additionally requires the ExamPublish_UPDATE permission (403 PERMISSION_INSUFFICIENT otherwise) and emits an exam.schedule_changed notification; a text-only edit does neither.

SwapExamRoutineEntriesDto: { entryPublicId, version, otherEntryPublicId, otherVersion }, all versions int. Swaps two papers' examDate/startMinute/endMinute/roomId atomically using SET CONSTRAINTS … DEFERRED so neither UPDATE transiently collides with the other's old slot — see §11.

ExamRoutineEntryDto (response): publicId, classId (the class's publicId, confusingly reusing the same field name as the request DTO's internal-class-id meaning — the two are NOT the same shape, see the field-by-field distinction in the source), className, classSubjectId, subjectName, examDate, startMinute, endMinute, roomId (int | null), roomName (string | null), examCenter, notes, internalNote (this route is admin-only, so it IS included here — every portal DTO omits it), isCompleted, completedAt (ISO string | null), version (number, not a string — see §3), components[], invigilators[].

6.9 PutExamComponentsDto / ExamComponentDto

PutExamComponentDto (request row): kind (enum, §7), label (≤64 chars), maxMarks (0.01..1000, 2 decimals), passMarks (0..maxMarks), sortOrder (optional int), id (optional int — present to update an existing row, absent to create one), version (optional int — enforced ONLY when supplied, so a brand-new row added alongside existing ones in the same request carries no token to check). A row with an id not found on this entry is 404 EXAM_COMPONENT_NOT_FOUND; a stale version on one that IS found is 409 EXAM_VERSION_CONFLICT, naming which numbered component in the request failed. An existing row omitted from the request is deleted; if marks already exist against it the delete is refused whole: 409 EXAM_COMPONENT_HAS_RECORDED_MARKS. Lowering a kept component's maxMarks below a mark already recorded against it is refused: 422 EXAM_COMPONENT_CEILING_BELOW_RECORDED_MARK.

ExamComponentDto (response): id, kind, label, maxMarks (number), passMarks (number), sortOrder, version (number).

6.10 PutExamInvigilatorsDto / ExamInvigilatorDto

Request: { invigilators: [{ staffId: uuid, isChief?: boolean }] }, @ArrayUnique on staffId. Every staffId must resolve to a live (deletedAt IS NULL) staff row, else 404 EXAM_INVIGILATOR_NOT_FOUND, naming none individually but refusing the whole request. Full replacement inside a transaction; onConflictDoUpdate on (routineEntryId, staffId) so re-listing the same staff member only flips isChief.

Response ExamInvigilatorDto: staffId, staffName, employmentStatus (reported as-is even for a soft-deleted row, so a screen shows the person has left rather than presenting them as current staff), isChief.

6.11 ExamEntryAvailabilityDto

{ routineEntryPublicId, freeStaff: [{staffId, name}], freeRooms: [{id, name}] } — every active room and every active, non-deleted staff member NOT already booked (published/completed entries only) in the same date/time window as this entry, excluding this entry itself.

6.12 ExamConflictsReportDto / ExamPublishPreviewDto

ExamConflictReportRowDto: { kind: "room"|"class"|"invigilator", routineEntryPublicId, conflictsWith: ExamConflictsWithDto }. ExamConflictsWithDto: { routineEntryPublicId, examPublicId, examName, className, subjectName, examDate, startMinute, endMinute } — enough to find and fix the other paper, never a full entry dump.

ExamPublishPreviewDto: { examPublicId, classCount, pupilCount, subjectNames: string[], examDates: string[], canPublish: boolean, warnings: ExamPublishPreviewWarningDto[], conflicts: ExamConflictReportRowDto[] }. Warning kind is one of class_no_entries | entry_no_room | entry_no_invigilator | entry_no_components | not_school_day | grading_scale_no_floor_band — only entry_no_components, grading_scale_no_floor_band, and any non-empty conflicts set canPublish: false; the rest are cosmetic. publish itself is still the actual gate — this route mutates nothing.

6.13 Marks sheet DTOs

A teacher reads and writes their own marks through the audience surface, never through ExamMarks_*. The admin ExamMarksController/ExamMarksWorkflowController (GET/PUT /exam-routine-entries/:publicId/marks, POST .../marks/submit) is the unscoped, whole-school code — any holder of ExamMarks_UPDATE can write ANY paper's marks. TeacherExamMarksPortalController on /api/mobile/teacher/exams/:examPublicId/entries/:entryPublicId/marks* calls the exact same underlying ExamMarksSheetService/ExamMarksWorkflowService methods, but only after its OWN scoping predicate passes (class_subjects.teacher_id = me OR exam_marks_submissions.submitted_by_staff_id = me). Do not "fix" a teacher's 403 by granting them ExamMarks_UPDATE — that permanently hands every teacher every child's marks across the whole school, because grants are never revoked; the fix for a legitimately blocked teacher is in the scoping predicate, not the admin permission catalogue.

SaveExamMarksDto (PUT .../marks): { students: [{ studentId: uuid, components: [{ componentId: int, attendance: enum, obtainedMarks?: number|null, remarks?: string|null }] }] }. Each cell is a FULL replacement of that (student, component) pair — an omitted obtainedMarks/remarks on a resend CLEARS it, this is not a partial patch. obtainedMarks must be null when attendance !== "present" (422 EXAM_MARK_ABSENT_CANNOT_SCORE) and must not exceed the component's maxMarks (422 EXAM_MARK_EXCEEDS_CEILING). studentId must be on the paper's LIVE roll (§3), else 404 STUDENT_NOT_FOUND; componentId must belong to this entry, else 404 EXAM_COMPONENT_NOT_FOUND. The whole save is refused with 409 EXAM_MARKS_NOT_YET_OPEN while the gate is closed, and 409 EXAM_MARKS_NOT_EDITABLE once the submission has moved past draft/returned.

ExamMarksSheetDto (response, GET/PUT): routineEntryPublicId, components: ExamMarkComponentHeaderDto[] ({componentId, label, maxMarks, passMarks, sortOrder}), students: ExamMarkStudentRowDto[] ({studentId, studentName, admissionNumber, components: ExamMarkCellDto[]}), submission: ExamMarksSubmissionDto, opensAt (Date), isOpen (boolean), isEditable (boolean — isOpen AND submission is draft/returned; the one field that actually gates the client's PUT button).

ExamMarkCellDto: {componentId, markPublicId: uuid|null, attendance, obtainedMarks: number|null, remarks: string|null}. markPublicId is null and obtainedMarks is null until the first save creates the row — rows are created lazily, one per (component, student) actually saved, never pre-created for the whole roll. A pupil with no row at all reads as attendance: "present", obtainedMarks: null — the same shape a present-but-unscored pupil has, which is exactly why submit's completeness check treats "no row" and "a present row with a null mark" identically as incomplete.

null in obtainedMarks means NOT SCORED, never zero. A pupil marked absent never carries a mark at all (the schema forbids it — exam_marks_absent_has_no_marks, 422 EXAM_MARK_ABSENT_CANNOT_SCORE). This is true everywhere a mark or result field appears on the wire in this module: ExamMarkDetailDto.obtainedMarks, every ExamResult*Dto.totalObtained/percentage/gpa, ExamSubjectResultDto.obtained/percentage. A 0 is a genuine, scored zero; null is "there is nothing to report here."

ExamMarksSubmissionDto: {publicId: string|null, state, submittedAt, submittedByStaffId, reviewedAt, returnReason, finalizedAt, version: string}. A submission that has never been saved is represented VIRTUALLY — publicId: null, state: "draft", version: "0" — rather than 404ing, because "nobody has typed anything yet" is not an error condition.

6.14 Marks workflow request DTOs

ExamMarksVersionDto: { version: string } — used by submit/approve/finalize. ReturnExamMarksDto extends it with a required reason (1-500 chars) — unlike the column's own nullability, a return with no explanation leaves the teacher unable to act on it.

6.15 Mark correction DTOs

CorrectExamMarkDto (POST /exam-marks/:publicId/correct — :publicId here is the MARK's own publicId): { attendance: enum, obtainedMarks?: number|null, reason: string (1-500, required) }. Legal only once the paper's submission has reached finalized (409 EXAM_MARKS_TRANSITION_INVALID otherwise) — a correction to an unfinalized paper does not exist as a concept; the sheet is still directly editable. reason is required even though the column is nullable, "because an unattributed rewrite of a finalised academic record is exactly what this route exists to prevent" (source comment). Every correction is append-only: a new exam_mark_corrections row carrying both the previous and new values, never an update to a prior correction. Correcting a finalized mark marks every exam_results row for that EXAM isStale: true — the recompute is not automatic; see §6.16.

ExamMarkCorrectionDto (one row of GET .../corrections): {id, previousAttendance, previousObtainedMarks, newAttendance, newObtainedMarks, reason, correctedByUserPublicId, correctedAt}.

ExamMarkDetailDto (the mark, re-read after a correction — never the request echoed): {publicId, attendance, obtainedMarks: number|null, maxMarks, version: string}.

6.16 Result DTOs

ListExamResultsQueryDto extends QueryDto: adds only status (enum, §7). The source docblock comment on this class says ?status=&classId=, but classId is NOT a declared field — sending it 400s the whole request under the global forbidNonWhitelisted pipe. Treat the comment as stale relative to the code; status is the only filter this endpoint accepts beyond the shared pagination/sort/search fields.

ExamResultSummaryDto (GET .../results list row): id (the result's publicId), studentId, studentName, admissionNumber, className, totalObtained: number|null, totalMax, percentage: number|null, gpa: number|null, overallGradeLabel: string|null, passedSubjects, failedSubjects, status (enum, §7), isStale (boolean — true the moment any underlying mark is corrected, until the next compute), computedAt, version (string).

ExamResultDetailDto extends it with remarks: string|null and subjects: ExamSubjectResultDto[] — each carrying routineEntryId (despite the name, this is the routine entry's publicId), subjectName, obtained, max, percentage, gradeLabel, gradePoint, isPassing, attendance, countsTowardTotal, remarks, and componentBreakdown: ExamResultComponentBreakdownDto[] — a per-component snapshot (componentId, label, kind, max, obtained, attendance) frozen at compute time, independent of any later edit to the live component row.

WithholdOrReleaseResultDto: { version: string }. withhold simply flips status to withheld; release RE-DERIVES the overall status/percentage/GPA/pass-fail counts from the pupil's own unchanged exam_subject_results rows through the identical computeOverall function compute uses — there is no stored "status before withhold" column, so recomputation from the unchanged per-subject snapshot is the only source of truth that does not invent one.

ComputeResultsResponseDto (POST .../results/compute): { mode: "computed"|"queued", studentCount, resultCount: number|null }. compute is synchronous for a roll of 500 pupils or fewer (EXAM_SYNC_COMPUTE_MAX_STUDENTS); for a larger roll it enqueues ExamJob.RESULT_COMPUTE through the outbox and returns immediately with mode: "queued", resultCount: null — the caller must poll GET .../results afterward rather than trust the response body to reflect the finished computation. Every compute run — synchronous or queued — serializes through a per-exam Postgres advisory lock, so two overlapping compute requests for the same exam never race onto the same result rows.

publish refuses with 409 EXAM_RESULTS_NOT_ALL_FINALIZED while any routine entry under the exam lacks a finalized marks submission, and with 409 EXAM_RESULTS_STALE while any computed result is stale (a correction landed after the last compute) — both must be clear before results can go out. unpublish refuses 409 EXAM_RESULTS_NOT_PUBLISHED if nothing is published. Publishing/unpublishing does not delete or recompute anything; it only flips exams.results_published_at.

6.17 ExamNotificationRuleDto / UpdateExamNotificationRuleDto

Response: {event: enum(7 values, §7), enabled, channels: NotificationChannel[], notifyStudents, notifyGuardians, notifyTeachers, notifyInvigilators, invigilatorApplicable: boolean, version: string}. invigilatorApplicable is computed, never stored — true only for schedule_changed, cancelled, invigilation_assigned (INVIGILATOR_APPLICABLE_EVENTS); an invigilator has no interest in a result publication or an exam simply being published.

Request (PUT :event): { version: string, enabled, channels: NotificationChannel[] (≤4, unique, each ∈ the channel registry), notifyStudents, notifyGuardians, notifyTeachers, notifyInvigilators } — event comes from the route, never the body. An unknown channel is 400 EXAM_NOTIFICATION_RULE_INVALID; setting notifyInvigilators: true on an event not in the applicable set is also 400 EXAM_NOTIFICATION_RULE_INVALID. There is no create/delete on this resource — one row per event is seeded by migration, and :event not matching one of the 7 known values is 404 EXAM_NOTIFICATION_RULE_NOT_FOUND.

6.18 ExamReminderRuleDto / reminder-rule replacement DTOs

Response: {id, offsetMinutes, label: string|null, enabled, channels, version: string}. UpsertExamReminderRuleDto (one row of the PUT full-list replace): id? (omit to create), version? (required when id is given), offsetMinutes (15..43200, i.e. 15 minutes to 30 days before the paper), label? (≤64 chars), enabled, channels. ReplaceExamReminderRulesDto: { rules: UpsertExamReminderRuleDto[] }.

Two rules cannot share an offset (400 EXAM_REMINDER_RULE_INVALID), and two ENABLED rules must be at least 15 minutes apart — one sweep tick (409 EXAM_REMINDER_RULES_TOO_CLOSE) — because an offset closer than the sweep interval can fall entirely between two ticks and never dispatch, silently. Updating an existing rule with no id-match is 400 EXAM_REMINDER_RULE_INVALID; a missing or stale version on an existing rule is 409 EXAM_VERSION_CONFLICT.

6.19 ExamDashboardDto / ExamDashboardQueryDto

Query: { academicSessionId?: uuid } — defaults to academic_sessions.is_current; 404 ACADEMIC_SESSION_NOT_FOUND if given and unknown, or if omitted and no session is marked current. Response: {upcoming, ongoing, completed, cancelled, publishedResults, pendingMarks, pendingVerification} — all number. upcoming/ongoing split the published status by whether startDate is in the future; pendingMarks counts routine entries under a published/completed exam with no finalized marks submission; pendingVerification narrows that to submitted (awaiting an ExamMarksVerify holder).

6.20 ExamDayDto

{ date: string (school's own YYYY-MM-DD, never UTC-derived), entries: ExamDayEntryDto[] }. Each entry: {routineEntryPublicId, examPublicId, examName, className, subjectName, startMinute, endMinute, roomName: string|null, invigilatorNames: string[], isCompleted} — every paper sitting TODAY across every published/completed exam, gated on ExamRoutines_READ (the same code the routine builder uses), so invigilator identity is fine here even though it would not be on an audience-facing shape.

6.21 Portal shared DTOs (student/guardian)

ExamPortalListDto: {items: ExamPortalListItemDto[], truncated: boolean} — each item {publicId, name, examTypeName, status, startDate, endDate, resultsPublished: boolean}. truncated is true when the pupil's own exam count exceeds PaginationUtil.UNPAGINATED_HARD_CAP (1000) — detected with one extra row over the cap, never a second count(*).

ExamPortalDetailDto: {publicId, name, description, examTypeName, status, startDate, endDate, publicCancellationNote, resultsPublishedAt, entries: ExamPortalSubjectEntryDto[], attachments: ExamPortalAttachmentDto[]}. entries is scoped to the pupil's OWN class — never every class under the exam. ExamPortalSubjectEntryDto: {routineEntryPublicId, subjectName, examDate, startMinute, endMinute, examCenter, notes, room: ExamPortalRoomDto|null, isCompleted} — audience-visible fields only: notes, never internalNote.

ExamPortalResultDto: {examPublicId, examName, totalObtained, totalMax, percentage, gpa, overallGradeLabel, passedSubjects, failedSubjects, status, remarks, computedAt, subjects: ExamPortalSubjectResultDto[]} — served only once resultsPublishedAt IS NOT NULL AND the pupil's own result status <> 'withheld'; both conditions failing answer the identical 404 EXAM_NOT_FOUND (§5).

ExamPortalHistoryDto: {items: ExamPortalHistoryItemDto[], truncated} — every published, non-withheld result the pupil has EVER had, across every academic session; not a promotion/attendance transcript.

ExamPortalDashboardDto: {upcoming, nextExam: {publicId,name,startDate}|null, remindersCount?, pendingResultsCount?, publishedResultsCount}. remindersCount is read as "upcoming exams within the next 7 days" — a display aggregate, independent of exam_reminder_rules' own configured windows.

ExamPortalAttachmentDto: {publicId, originalName, mimeType, sizeBytes} — never storageKey. ExamPortalRoomDto: {building, floor, roomNumber}.

Every mapper in this file enumerates fields explicitly and never spreads a raw database row — internalNote, cancellationReason, and returnReason never reach any portal DTO, by construction rather than by a field being nulled at the edge.

6.22 Teacher portal DTOs

TeacherExamListDto/TeacherExamListItemDto: {publicId, name, examTypeName, status, startDate, endDate}. TeacherExamDetailDto adds entries: TeacherExamEntryDto[] and attachments; each entry carries role: "subject_teacher"|"invigilator" so the client can distinguish why this paper appears. TeacherMarksQueueDto/TeacherMarksQueueItemDto: {examPublicId, examName, routineEntryPublicId, className, subjectName, examDate, submissionState: "draft"|"returned"} — scoped to the subject-teacher half of the authorization predicate only (a display convenience; the submitted_by_staff_id half is what the write routes additionally honour). TeacherInvigilationListDto/TeacherInvigilationItemDto: never embeds a co-invigilator's identity or employee code — only the caller's own isChief flag. TeacherExamDashboardDto: {myExams, upcoming, marksPending, marksSubmitted, resultsPending}.

6.23 schedule/today DTOs (modules/mobile/teacher/)

TeacherTodayScheduleDto: {serverTime, timezone, date, bsDate: {year,month,day}, dayOfWeek, calendar: {classification, eventName, isOperatingDay}, periods: TeacherTodayPeriodDto[], currentPeriodId, nextPeriodId, nextTransitionAt, summary: {total, finished, remaining}}. Each TeacherTodayPeriodDto: {id, kind: "class"|"exam_invigilation"|"exam", state: "finished"|"in_progress"|"upcoming", startMinute, endMinute, startsAt, endsAt, className, subjectName, room, classPublicId, subjectId, classSubjectId}; the last three are the public uuids of the period's class, subject and class-subject, present for every kind. Three independent sources are merged and NEVER suppress one another — a class period and an exam duty legitimately overlap because they come from different tables; kind disambiguates. currentPeriodId ties break in favour of exam_invigilation over exam over class when two periods are in progress simultaneously. Finished periods are never dropped from the response — a teacher arriving mid-morning must still see how much of the day is done. An exam_invigilation period names the class being invigilated, which the caller may neither teach nor be class teacher of; opening that class's roster through GET /api/mobile/teacher/classes/:publicId/roster then answers 404, so a client must not assume every period's classPublicId is openable.

7. Enum Reference

Two internal notify occasions are not their own configurable row. The worker-side ExamNotifyEvent type additionally carries unpublished and marks_submitted, neither of which is in the 7-value settings enum above. unpublished deliberately reuses the schedule_changed rule row (confirmed at exam-notifier.service.ts's RULE_EVENT_BY_NOTIFY_EVENT map) rather than adding an eighth configurable event. marks_submitted is dispatched through its own dedicated code path (notifyMarksSubmitted) rather than through that same class-scoped rule map — this document does not assert which settings row, if any, gates it, because no direct read of that method's rule-resolution logic was made this session; treat that one detail as [UNVERIFIED] and confirm against exam-notifier.service.ts before building an integration that depends on it.

8. Endpoint Reference

Every route from §4 is covered here in full detail for the capability groups a reader is most likely to integrate against, and for every route (all 80) in the route-by-route matrix at §13.1. Where an admin route and its audience-portal mirror share the same underlying service (marks read/write/submit), the audience differences are called out inline rather than repeating the whole shape.

8.1 POST /api/exams

Purpose

Creates a new exam, always as a draft, for the admin panel's exam-creation form. Used before any routine, class scope, or grading is attached — every other write in this module operates on an exam this route already created.

Source Evidence

Auth and Permissions

• Auth: JWT required.
• Guard chain: JwtAuthGuard, RoleGuard.
• Permission: Exams_CREATE.
• Guest support: none.
• Rate limit: none.
• Idempotency: none — there is no clientRequestId on this DTO; a replayed request creates a second draft exam.

Request

{
  "academicSessionId": "01973a...",
  "examTypeId": "01973b...",
  "name": "First Terminal Examination 2083",
  "startDate": "2026-09-20",
  "endDate": "2026-09-30"
}

Full request:

{
  "academicSessionId": "01973a...",
  "examTypeId": "01973b...",
  "gradingScaleId": "01973c...",
  "name": "First Terminal Examination 2083",
  "description": "Covers units 1 through 6.",
  "internalNote": "Room allocation pending facilities sign-off.",
  "startDate": "2026-09-20",
  "endDate": "2026-09-30"
}

Response

201 with "Exam created.".

{
  "success": true,
  "message": "Exam created.",
  "data": {
    "publicId": "01973h...",
    "status": "draft",
    "displayStatus": "draft",
    "classes": [],
    "version": "0"
  }
}

(Full shape: ExamDetailDto, §6.2.)

Side Effects

• Database writes: exams (insert).
• Cache: none.
• BullMQ jobs: none.
• Realtime events: none.
• Notifications: none (a draft is invisible to every audience).
• Audit logs: ActivityAuditInterceptor records the mutating request under module Exams, action CREATE.
• External API calls: none.

Error Cases

Edge Cases

• Empty description/internalNote string is stored as null (trimmed-then-falsy collapse), not an empty string.
• startDate === endDate is legal — a one-day exam.
• Omitting gradingScaleId produces a marks-only exam: results still compute (obtained/max/percentage) but never carry a gradeLabel/gradePoint.
• Two concurrent creates with identical fields both succeed as two separate drafts — there is no de-duplication.

Example Requests

POST /api/exams HTTP/1.1
Authorization: Bearer TOKEN
Content-Type: application/json

curl -X POST "$API_URL/api/exams" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"academicSessionId":"...","examTypeId":"...","name":"First Terminal","startDate":"2026-09-20","endDate":"2026-09-30"}'

8.2 POST /api/exams/:publicId/publish

Purpose

Publishes a draft exam, making it visible to every scoped pupil, guardian and teacher, and arming its routine entries' room/class/invigilator exclusion constraints all at once. The primary irreversible-feeling step in the exam lifecycle — call it only once routine building, components, invigilators and (if graded) the grading scale are all in place; GET .../publish-preview is the read-only rehearsal for this exact call.

Source Evidence

Auth and Permissions

• Auth: JWT required.
• Guard chain: JwtAuthGuard, RoleGuard.
• Permission: ExamPublish_UPDATE — deliberately separate from Exams_UPDATE, so an ordinary editor cannot make an exam live.
• Guest support: none.
• Rate limit: none.
• Idempotency: none by request shape; a repeat call with the same (now stale) version is a version conflict, not a silent no-op.

Request

{ "version": "0" }

Response

200 with "Exam published." and the full ExamDetailDto.

Side Effects

• Database writes: exams (status→published, publishedAt, publishedByUserId), cascades exam_status onto every exam_routine_entries/exam_invigilators row for this exam in the same statement.
• Cache: none.
• BullMQ jobs: ExamJob.PUBLISH_NOTIFY enqueued via the outbox in the same transaction, deduped on exam-published-<publicId>-v<version>.
• Realtime events: none.
• Notifications: exam.published — see §11.
• Audit logs: ActivityAuditInterceptor, module ExamPublish, action UPDATE.
• External API calls: none.

Error Cases

Edge Cases

• A conflict entirely INSIDE the batch being published (two of this exam's own papers colliding with each other, neither yet published) is caught by the second pass of the two-pass detector — see §3, §11.
• Publishing an exam with gradingScaleId: null never checks GRADING_SCALE_HAS_NO_FLOOR_BAND — that check only runs when a scale is attached.
• A pupil enrolled into a scoped class AFTER publish still appears on every subsequent marks/results read — the roll is read live, never snapshotted at publish.

Example Requests

curl -X POST "$API_URL/api/exams/$EXAM_ID/publish" \
  -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
  -d '{"version":"0"}'

8.3 PUT /api/exam-routine-entries/:publicId/marks (admin) and the teacher-portal mirror

Purpose

Saves a paper's marks sheet — one row per pupil on the live roll, one cell per assessment component. The admin route (ExamMarks_UPDATE) is unscoped across the whole school; PUT /api/mobile/teacher/exams/:examPublicId/entries/:entryPublicId/marks calls the identical underlying service after its own scoping predicate confirms the caller is the paper's current subject teacher or already submitted marks for it (§6.13).

Source Evidence

Auth and Permissions

• Auth: JWT required.
• Guard chain: JwtAuthGuard, RoleGuard.
• Permission: admin route ExamMarks_UPDATE; teacher route none (scoping predicate is the control).
• Guest support: none.
• Rate limit: none.
• Idempotency: a resend is a full replacement per cell — resending the same payload is a safe no-op; resending WITHOUT a previously-saved cell clears it.

Request

{
  "students": [
    {
      "studentId": "01973s...",
      "components": [
        { "componentId": 12, "attendance": "present", "obtainedMarks": 62 }
      ]
    }
  ]
}

Response

200 with "Marks saved." and the full ExamMarksSheetDto (§6.13), re-read after the write.

Side Effects

• Database writes: exam_marks upsert on (componentId, studentId).
• Cache: none.
• BullMQ jobs: none directly (submission, not save, is what notifies).
• Notifications: none.
• Audit logs: ActivityAuditInterceptor, module ExamMarks, action UPDATE (admin route) or the teacher-portal's own handler key.

Error Cases

Edge Cases

• A cell for a pupil who has since left the class (no longer on the live roll) 404s the WHOLE save, not just that cell — the request is all-or-nothing.
• Sending obtainedMarks: null on a present row clears a previously-saved score back to "not scored", which is distinct from 0.
• The teacher route's entryPublicId not belonging to the examPublicId in the URL is refused identically to "not my paper" — 404 EXAM_ROUTINE_ENTRY_NOT_FOUND, never a more specific mismatch error.

Example Requests

curl -X PUT "$API_URL/api/mobile/teacher/exams/$EXAM_ID/entries/$ENTRY_ID/marks" \
  -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
  -d '{"students":[{"studentId":"...","components":[{"componentId":12,"attendance":"present","obtainedMarks":62}]}]}'

8.4 POST /api/exam-routine-entries/:publicId/marks/submit (and the teacher-portal mirror)

Purpose

Moves a paper's marks from draft/returned into submitted, the point at which an ExamMarksVerify holder can act on them. Refuses if any present pupil is still missing a mark, so a verifier never receives a visibly incomplete sheet.

Source Evidence

Auth and Permissions

• Permission: admin ExamMarks_UPDATE; teacher route none (scoping predicate).
• Idempotency: none — a repeat submit against an already-submitted state is 409 EXAM_MARKS_TRANSITION_INVALID.

Request

{ "version": "0" }

The teacher route's controller supplies the caller's own staff.id as submittedByStaffId automatically; the admin route never supplies one (it stays null — "the unscoped administrator route" per source comment).

Response

200 with "Marks submitted." and ExamMarksSubmissionDto.

Side Effects

• Database writes: exam_marks_submissions (created if absent, via onConflictDoNothing racing safely against a concurrent first save; then transitioned to submitted).
• BullMQ jobs: ExamJob.MARKS_SUBMITTED_NOTIFY via the outbox, deduped on exam-marks-submitted-<publicId>-v<version>.
• Notifications: exam.marks_submitted.
• Audit logs: yes.

Error Cases

Edge Cases

• getOrCreateSubmission loses a race to a concurrent first save gracefully — it re-reads the winner's row rather than erroring.
• The completeness check treats a pupil with NO exam_marks row identically to one with a present/null row — both count as incomplete.

8.5 GET /api/exams/:publicId/results and POST /api/exams/:publicId/results/compute

Purpose

GET lists every computed result for the exam, filterable by status; compute (re-)runs the scoring for every pupil on the exam's live roll. An administrator calls compute after every paper's marks are finalized, then GET to review before publish.

Source Evidence

Auth and Permissions

• Permission: ExamResults_READ (list/detail), ExamResults_UPDATE (compute).

Request (list)

Response (list)

{
  "success": true,
  "message": "Exam results fetched.",
  "data": [
    {
      "id": "01973r...",
      "studentId": "01973s...",
      "studentName": "Aarav Sharma",
      "admissionNumber": "SID-2026-0005",
      "className": "Grade 5 - A",
      "totalObtained": 412,
      "totalMax": 500,
      "percentage": 82.4,
      "gpa": 3.6,
      "overallGradeLabel": "A",
      "passedSubjects": 4,
      "failedSubjects": 1,
      "status": "passed",
      "isStale": false,
      "computedAt": "2026-10-01T09:00:00.000Z",
      "version": "1"
    }
  ],
  "meta": { "count": 42, "page": 1, "size": 20 }
}

Response (compute)

{ "success": true, "message": "Result computation finished.", "data": { "mode": "computed", "studentCount": 42, "resultCount": 42 } }

or, over the synchronous roll cap:

{ "success": true, "message": "Result computation finished.", "data": { "mode": "queued", "studentCount": 812, "resultCount": null } }

Side Effects

• Database writes (compute): exam_results upsert on (examId, studentId), exam_subject_results delete-then-reinsert per pupil, inside a per-exam Postgres advisory-lock transaction.
• BullMQ jobs: ExamJob.RESULT_COMPUTE when the roll exceeds 500 pupils, deduped per exam so a repeated request while the first has not dispatched is a no-op.
• Notifications: none directly from compute (publish is what notifies).

Error Cases

Neither list nor compute has any other named error path in the code read this session — an empty roll simply computes zero rows (resultCount: 0), not an error. compute on an unlocked academic year runs normally. When the queued (>500-pupil) path picks up a job for an exam whose year has since been locked, ExamResultComputeAdapter does not throw: it leaves the results as they are and logs a warning, so a caller polling GET .../results after a mode:"queued" response for a year that was locked mid-flight sees no result rows rather than an error.

Every write endpoint under this module — create, publish, routine, marks, results, attachments — refuses with 409 ACADEMIC_SESSION_LOCKED once the exam's academic year is locked; see academic-sessions/backend.mdx for the trigger mechanism and exams/backend.mdx §11 for the exam-specific table list.

Edge Cases

• Recomputing an exam that already has results overwrites every value via onConflictDoUpdate, but deliberately never overwrites classId — that column records which class the pupil SAT the exam in, at first compute, permanently.
• A withheld result IS still returned by GET .../results to an admin caller (only the audience surface hides it).
• isStale: true persists until the next compute call — nothing clears it automatically, and publish refuses outright while any result is stale.

8.6 GET /api/mobile/student/exams/:examPublicId/result (and the guardian mirror)

Purpose

A pupil (or their guardian) reading their own published result for one exam — the single most consumed audience read in this module, since it is the entire reason a school publishes results at all.

Source Evidence

Auth and Permissions

• Auth: JWT required; no @Permissions().
• Guard chain: JwtAuthGuard, RoleGuard; audience asserted via assertPortalAudience/GuardianPortalService.resolveOwnChildId.
• Rate limit: none.

Request

Response

200, ExamPortalResultDto (§6.21) — remarks here is the AUDIENCE-visible one, distinct from any internal note; every field that could carry a per-subject breakdown returns the pupil's own subjects array only.

Error Cases

No other error path exists on this route — a guardian's child-binding failure short-circuits before this service is ever called (GuardianPortalService.resolveOwnChildId's own 404).

Edge Cases

• A pupil whose result was computed but never published (results-publish not yet run) gets the identical 404 as one whose exam does not exist.
• A pupil's own result being withheld is invisible to them but still visible to an admin via §8.5 — an intentional divergence, not a bug.
• A guardian viewing a linked child who has since been unlinked gets 404 from the child-resolution step, before this route's own logic ever runs.

9. Flow Diagrams

9.1 Route Ownership

9.2 Request Sequence — publish

9.3 Request Sequence — marks submission state machine

9.4 Error Branch — audience exam read

9.5 Activity Diagram — result publish

9.6 Data Contract Map — routine entry create

9.7 Cache Flow

No route in this module reads or writes a Redis cache key. Every read hits PostgreSQL directly.

9.8 Async/Job Flow — result compute over the sync cap

10. Pagination, Sorting, Filtering, and Search

Every list/query DTO in this module runs through the global ValidationPipe's whitelist+forbidNonWhitelisted: a query parameter the DTO does not declare 400s the WHOLE request rather than being silently ignored. GET /exams accepts only search, academicSessionId, examTypeId, status beyond the shared pagination fields — nothing else. There is no broad-search relevance scoring anywhere in this module; search is a plain case-insensitive ILIKE on the name column, and an empty search string is trimmed to undefined by the shared QueryDto transform (no filter applied).

11. Caching, Jobs, and External Integrations

Two Postgres advisory locks are load-bearing and worth knowing about even though they are not "jobs": every results/compute run (sync or async) takes a per-exam pg_advisory_xact_lock, and the swap route (POST /exam-routine-entries/swap) uses SET CONSTRAINTS ... DEFERRED inside its own transaction rather than a lock, to let two UPDATEs land with a transient overlap before the exclusion constraints are checked for real.

13. Mandatory Deep API Documentation Pack

13.1 Route-by-Route Completeness Matrix

13.2 Request/Response Exhaustiveness

Every route family above has a minimal-valid, full-valid (where the DTO has optional fields), success-response, and representative-error example in §8 for the routes given full treatment, and the exact DTO shape in §6 for every other route — the same fields, defaults and validators apply regardless of which section documents them. Every list endpoint's empty-result shape is {success: true, message: "...", data: []} (or {items: [], truncated: false} for the unpaginated portal lists) — none of them return a distinct "empty" envelope.

13.3 API Diagram Pack

Covered in §9: route ownership (9.1), two request sequences spanning the module's two most consequential write paths (9.2 lifecycle publish, 9.3 marks submission), an error decision tree for the audience 404-ambiguity contract (9.4), an activity diagram for the results-publish gate (9.5), a data contract map for routine-entry creation (9.6), the (empty) cache flow (9.7), and the async job flow for result computation (9.8).

13.4 Consumer Integration Notes

13.5 API Tradeoffs and Rationale

13.6 API Change Impact

14. Zero-Omission API Checklist

• Every controller route is documented (80 of 80 — §4, §13.1).
• Every parent route prefix and runtime URL is documented, including the two controllers declared with a parameterized controller-level path (exams/:publicId, exams/:publicId/results).
• Every DTO field, nested field, enum, default, transform, and validator is documented (§6, §7).
• Every response field, nullable field, generated field, and omitted raw-entity field is documented, including the module-wide "raw row never spread into a portal DTO" rule (§6.21).
• Every auth, guard, permission, role, public decorator, and guest identity branch is documented (§5) — there is no public/guest branch anywhere in this module.
• Every success, validation, auth, permission, not-found, conflict, rate-limit, and server-error branch is documented; there is no rate-limit branch anywhere in this module (§5, §8, §13.1).
• Every database read/write, cache hit/miss/write/invalidation, queue job, and audit log is documented; there is no cache layer and no realtime event in this module (§9, §11).
• Representative routes carry minimal, full, success, and error examples (§8); every other route's exact shape is in §6 and §13.1.
• Route, sequence, activity, and error diagrams are present (§9).
• Tradeoffs and compatibility risks are documented, including two flagged defect candidates (§13.5, §13.6).
• The API doc links to backend and features/flows (See Also).

15. Integration Checklist

• Every route from controllers is documented.
• Every DTO field is documented.
• Every enum value is documented.
• Every response envelope is documented.
• Every error code is documented — including the two registered but never-thrown codes (EXAM_ROUTINE_ENTRY_IN_USE, EXAM_BS_DATE_OUT_OF_RANGE), called out explicitly rather than silently omitted.
• Every auth guard and permission is documented.
• Every queue job is documented; this module has no cache key and no realtime event.
• Every diagram matches the current code.
• The API doc links to backend and features/flows.

See Also

• Backend doc: /docs/developer/exams/backend
• Features and flows doc: /docs/developer/exams/feature