Leave Backend Documentation

1. Documentation Evidence

2. Backend Scope and Boundaries

Owns

• The leave-type catalogue: code, label, description, which subject kinds it applies to, active/retired state, sort order.
• The leave-request lifecycle for both pupils and staff: filing, correcting the type/reason, soft-deleting, restoring, and the full decision chain (guardian consent where applicable, then the school step, with a reversal path out of approved).
• The append-only decision log — every consent and refusal, in what capacity the decider acted.
• The one small runtime table tracking whether an approved request's attendance write has been applied and/or reversed.
• Rewriting the attendance register (student_attendance_records / staff_attendance_records) when a leave is approved, and restoring it when that approval is reversed — the one BullMQ worker on QueueName.LEAVE.
• Four admin/office surfaces (/api/leave-types, /api/student-leaves, /api/staff-leaves, plus the decision and reapply-attendance sub-routes) and four consumer surfaces under /api/mobile (guardian, student, teacher, staff).
• Entitlement carry-over between academic sessions (carry-over). A carry-over grant is written once per subject/type/target-session (leaveCarryOver, deduplicated by a unique target key), its expiresOn anchored to the TARGET session's own start date computed in SQL — never the run date, so the documented delete-and-re-run correction path always produces the same expiry. Writing a carry-over grant is treated as an entitlement increase for the target session: CarryOverRolloverService re-splits every already-approved request in that session under the same per-subject lock an administrator's own override re-split would take (LeaveBalanceService.reallocateAll), so a request approved before the carry-over landed is never left computed against a smaller entitlement than one approved after it — the split is monotone regardless of order.

Does Not Own

• Class, grade, section, enrolment and staff/student identity — packages/db/src/schema/school/{classes,people}.ts. This module references them by id and by deleted_at, never writes to them.
• The academic calendar and academic sessions — consumed read-only through CalendarDayService (owned by the attendance module's shared layer), never generated, edited or seeded here.
• The attendance register's OWN write paths for an ordinary (non-leave) marking or correction — apps/api/src/modules/attendance/. This module writes into the SAME tables, through the same excused status vocabulary, but owns none of the register's session-lifecycle logic (open/complete/reopen/reset).
• The transactional outbox mechanism itself — apps/api/src/modules/outbox/. This module is a producer only: it calls OutboxService.enqueue() inside its own transactions and never constructs a dispatcher or a BullMQ Queue.add() directly.
• Authentication and permission evaluation — JwtAuthGuard, RoleGuard, RoleModule. The admin and type surfaces declare @Permissions() codes; the portal surfaces declare none and assert their audience instead (§11).
• Notification delivery. The 'leave' notification category exists in the schema (both the TypeScript catalogue and two database CHECK constraints) but no code in this module calls NotificationService — see §16.6.
• Payroll's own use of a staff leave request. LeaveAttributionService.unpaidDatesInRange (apps/api/src/modules/leave/shared/leave-attribution.service.ts) is the one read the salary module makes of leave_requests, restricted to approved, non-soft-deleted staff requests. The paid entitlement is consumed FIRST, so a request's unpaid days are always the LAST unpaid_days of its counted dates — the last-N slice is taken over the whole request before restricting to a payroll period's date range, so a request spanning two months never has its unpaid days misassigned to the wrong one. day_count_basis (staff_working_days or calendar_days) on the request decides which dates count at all; the resulting counted_dates/unpaid_dates_in_range are what a payslip deducts, so leave and payroll always agree on which days were unpaid. A pre-migration request with no stored counted dates is reconstructed on read and marked isLegacy.

Source of Truth

3. Module Composition

Ten NestJS modules compose this feature. There is no top-level LeaveModule aggregate — app.module.ts and mobile.module.ts import the leaves.

Every one of the four consumer-facing (portal) modules imports RoleModule — RoleGuard is applied at class level on each controller and resolves RoleService from the guarded controller's own module context; omitting it is an UnknownDependenciesException at boot, not a compile error, which is why test:structure boots the app rather than statically parsing it.

LeaveSharedModule and LeaveDecisionModule declare no controller, so ADMIN_MODULES never names them — Swagger's include does not recurse, and a module contributing no controller of its own would contribute nothing to the document while looking listed.

4. File and Directory Map

apps/api/src/modules/leave/
  admin/
    staff-leaves/
      dto/
        index.ts
        staff-leave.dto.ts
      staff-leaves.controller.ts
      staff-leaves.module.ts
      staff-leaves.service.ts
    student-leaves/
      dto/
        index.ts
        student-leave.dto.ts
      student-leaves.controller.ts
      student-leaves.module.ts
      student-leaves.service.ts
  decision/
    leave-decision.module.ts
    leave-decision.service.ts
  portal/
    guardian/
      dto/guardian-leave-portal.dto.ts
      guardian-leave-portal.controller.ts
      guardian-leave-portal.mapper.ts
      guardian-leave-portal.module.ts
      guardian-leave-portal.resolvers.ts
      guardian-leave-portal.service.ts
    staff/
      dto/staff-leave-portal.dto.ts
      staff-leave-portal.controller.ts
      staff-leave-portal.module.ts
      staff-leave-portal.service.ts
    student/
      dto/student-leave-portal.dto.ts
      student-leave-portal.controller.ts
      student-leave-portal.module.ts
      student-leave-portal.service.ts
    teacher/
      dto/teacher-leave-portal.dto.ts
      teacher-leave-portal.controller.ts
      teacher-leave-portal.module.ts
      teacher-leave-portal.service.ts
  shared/
    dto/
      decide-leave.dto.ts
      index.ts
      leave-request.dto.ts
    leave-request.mapper.ts
    leave-resolution.service.ts
    leave-shared.module.ts
    leave-sql-errors.util.ts
  types/
    dto/
      index.ts
      leave-type.dto.ts
    leave-types.controller.ts
    leave-types.module.ts
    leave-types.service.ts
  workers/
    leave-attendance.service.ts
    leave-queue.processor.ts
    leave-workers.module.ts
  __tests__/
    leave-admin.integration.spec.ts
    leave-decision.integration.spec.ts
    leave-portal.integration.spec.ts
    leave-request-attendance-fields.integration.spec.ts
    leave-types.integration.spec.ts

5. Data Model

5.1 Schema Source

packages/db/src/schema/school/
  leave.ts                 -- four tables, six enums, every CHECK the drizzle builder can express
packages/db/src/migrations/
  0022_leave_module.sql    -- the EXCLUDE constraint, the generated column, the triggers, the seed

5.2 Tables and Collections

leave_types

Seeded (migration, ON CONFLICT DO NOTHING): sick / "Sick leave", casual / "Casual leave", annual / "Annual leave" — all three applying to both students and staff, sort_order 10/20/30.

leave_requests

Every CHECK constraint on leave_requests, and what it prevents:

Every status CHECK above is written as an implication (status NOT IN (...) OR <rule>), never a closed disjunction over the enum — a closed disjunction would make ALTER TYPE leave_request_status ADD VALUE unwritable: the migration would succeed, tsc would be happy because the union really did gain the member, and every UPDATE to the new label would fail 23514 at runtime. This shape was probed against before the tables were written.

leave_request_runtime

Carries no version column and no bump_row_version trigger, deliberately. The row is created inside the APPROVAL transaction (LeaveDecisionService.armApply), not by the worker, and the worker stamps its own progress here unconditionally. Attaching the trigger would let the worker's write invalidate a version token an operator is holding on the decision screen at the exact moment the work they asked for finishes — the same reasoning student_attendance_session_runtime exists under. Only the admin LeaveRequestDto exposes it, and only three columns: attendance_applied_at, attendance_days_written and attendance_reverted_at reach the response as attendanceAppliedAt, attendanceDaysWritten and attendanceRevertedAt. StudentLeavesService.baseSelect() and StaffLeavesService.baseSelect() LEFT JOIN this table on its primary key (at most one row per request, so the join cannot multiply rows), and a request with no runtime row emits all three as null. The attempt count and the last error code reach no response; they are read only internally (reapplyAttendance's eligibility check, the worker's own claim queries).

leave_request_decisions

No foreign key on decided_by_user_id. A referential ON DELETE SET NULL is itself an UPDATE on the child row and fires row triggers — so it would abort any DELETE FROM users that had ever touched a leave decision, because the table below is append-only by trigger. The name snapshot is what the screen renders once the person is gone.

Append-only by trigger, not by convention. leave_request_decisions_is_append_only() raises 2F002 (modifying_sql_data_not_permitted) on any UPDATE OR DELETE, installed LAST in the migration — a guard installed beside its own CREATE TABLE would refuse the same migration's bookkeeping, even though nothing in this migration writes to the log.

Index: leave_request_decisions_request_idx on (leave_request_id, decided_at DESC, id DESC) — id DESC is not decoration; now() is constant within a transaction, so a reversal writing two rows in one transaction shares one decided_at exactly, and a cursor on the timestamp alone would be unstable across that tie.

attendance_change_log.leave_request_id (added column, not a new table)

The migration adds one nullable, FK-less column to the EXISTING attendance_change_log table (owned by the attendance module) plus a partial index WHERE leave_request_id IS NOT NULL. No FK, for the identical append-only-trigger reason as leave_request_decisions.decided_by_user_id above. This is what lets a register row's history be traced back to the leave that produced it, and what bounds the revert's read to one generation (changed_at >= leave_request_runtime.attendance_applied_at).

5.3 The Overlap Exclusion — the module's most important integrity rule

Declared only in the migration (drizzle has no EXCLUDE builder):

ALTER TABLE "leave_requests" ADD CONSTRAINT "leave_requests_no_overlap"
EXCLUDE USING gist (
  "subject_key" WITH =,
  daterange("start_date", "end_date", '[]') WITH &&
) WHERE ("status" IN ('pending_guardian','pending_school','approved')
         AND "deleted_at" IS NULL);

Three things about it bind every write path:

• It needs the btree_gist extension for the = operator on subject_key — created by 0019_timetable_module.sql and re-asserted here in case a database has run only through 0021.
• '[]' is inclusive on both ends. The default [) makes daterange(d, d) empty, and an empty range overlaps nothing — so with the default, a single-day leave (the commonest shape there is) would collide with nothing at all. Two independent reviewers read a prose description of this constraint and both concluded exactly that; the SQL, reproduced here and in the migration and the schema file, is the authority.
• It is partial on the live statuses and deleted_at IS NULL — a refused, cancelled or soft-deleted request stops reserving the range, so a re-file is never blocked by a request nobody can see the reason for.

A violation surfaces as PostgreSQL 23P01, mapped by translateLeaveRequestError/insertLeaveRequest (per surface) to LEAVE_OVERLAPPING_REQUEST_EXISTS, matched on the constraint NAME (.constraint, walked through .cause because drizzle's error wrapper drops it at the top level).

5.4 Relationship Diagram

5.5 Index Rationale

6. Services and Responsibilities

6.1 LeaveTypesService

pagination=false is explicitly ALLOWED here (bounded by PaginationUtil.UNPAGINATED_HARD_CAP), following the reference-table convention — unlike every leave-REQUEST list in this module, which refuses it.

6.2 StudentLeavesService / StaffLeavesService

Near-identical admin services over the two subject kinds; documented once, with the differences called out.

Differences, staff vs. student: staff carry no class_id/enrollment_id and are not calendar-gated (computeStaffDayCount counts every calendar day); staff create enters pending_school directly and calls no guardian-existence check; staff findAll's search is a plain ilike on reason (no name-search EXISTS subquery, since the staff list has no class filter to preserve a shared buildWhere for).

Input normalization: reason is trimmed before insert/update on every create/update path (admin and portal alike). Validation order: DTO class-validator decorators run first (route-level ValidationPipe), then range bound → subject resolution → type resolution → enrolment/session resolution → day-count computation → guardian check (student only) → insert. Transaction boundaries: create is NOT wrapped in an explicit transaction (single INSERT); update/decide open one to hold the row lock across the read-check-write. Idempotency: submissionId on create; a fresh, timestamped dedupe key on every reapplyAttendance call (reusing the original key would let onConflictDoNothing swallow the retry silently). Fail-open/closed: every resolution failure is fail-closed — a missing calendar row, an unresolvable session, or zero live guardians all refuse the create rather than proceeding with a default. Logger usage: LeaveDecisionService and LeaveAttendanceService log structured lines (module: "Leave", operation, outcome, requestId); the two admin services log nothing themselves.

6.3 LeaveResolutionService

Verified against .omc/plans/leave-module/master-plan.md §11 in-repo, per the service's own docblock — not re-derived here; the resolution rules documented above and in §5 are the observable behavior regardless of that plan's status.

6.4 LeaveDecisionService

The single place a leave request's status changes — five callers (guardian portal, teacher portal, both admin decide routes, and the reversal, which is the same admin route against approved) share one method rather than four copies of "flip the status, append the decision row, arm or emit, record the outbox intent".

Transaction boundary: runs INSIDE the caller's transaction, never opens its own — so the audience/row-scope check the caller already performed and this write can never straddle a commit boundary. Idempotency: the outbox dedupeKey is ${jobName}_${leaveRequestId} for the initial apply/revert (stable, so a retried decide within the same transaction cannot double-enqueue) and a fresh, timestamped key for a manual reapply. Response mapping: returns the raw updated row; every caller re-selects through its own DTO-shaped projection afterward, inside the same transaction, so the response reflects the committed write.

6.5 LeaveAttendanceService

Fail-open/closed: fail-closed throughout — any resolution miss for a date (no live enrolment, no open session) simply writes nothing for that date and moves on (return 0), rather than aborting the whole apply; a genuinely unexpected error aborts the transaction and lets BullMQ retry the whole job. Idempotency: both methods are idempotent — apply's exactly-once claim is a conditional upsert on attendance_applied_at IS NULL; revert's is the same on attendance_reverted_at IS NULL. Per-date writes are additionally idempotent (if (existing?.status === "excused") return 0).

6.6–6.9 Portal services (GuardianLeavePortalService, StudentLeavePortalService, TeacherLeavePortalService, StaffLeavePortalService)

Graduate read-only. Both pupil-facing writes call assertNotGraduatedReadOnly (apps/api/src/modules/people/shared/graduate-access.query.ts) — StudentLeavePortalService.create on the pupil's own resolved id, GuardianLeavePortalService.create on the resolved child's id — answering 403 STUDENT_GRADUATED_READ_ONLY once the pupil's graduate access state is grace or ended. Both check it AFTER a submission-id replay: retrying an already-accepted request that was raised while the pupil still attended returns the existing row unconditionally rather than a 403 produced by a graduation that happened in between. GuardianLeavePortalService.ownChildrenWhere additionally excludes a child whose graduate access has ENDED (NOT graduateAccessEnded(students.id, today), mirroring GuardianPortalService.ownChildrenWhere) from every read, so once access ends the pupil stops resolving as this guardian's child at all rather than surfacing as a read-only leave history.

Every portal service's row-scope predicate is hand-built in the service itself and is never routed through PeopleAccessService.scopeFor — see §11 for the incident this avoids.

7. Runtime Flows

7.1 Self-serve create (pupil or staff)

7.2 Guardian consent / teacher decision / admin decision

7.3 Cancel (pupil, guardian, staff — never admin)

Only the ORIGINAL raiser may cancel, and only while pending (staff: pending_school only, since staff never enter pending_guardian). Locks the row (FOR UPDATE), checks expectedVersion when supplied, sets status: cancelled plus cancelled_at/cancelled_by_user_id. No decision row is written — a cancellation is not a decision. Failure: 404 LEAVE_REQUEST_NOT_FOUND (wrong raiser, wrong status, or genuinely absent — all three produce the identical response), 409 LEAVE_VERSION_CONFLICT.

7.4 Worker apply

Covered in detail at Feature doc §5.8. Code path: LeaveQueueProcessor.process → LeaveAttendanceService.apply. Re-checks status = approved inside its own transaction (guards against a reversal racing a slow/redelivered job); resolves per-date attendance-required days (pupil) or every day (staff); writes each register row and change-log entry; claims the apply via a conditional upsert. Cache miss/hit: N/A, no cache in this module. Guest vs. logged-in branch: N/A, no HTTP caller.

7.5 Worker revert

Code path: LeaveQueueProcessor.process → LeaveAttendanceService.revert. Claims the revert via a conditional upsert on attendance_reverted_at IS NULL; reads attendance_change_log bounded to changed_at >= attendance_applied_at of the CURRENT generation; for each row, either deletes the register record (if previous_status IS NULL — the apply CREATED it) or restores the prior status; writes a matching change-log row for the restoration.

7.6 Reapply-attendance

Admin-only recovery route. Re-checks status = approved AND attendance_reverted_at IS NULL, then enqueues a fresh APPLY_ATTENDANCE job with a timestamped, non-reusable dedupe key — reusing the original key would let onConflictDoNothing swallow the operator's retry with no observable effect at all.

8. Caching

None. This module reads and writes PostgreSQL directly on every request; no Redis key is built or consulted anywhere in apps/api/src/modules/leave/.

9. BullMQ, Schedulers, and Async Work

LeaveQueueProcessor is the ONE @Processor(QueueName.LEAVE, { concurrency: 2 }) on this queue. LeaveAttendanceService is a plain @Injectable(), never a second @Processor — @nestjs/bullmq builds one BullMQ Worker per decorated class, and two decorated classes on one queue name would compete for every job, each capable of running the wrong handler's body against the wrong payload. handlers is a Record<LeaveJob, ...>, so an unrouted job name is a compile error rather than a job that completes silently having done nothing — the process() method throws (never returns) for a name outside the map, because a return marks the job COMPLETED and it disappears from the failed-job sweep.

Both jobs are enqueued exclusively through OutboxService.enqueue(), inside the SAME transaction as the status change — never a direct queue.add(). A direct call would let the decision commit, the enqueue throw, the request answer 200, and nothing ever get scheduled.

LeaveWorkersModule is composed by the application root ONLY outside the fast runtime profile (isFastRuntimeProfile()). Importing a module that declares a @Processor STARTS a worker — a worker started during a migration or a one-shot script would connect to Redis and begin claiming jobs mid-script.

10. Realtime and Events

None. No Socket.IO/SSE event is emitted anywhere in this module.

11. Security, Auth, and Abuse Controls

Guards. JwtAuthGuard (global) plus RoleGuard on every controller in this module. LeaveTypesController, StudentLeavesController and StaffLeavesController declare @Permissions() on every handler; the four portal controllers declare NONE.

Permissions. Six PERMISSION_MODULES entries: LeaveTypes, StudentLeaves, StudentLeaveDecisions, StaffLeaves, StaffLeaveDecisions, LeaveView. *Decisions is a SEPARATE module from its CRUD counterpart specifically because PERMISSION_ACTIONS is closed at CREATE/READ/UPDATE/DELETE/RESTORE with no APPROVE — folding the decision into StudentLeaves_UPDATE would hand anyone who can fix a typo in a reason the power to rewrite a child's attendance register. LeaveView gates the panel SCREEN and zero API routes.

Who holds what, by default. rolePermissionsMap in seed-auth.ts seeds exactly five system roles: superadmin, staff, teacher, guardian, student. superadmin holds fullAccessPermissions — every Module_ACTION cross-product, including every Leave* code. The other four hold LeaveView_READ ONLY. No seeded role other than superadmin holds LeaveTypes_*, StudentLeaves_*, StaffLeaves_*, StudentLeaveDecisions_* or StaffLeaveDecisions_*. This is deliberate, not an oversight: TEACHER_PERMISSIONS = STAFF_PERMISSIONS BY REFERENCE, so any grant to staff reaches every teacher identically, and both roles carry scopeKind: "all" — granting a decision code to staff would hand every teacher in the school the power to decide any pupil's leave, unscoped. A school delegating office/admin leave duties creates a dedicated role holding exactly these codes; grantToRoles uses onConflictDoNothing and never revokes, so withholding by default is the recoverable direction.

Guest identity. N/A — every route in this module (admin and portal alike) requires a valid JWT; there is no public or guest-accessible leave route.

Admin identity. @CurrentUser()/@CurrentAdmin() resolve req.user, populated by JwtAuthGuard's strategy; both decorators return the same AuthUser shape in this codebase.

The twelve permission-less portal handlers. StudentLeavePortalController.{listMine,create,cancel}, GuardianLeavePortalController.{listMine,create,decide,cancel}, TeacherLeavePortalController.{listMine,decide}, StaffLeavePortalController.{listMine,create,cancel}. Each key is on BOTH NO_PERMISSION_ADMIN_HANDLERS in role.guard.ts and its CI mirror route-permissions.spec.ts — omitting either makes the route 403 for everyone including superadmin (guard) or fails a structure test (spec) with no other signal, because the integration specs call the services directly and never pass through the guard.

Rate limits / anti-abuse. None specific to this module beyond the platform-wide guards (JwtAuthGuard, the global ValidationPipe's whitelist/forbidNonWhitelisted).

Input normalization. reason/label/code trimmed before persistence on every write path. ValidationPipe's whitelist: true strips any field a DTO does not declare — the mechanism that makes "no field for subjectKind/status/origin" enforceable rather than merely documented; a client sending one of those gets a 400 (forbidNonWhitelisted), never a silently ignored field.

Sensitive data redaction. TeacherLeaveRequestDto omits reason entirely — an explicit field allowlist mapper, never a row spread, the same discipline StudentClassSummaryDto and every other public-facing mapper in this codebase follows.

Audit logs. Every mutating request through this module (admin CRUD, decide, reapply, and every portal create/decide/cancel) is recorded by the globally registered ActivityAuditInterceptor, keyed by the handler's @Permissions() code where one exists and by the route otherwise — including the twelve permission-less portal handlers, which fall back to their route so "not in the catalogue" still means "recorded". No leave-specific recordActivity() call exists anywhere in this module; the interceptor's coverage is the whole audit trail here.

Fail-closed behavior. Every resolution step in every create path is fail-closed (§6.2, §6.3). The worker is fail-open PER DATE (a date it cannot resolve is skipped, not aborted) but fail-closed on the request as a whole (a genuinely unexpected error aborts the transaction for that job attempt and lets BullMQ retry).

13. Error Handling

Four of the twenty-one declared LEAVE_* codes are verified, this session, to be thrown by no code path in apps/api/src — confirmed by a codebase-wide search, not only within this module. They are reserved, not dead by mistake: each names a real condition the schema or the queue can reach, but the code that would throw it currently reports the SAME outcome through a different, already-thrown code instead (see the table). A future change narrowing any of those shared outcomes should reach for the code already declared for it rather than inventing a new one.

14. Observability

No metric (Prometheus/StatsD-shaped) is emitted anywhere in this module.

15. Testing and Validation

Every spec in this directory is an integration test — every one connects to the real test database (TEST_DATABASE_URL), per this repo's testing rule (no mocked database, Redis, queue, or first-party package). Run with pnpm --filter @skoolsewa/api test (or scoped to this module's test files).

16. Mandatory Backend Deep-Dive Pack

16.1 Submodule Coverage Matrix

On the intentionally local, not shared, error-text walker. leave-sql-errors.util.ts (admin surfaces) and guardian-leave-portal.mapper.ts's leaveInsertErrorText (portal surfaces, also used verbatim by staff-leave-portal.service.ts's own private errorText) implement the identical five-line .cause-walking loop three times across this module. None is promoted to a shared utility — each call site's OWN error-code mapping differs (the admin util also handles range/date-ordering CHECKs the portal insert never needs to translate, since the portal DTOs validate those client-side first), so the walker itself is genuinely trivial while what each caller DOES with the matched text is not.

16.2 UML and Architecture Diagram Pack

16.3 Code Flow Narrative — LeaveDecisionService.decide

16.4 Data Layer Deep Dive

Covered exhaustively in §5. Summary of what is NOT in that section: Money units — N/A, no monetary field in this module. Timezone/date interpretation — every date column (start_date, end_date, academic_calendar_days.gregorian_date) is a plain SQL date, timezone-naive by construction; every timestamp column is timestamptz. JSON shapes — none; no jsonb column exists in leave.ts. Migration history — one migration, 0022_leave_module.sql, hand-extended after drizzle-kit generate for everything the generator cannot express (EXCLUDE, generated column, triggers, seed, the two notification-category CHECK rewrites). Seed data dependency — the three seeded leave types are the only rows any environment can rely on existing without an administrator creating them.

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 (§4, §16.1).
• Every controller, service, provider, processor, mapper, DTO, enum, and schema element is documented (§3, §5, §6, §16.1).
• Every method with business behavior has a code-flow narrative (§6, §16.3 for the deepest one).
• Every table/cache object/job payload has field-level detail (§5, §9).
• Every index, constraint, relation, and delete behavior has rationale (§5.5, §5.2's CHECK table).
• Every lifecycle/status transition has a state diagram and transition table (Feature doc §7).
• Every read/write/action/job flow has sequence and activity diagrams (§7, §16.2).
• Every business invariant is cataloged (§16.5).
• Every cache key (none), invalidation path (none), queue job, and external call is documented (§8, §9, §10).
• Every architectural tradeoff is documented with alternatives and revisit triggers (§16.6).
• Every operational failure mode has a runbook entry (§16.7, §16.8).

18. Backend Completion Checklist

• Module boundaries are documented (§2).
• Every controller, service, DTO, schema file, job, cache key (none), and event (none) is covered.
• Every database table has a field table and relationship diagram (§5).
• Every runtime flow has a diagram and branch notes (§7).
• API and features/flows docs are linked (below).
• No claim is made without a source file or documented source reference — every discrepancy between the code and the brief this document was written from (four unused error codes, two unpopulated runtime columns, an unused notification category) is stated explicitly rather than silently corrected or omitted.

See Also

• API doc: /docs/developer/leave/api
• Features and flows doc: /docs/developer/leave/feature
• Attendance (dependency — not documented here): /docs/developer/attendance
• Academic calendar (dependency — not documented here): /docs/developer/academic-calendar