Attendance Backend Documentation

1. Documentation Evidence

2. Backend Scope and Boundaries

Owns

• The daily student register: opening a class's register for a date, bulk marking and unmarking a set of pupils, correcting one pupil's record, and the three session-level transitions — complete, reopen, reset.
• The school-wide attendance overview — one row per active class for a date, with every tally computed from grouped SQL rather than a per-class round trip.
• A pupil's attendance change history and a staff member's attendance change history, both keyset-paginated over the same append-only log.
• The staff and teacher register — one table for both, marked, corrected, and read back through history, with no calendar gate.
• Which delivery channels the two attendance notification kinds are allowed to use, as an administrator-only, subtractive-only setting.
• Three read-only consumer surfaces mounted under the mobile prefix: a class teacher's own classes and their register (which also lets the teacher mark and complete, through the same transaction the admin surface uses), a pupil's own attendance, and a guardian's reading of one child's attendance.
• Two BullMQ sweeps ticking every minute: a first-period reminder to the class teacher, and a guardian absence alert once first period has ended.

Does Not Own

• Class, grade, section and room definitions — packages/db/src/schema/school/classes.ts. This module references classes, grades and sections by id and never writes to them.
• Staff and student identity, including soft delete — packages/db/src/schema/school/people.ts. Every read here treats deleted_at as authoritative but never sets it.
• The academic calendar and academic sessions — CalendarDayService (apps/api/src/modules/attendance/shared/calendar-day.service.ts) is this module's own read-only client of academic_calendar_days and academic_sessions, both owned by the academic-calendar module. Attendance consumes "is this a school day, and which session contains this date" through that service; it does not generate, edit or seed a calendar.
• Class timetables and timeslots — packages/db/src/schema/school/timetable.ts, owned by the Timetable module. The reminder sweep reads class_timetables.status and class_timeslots to find each class's first published period; it never writes either.
• Notification delivery, rendering, preference resolution and the transactional outbox — apps/api/src/modules/notification/. Both workers call NotificationService.send() inside their own transaction and never construct an outbox row or a rendered message themselves.
• Authentication and permission evaluation — JwtAuthGuard, RoleGuard, RoleModule. This module declares @Permissions() codes on its admin and staff surfaces and imports RoleModule so the guard can resolve RoleService, but implements no guard logic. The portal surfaces declare no permission at all and are covered in §11.

Source of Truth

3. Module Composition

packages/db and packages/jobs are excluded from the table above: they contribute the schema and the queue contract respectively but declare no NestJS module.

AttendanceSharedModule declares no controller, so ADMIN_MODULES and MOBILE_CHILDREN never name it — Swagger's include does not recurse, and a module contributing no controller of its own would publish nothing while looking listed. The same is true of AttendanceWorkersModule, which is composed by the application root rather than through ADMIN_MODULES.

4. File and Directory Map

apps/api/src/modules/attendance/
  shared/
    school-clock.service.ts
    calendar-day.service.ts
    attendance-roster.service.ts
    attendance-log.service.ts
    attendance.types.ts
    attendance-shared.module.ts
  admin/
    student-attendance.controller.ts
    student-attendance-read.service.ts
    student-attendance-write.service.ts
    student-attendance-lifecycle.service.ts
    student-attendance-history.controller.ts
    attendance-history.service.ts
    attendance-overview.controller.ts
    attendance-overview.service.ts
    attendance-admin.module.ts
    dto/
      student-attendance.dto.ts
      attendance-history.dto.ts
      attendance-overview.dto.ts
  staff/
    staff-attendance.controller.ts
    staff-attendance-history.controller.ts
    staff-attendance.service.ts
    attendance-staff.module.ts
    dto/
      staff-attendance.dto.ts
      index.ts
  settings/
    attendance-settings.controller.ts
    attendance-settings.service.ts
    attendance-settings.module.ts
    dto/
      attendance-settings.dto.ts
      index.ts
  portal/
    teacher/
      teacher-attendance-portal.controller.ts
      teacher-attendance-portal.service.ts
      teacher-attendance-portal.module.ts
      dto/teacher-attendance-portal.dto.ts
    student/
      student-attendance-portal.controller.ts
      student-attendance-portal.service.ts
      student-attendance-portal.module.ts
      dto/student-attendance-portal.dto.ts
    guardian/
      guardian-attendance-portal.controller.ts
      guardian-attendance-portal.service.ts
      guardian-attendance-portal.module.ts
      dto/guardian-attendance-portal.dto.ts
    shared/
      portal-attendance-summary.dto.ts
      portal-attendance-summary.service.ts
    calendar/                      (academic-calendar module; not documented here)
  workers/
    attendance.scheduler.ts
    attendance-queue.processor.ts
    attendance-reminder.processor.ts
    attendance-absence.processor.ts
    attendance-workers.module.ts
  __tests__/
    student-attendance.integration.spec.ts
    staff-attendance.integration.spec.ts
    attendance-portal.integration.spec.ts
    attendance-settings.integration.spec.ts
    attendance-sweeps.integration.spec.ts

packages/db/src/schema/school/attendance.ts
packages/db/src/migrations/0020_attendance_module.sql
packages/jobs/src/index.ts            (QueueName.ATTENDANCE, AttendanceJob, AttendanceSweepPayload)

5. Data Model

5.1 Schema Source

packages/db/src/schema/school/attendance.ts
  attendanceStatusEnum
  attendanceSessionStatusEnum
  attendanceSubjectKindEnum
  studentAttendanceSessions
  studentAttendanceSessionRuntime
  studentAttendanceRecords
  staffAttendanceRecords
  attendanceChangeLog
  attendanceNotificationSettings

packages/db/src/migrations/0020_attendance_module.sql

5.2 Tables and Collections

student_attendance_sessions

One class's register for one date — the operator's own intent, and nothing the system writes on its own (attendance.ts:86-89).

Constraints: student_attendance_sessions_class_session_fk — a composite FK on (class_id, academic_session_id) against classes(id, academic_session_id), ON DELETE/UPDATE restrict, targeting a UNIQUE CONSTRAINT on classes rather than a unique index (0020_attendance_module.sql:199-201); student_attendance_sessions_class_date_unique on (class_id, attendance_date); student_attendance_sessions_completed_at_matches_status, stated as an equivalence so neither incoherent row is representable (attendance.ts:141-144). Index student_attendance_sessions_date_status_idx on (attendance_date, status) — what the overview scans.

Carries bump_row_version.

student_attendance_session_runtime

Every system-written column the schedulers and the idempotency check touch, kept off the versioned session row on purpose (attendance.ts:153-160).

CHECK student_attendance_session_runtime_minutes_bounded: both minute columns, when present, lie in [0, 1440].

Carries NO version and NO bump_row_version trigger. This is the module's central design decision — see §16.6.

student_attendance_records

One pupil's status for one day.

Constraints: student_attendance_records_session_student_unique on (session_id, student_id); student_attendance_records_note_format and student_attendance_records_forced_reason_format — no leading/trailing whitespace, no control characters, bounded length (500 / 200). Indexes: student_attendance_records_student_idx on (student_id, id) — a pupil's own history as a keyset walk; student_attendance_records_pending_alert_idx, partial on (session_id) WHERE status = 'absent' AND guardian_alerted_at IS NULL — what the absence sweep scans, normally zero rows and never more than one morning's absences.

Carries bump_row_version.

staff_attendance_records

Teacher and staff attendance, in ONE table — a teacher is a staff row with a teaching designation, and there is no teacher entity to split against (attendance.ts:317-327).

Constraints: staff_attendance_records_staff_date_unique on (staff_id, attendance_date); staff_attendance_records_note_format. Index staff_attendance_records_date_idx on (attendance_date).

Carries bump_row_version.

attendance_change_log

Every attendance transition, append-only, for both students and staff (attendance.ts:384-403).

Constraints: attendance_change_log_states_a_change — previous_status IS NOT NULL OR new_status IS NOT NULL; a row asserting that nothing changed is not representable. attendance_change_log_reason_format. Index attendance_change_log_subject_idx on (subject_kind, subject_id, changed_at DESC, id DESC) — the id DESC tiebreaker is mandatory, not decoration, because now() is constant within a transaction and one bulk mark writes many rows sharing one changed_at exactly. Also attendance_change_log_date_idx on (attendance_date) and attendance_change_log_class_date_idx on (class_id, attendance_date).

Carries NO version and NO bump_row_version. Carries the append-only trigger — see §5.4 and §11.

attendance_notification_settings

Which channels each attendance notification kind is allowed to use.

Constraints: attendance_notification_settings_kind_known — kind IN ('attendance.first_period_reminder', 'attendance.student_absent'); attendance_notification_settings_channels_array — jsonb_typeof(channels) = 'array' AND jsonb_array_length(channels) <= 4.

Carries bump_row_version. Seeded with both rows, enabled = true, channels = ["push", "in_app"] — matching CATEGORY_DEFAULTS.attendance, so the seed never advertises a channel the preference resolver would suppress for every guardian by default.

student_attendance_sessions, staff_attendance_records and student_attendance_records each carry a trigger that refuses the write when their academic_session_id (looked up directly on the first two, through session_id on the third) belongs to a session with locked_at set — see the academic-sessions backend doc's "academic-year lock" section for the trigger mechanism. student_attendance_session_runtime and attendance_change_log are not covered: the former is scheduler bookkeeping rather than the record itself, and the latter is written alongside an edit to a covered row, so the lock on that row already refuses the edit that would have produced the log entry.

5.3 The Runtime Split, Precisely

bump_row_version fires on any UPDATE, unconditionally — NEW.version := OLD.version + 1, with no IS DISTINCT FROM guard (0020_attendance_module.sql:206-211). The reminder sweep runs every minute of every school day and writes a first-period snapshot and a reminder_sent_at stamp; the idempotency check writes last_submission_id. None of those three facts is something an operator has a stake in reading atomically with version — they are the system's own bookkeeping. Had they lived on student_attendance_sessions, every sweep tick that touched an open register would silently bump the token a teacher's screen was holding, and the very next PUT from that screen would 409 with ATTENDANCE_VERSION_CONFLICT at exactly the minute the teacher was prompted to mark the register — the system denying the marking it exists to prompt. student_attendance_session_runtime exists to make that impossible by construction rather than by discipline: it has no version column, so bump_row_version cannot be attached to it at all (the function raises record "new" has no field "version" on the first UPDATE, at runtime, not at DDL time).

This is also why every session-open path — the bulk write, the reminder sweep — inserts with ON CONFLICT DO NOTHING and then re-selects, rather than issuing a no-op DO UPDATE: a no-op UPDATE is still an UPDATE, and bump_row_version cannot tell it apart from a real one.

5.4 The Append-Only Trigger

attendance_change_log_is_append_only() (0020_attendance_module.sql:263-275) is a row-level BEFORE UPDATE OR DELETE trigger that unconditionally raises, with ERRCODE = '2F002' (modifying_sql_data_not_permitted) — chosen over 23001 (restrict_violation) specifically because the latter reads as a foreign-key RESTRICT and would send a reader looking for one that does not exist here. It is row-level rather than statement-level so TRUNCATE is unaffected, which is what the integration test harness uses to clear tables between specs; a statement-level trigger here would fail every attendance test that touches the log.

5.5 Relationship Diagram

5.6 Index Rationale

6. Services and Responsibilities

6.1 SchoolClockService

Built on Intl.DateTimeFormat parts rather than a hard-coded +05:45 offset, so a school in a DST-observing zone gets the right side of a transition without this code knowing DST exists (school-clock.service.ts:45-53). hour12: false is explicitly normalised with % 24 because some ICU builds render midnight as 24, which would otherwise produce minuteOfDay = 1440 and match nothing (school-clock.service.ts:74-76).

6.2 CalendarDayService

sessionContaining selects WHERE is_active AND start_date <= date AND end_date > date and reads .limit(1) — the academic_sessions_no_active_overlap EXCLUDE constraint, not the query, guarantees at most one active session can ever cover a date. attendanceExpected on find's result is computed in TypeScript from isAttendanceRequired(classification) (packages/db/src/calendar/calendar-contract.ts:115-121) and is never stored — a value with a compile-time exhaustiveness proof over every calendar classification, so a classification added without an attendance decision fails the build rather than silently defaulting.

6.3 AttendanceRosterService

forSession is the row-scope layer: it filters students.deleted_at IS NULL, students.record_status = 'active', and the enrolment's own status = 'active' — all three, because a soft delete never fires ON DELETE and an enrolment can outlive its pupil with its own status untouched (attendance-roster.service.ts:28-38). When sessionId is null (a register never opened) the LEFT JOIN condition is forced to sql\false`, so every roster row reports status: nullrather than joining nothing at all. Ordering isrollNumber ASC NULLS LAST, admissionNumber, id` — a pupil with no assigned roll sorts last, and the two tiebreakers give pagination and the tally one stable order.

6.4 AttendanceLogService

Filters entries to previousStatus !== newStatus before inserting, so a resubmitted, unchanged register appends nothing to a table the append-only trigger will never let anyone prune (attendance-log.service.ts:39-42). Takes the caller's transaction as a required parameter — there is no default executor, unlike every read service in this module — because a log row that commits independently of the change it describes would assert something that may have rolled back.

6.5 StudentAttendanceReadService

loadState is the one assembly point: session-range gate (a date outside the class's own session is refused before the calendar is consulted, so a date that belongs to a different academic year is named as such rather than reported as a missing calendar row), calendar gate, session (or its confirmed absence), roster and tally, all from one population, returned identically by the GET, the bulk write, and every lifecycle transition — never an echo of the request (student-attendance-read.service.ts:139-183). buildClassLabel ("Grade {grade} {section} ({Shift})") and composeFullName (collapsed whitespace, matching the generated users.full_name expression) are static, so the admin surface, the overview and every portal render identically formatted labels and names.

6.6 StudentAttendanceWriteService

The full narrative for bulkMark is in §16.3. patchRecord is the correction path, keyed on the record's own version rather than the session's, and it is explicitly permitted against a completed session — that permission is what makes it a correction path rather than a duplicate of bulkMark. Its concurrency check is a conditional UPDATE ... WHERE id = $1 AND version = $2; zero rows returned is then disambiguated by a second SELECT into "the record no longer exists" (404) versus "someone else changed it" (409).

6.7 StudentAttendanceLifecycleService

None of the three registers as not_started/in_progress/completed transitions a per-pupil status directly — each acts on student_attendance_sessions.status alone. complete refuses with ATTENDANCE_INCOMPLETE_ROSTER (422) unless every row the LIVE roster returns has a non-null status, evaluated against that roster read inside the same statement rather than against any stored counter — the tally can never disagree with the roster because they are the same query. reset deletes every record for the class/date, logs one deletion row per previously-marked pupil (newStatus: null), returns the session to not_started, and clears last_submission_id so a subsequent bulk write is not treated as a stale replay. All three require input.expectedVersion to be supplied (the field is mandatory on the DTO) — reset carries the same token as complete and reopen even though it was omitted from an early draft, because it is the most destructive path in the module and a stale screen must not be able to erase marks someone else just saved.

6.8 AttendanceHistoryService

Keyset on (changed_at DESC, id DESC), filtered to subjectKind = 'student'. Both the ORDER BY and the cursor comparison wrap changed_at in date_trunc('millisecond', ...), because Postgres stores timestamptz to microsecond precision while the Node driver's Date can only hold millisecond precision — without the truncation, a cursor built from a row read back through a Date compares against the database's untruncated value and never matches, silently returning zero rows for the remainder of a tie (attendance-history.service.ts:29-41). The cursor itself is base64url(JSON.stringify([changedAtIso, id])).

6.9 AttendanceOverviewService

One row per active class in the session containing date. Every count — occupancy, marked/present/absent/late/excused, unalerted absences, reminder-sent timestamp, published/period-today schedule state — is resolved as a handful of grouped queries run in parallel (Promise.all), never a per-class round trip; a forty-class school costs a fixed number of queries, not forty (attendance-overview.service.ts:72-89). scheduleState is derived per class from whether its timetable is published and whether it has a period on date's weekday, computed by parsing the civil date at UTC midnight (weekdayOf, attendance-overview.service.ts:245-247) — there is no instant to get wrong in a plain calendar date, only a calendar day.

6.10 StaffAttendanceService

list fetches the full filtered roster (every live staff row, LEFT JOINed to that date's record) and then slices it in memory according to PaginationUtil's offset/limit — the tally is always computed over the same unsliced roster the page is drawn from, so a page boundary can never change what the tally reports. bulkWrite runs the calendar-day gate's session-membership half only (sessionContaining, 422 ATTENDANCE_DATE_OUTSIDE_SESSION if none) and never the attendanceExpected half — staff attendance is intentionally recordable on a holiday or an exam day, since refusing to record it would make the register unable to describe the days it most needs to (staff-attendance.service.ts:180-182). It is also last-write-wins: no session row exists to carry a concurrency token, so whichever PUT commits last is what the day shows; patch, in contrast, uses the record's own version, because that path has a real row to check optimistically against. history builds its keyset cursor from Postgres's own ::text rendering of changed_at fed back through ::timestamptz, a different technique from the student history's date_trunc approach but solving the identical precision-mismatch problem.

6.11 AttendanceSettingsService

list fails closed: if either of the two known kinds is missing its row, the whole read 404s rather than returning a partial or defaulted list — the workers themselves fail closed on a missing row, and the settings screen must not claim a channel state that does not exist. update validates channel membership and uniqueness in the service (422 ATTENDANCE_CHANNEL_UNKNOWN), never creates a row, and takes a SELECT ... FOR UPDATE plus a version check before writing.

6.12 TeacherAttendancePortalService

Every method resolves the caller's live staff.id via assertTeacherStaffRow first, then asserts resolvedClass.classTeacherId === staffId (assertOwnClass, throwing ATTENDANCE_NOT_CLASS_TEACHER) before touching the shared services. markAttendance passes { refuseIfCompleted: true, requireToday: true } into the exact same bulkMark transaction the admin surface calls — never a second implementation of the write.

6.13 StudentAttendancePortalService

Resolves the caller's own students row by user_id = actor.id, filtering deleted_at only. The response carries status, date, a composed class label, a note, and the Bikram Sambat parts of the date — deliberately no marked_by and no staff identity, since a pupil reading their own attendance must not learn which staff member marked them absent.

6.14 GuardianAttendancePortalService

resolveWard joins guardians → student_guardian → students → users and filters deleted_at on all three of guardians, students and users — and nothing else. It deliberately does not filter students.record_status, because that column is an administrator's ordinary record-keeping toggle (set by a plain Students_UPDATE), and promoting it to an existence predicate here would make a parent's read of their own child stricter than the pupil's own read of themselves, and would hand any Students_UPDATE holder a silent, unlogged way to revoke a parent's access. A non-ward answers 404, never 403, so the id space is not an enumeration oracle over a roll of children.

The one addition to that predicate is NOT graduateAccessEnded(students.id, today) (graduate-access.query.ts) — a pupil whose graduate access window has ended stops being reachable as "this guardian's child" in the attendance portal, and resolveWard answers the same 404 STUDENT_NOT_FOUND a non-ward gets. This is layered on top of the identity check rather than folded into students.record_status, so the graduation state (not the unrelated record-keeping flag) is what ends a parent's read of a child's attendance.

6.14a PortalAttendanceSummaryService

• Identity first. The controllers resolve the pupil before calling (StudentAttendancePortalService.resolveOwnStudentId from the token; GuardianAttendancePortalService.resolveChildId through the ward predicate). The service takes a resolved student id and applies no access rule of its own, so the cache entry is only reachable after the identity check and one entry serves both audiences.
• Window. From the current session's start_date to school-local today, or to the session's end_date once it has passed. When there is no current session, or to precedes the start, the service returns an all-zero summary with null bounds and rate.
• Totals. portalAttendanceSummary (reports/portal/queries/portal-attendance.query.ts) counts the days that are attendance-required in the calendar and fall inside one of the pupil's enrolment spans in the session, then joins the class's attendance session for that day and the pupil's record. ratePct = round((present + late) * 10000 / marked) / 100 through pctStrict: a share strictly between none and all is clamped to 0.01–99.99, so a single absence never reads 100%, while none stays 0 and all stays 100. ratePct is null when nothing is marked. unmarked is max(expectedDays - marked, 0).
• Cache. See §8.

6.15 AttendanceReminderProcessor

Full narrative in §7.7.

6.16 AttendanceAbsenceProcessor

Full narrative in §7.8.

6.17 AttendanceScheduler / AttendanceQueueProcessor

7. Runtime Flows

7.1 Bulk mark / correct the student register

7.2 Complete / reopen / reset

7.3 Correct one record (PATCH .../:recordId)

Keyed on the record's own version. Permitted against a completed session — this is deliberately the correction path for a closed day. A version mismatch and a deleted record are disambiguated by a follow-up SELECT after the conditional UPDATE returns zero rows: still exists → 409 ATTENDANCE_VERSION_CONFLICT; gone → 404 ATTENDANCE_RECORD_NOT_FOUND.

7.4 Staff register bulk write (last-write-wins)

No session row exists to carry an optimistic token, so this write is last-write-wins by design; the calendar's attendanceExpected gate is never consulted here.

7.5 The teacher portal's register (reuse, not duplication)

TeacherMarkAttendanceDto carries no force/forcedReason field, and the global ValidationPipe's forbidNonWhitelisted turns sending either into a 400 — which is what makes the holiday override unreachable from a teacher session rather than merely undocumented there.

7.6 Student and guardian portal reads

Both follow the same shape: assert the audience (assertPortalAudience), resolve the caller's own identity or their ward (filtering deleted_at only — the identity layer), then select attendance records joined to sessions/classes/grades/sections for the requested date range, returning status, a composed class label, a note, and the Bikram Sambat date parts — never marked_by. A guardian additionally resolves the ward through student_guardian, and a non-ward answers 404 rather than 403.

7.7 First-period reminder sweep

The window is [startMinute - 5, startMinute) — open at the top so a reminder never arrives after the lesson has begun, and five minutes wide so a missed, late, or slow tick is recovered by the next one rather than losing that cohort permanently. The guarded stamp (UPDATE ... WHERE reminder_sent_at IS NULL) is what makes sending exactly-once across two replicas and a replayed tick, without ever touching student_attendance_sessions.version.

The session this sweep opens always belongs to the current academic session, which the academic_sessions_current_not_locked CHECK forbids ever locking — so this insert can never be refused by the year lock, and the sweep carries no lock check of its own.

7.8 Guardian absence-alert sweep

The marker is on the record, not the session — a session-level stamp set when first period ends would close the alert window before the register is usually taken (the reminder fires five minutes before the period starts, so a class marked during or after the lesson would have zero absent records at the session-level stamping moment, and no guardian would ever be told). LIMIT 500, ORDER BY id keeps each tick bounded and lets the next tick resume deterministically; in practice student_attendance_records_pending_alert_idx never holds more than one morning's absences.

Every candidate record belongs to today's session in the current academic session, which the same CHECK keeps unlockable — the guarded UPDATE guardian_alerted_at can never be refused by the year lock either.

7.9 History pagination — the shared shape, two cursor techniques

Both GET .../students/:studentId/history and GET .../staff/:staffId/history are keyset-paginated on (changed_at DESC, id DESC), with data as the array and nextCursor as a top-level envelope field, never nested. The id tiebreaker is mandatory because now() is constant within one transaction, so one bulk mark writes many rows sharing an identical changed_at. The student path truncates both sides of the comparison to millisecond precision with date_trunc; the staff path instead round-trips changed_at through Postgres's own ::text rendering. Either technique closes the same gap — a Date-based cursor silently failing to equal the microsecond-precision row it was read from — and each history route uses exactly one of them consistently.

8. Caching

The only cached reads are the two portal attendance summary routes. Every other read is either a direct query (the register, the overview, history) or a derived-in-memory computation over one query's result (the tally).

The read uses cacheGetFast and the write cacheSetFast (apps/api/src/common/utils/cache-race.util.ts). The shared Redis client queues commands during an outage instead of rejecting them, so an awaited read would hold the request open. cacheGetFast races the read against a 250 ms budget and returns a miss on timeout or error; the service then computes from the database. cacheSetFast does not await, so a slow or lost write costs the next reader a miss and never delays the response.

9. BullMQ, Schedulers, and Async Work

AttendanceSweepPayload deliberately carries no minute (packages/jobs/src/index.ts:1034-1044): an earlier draft passed the scheduler's own minute, and a job delayed past it would serve the wrong cohort while the correct job for that minute found the notification already deduplicated — one minute's classes would silently get nothing while the log reported two successful sweeps. Instead each worker computes the local minute itself and selects over a window, so a late job still serves the right rows.

AttendanceQueueProcessor is the ONE @Processor(QueueName.ATTENDANCE, { concurrency: 2 }) class on this queue. AttendanceReminderProcessor and AttendanceAbsenceProcessor are plain @Injectable() handlers it dispatches to by job.name through a Record<AttendanceJob, …> map — never a second @Processor on the same queue, which nestjs/bullmq would otherwise instantiate as an independent competing Worker capable of running the wrong handler against the wrong payload.

Every enqueue in this module goes through BullMQ directly from a @Cron handler with no accompanying database write — the one exemption this repository's outbox rule carries for a cron-triggered job. Both cron methods catch and log rather than throw, because a throwing cron handler can take the scheduler's next tick with it; the log line is therefore the only evidence of a failed enqueue.

AttendanceWorkersModule declares no controller and is composed by the application root outside the fast runtime profile — importing a module that declares a @Processor starts a worker, and the fast profile deliberately runs none.

10. Realtime and Events

None. This module emits no Socket.IO/SSE realtime event; the only realtime event in the whole application today is feedback.submitted, owned by the support module.

11. Security, Auth, and Abuse Controls

Guards. JwtAuthGuard (global) and RoleGuard sit on every controller in this module. The admin and staff controllers declare @Permissions() on every handler: StudentAttendance_READ/CREATE/UPDATE/DELETE, StaffAttendance_READ/CREATE/UPDATE, AttendanceSettings_READ/UPDATE.

Permissions and why they are granted to no seeded role. StudentAttendance, StaffAttendance and AttendanceSettings are all declared in PERMISSION_MODULES (packages/db/src/authorization/permission-catalog.ts:258,263,267), but seed-auth.ts grants none of their codes to any seeded role. The catalogue's own comment states why (permission-catalog.ts:243-257): TEACHER_PERMISSIONS spreads STAFF_PERMISSIONS (seed-auth.ts:184), so any grant to staff reaches every teacher role identically, and the seeded staff/teacher roles both carry scopeKind: "all" — which makes Students_READ combined with that scope an unscoped read over every pupil in the school. Granting StudentAttendance_* to staff would hand every teacher the unscoped admin surface: read any pupil's history, reset any class's day. Delegating attendance to a non-administrator is instead a role the school creates deliberately, holding these codes and nothing else; grantToRoles never revokes, so withholding by default is the recoverable direction.

AttendanceView — the screen-only code. AttendanceView (permission-catalog.ts:277) gates the panel's three attendance screens — a pupil's own, a guardian's per-child view and a class teacher's register — and appears on no API route, so it grants no data access. AttendanceView_READ is seeded to staff (seed-auth.ts:113, which reaches teacher through the spread), guardian (:254) and student (:316); permissions:sync reads those grants from rolePermissionsMap. It is also the successor of AcademicCalendarView_READ in PERMISSION_SUCCESSORS (permission-catalog.ts:1006): when permissions:sync creates AttendanceView_READ, it grants it to every role — custom roles included — that already holds AcademicCalendarView_READ (grantSuccessorsToPredecessorHolders, apps/api/scripts/sync-permissions.ts:157), so a custom role that could open the attendance screens keeps them. The backfill runs only when the code is created; revoking it from a role afterwards is not undone by a later sync. It is listed in PERSON_BOUND_SCREEN_MODULES (permission-catalog.ts:961), so a superadmin's GET /api/auth/permissions list omits it: a superadmin account has no pupil, ward or class for the screens to show. It is split from AcademicCalendarView because the calendar is also an administrator screen and cannot be withheld.

The portal's audience assertion, and the two files a new handler must touch. None of the six portal handlers below carries @Permissions(). Each instead calls assertPortalAudience(actor, "student" | "guardian") or assertTeacherStaffRow(db, actor) — functions that prove who is calling, never which rows come back; the row-scope predicate in each query is the actual control. Because each handler declares no permission, its key must appear in both NO_PERMISSION_ADMIN_HANDLERS in role.guard.ts:176-224 and its CI mirror route-permissions.spec.ts:102-107, or the route 403s for everyone including superadmin with an otherwise fully green suite (the integration specs call the services directly and never pass through the guard, so that failure mode is invisible to pnpm test).

Row-scope filters. Every student-facing read in this module distinguishes the identity layer (who is this, filtering deleted_at only, failing as a 404) from the row-scope layer (which of their class rows come back, filtering deleted_at, record_status = 'active', and the enrolment's own status, failing as an empty list). AttendanceRosterService.forSession is the row-scope layer; StudentAttendancePortalService's own-identity resolution and GuardianAttendancePortalService.resolveWard are the identity layer, and neither filters record_status — see §6.14 for why that omission is deliberate rather than a gap.

Input normalization. Every free-text field that maps to a Postgres CHECK carrying the "no padding, no control characters, bounded length" pattern is validated in the DTO with a matching regex (NO_PADDING_OR_CONTROL_CHARS in the student DTOs) or a regex plus a custom @NoControlCharacters() decorator (the staff DTOs) — so the CHECK is unreachable from a well-behaved client rather than surfacing as an unmapped 500.

Audit. Every mutating admin/staff route is recorded by the application-global ActivityAuditInterceptor, deriving its module/action from the handler's own @Permissions() code. This module additionally writes its own, richer, append-only trail to attendance_change_log for every marking, correction and deletion — including the very first marking — because the interceptor's audit entry answers "who did what" while the change log answers "what was this pupil's attendance, over time."

Fail-closed decisions. CalendarDayService.require never defaults an undecided date to a school day (409). AttendanceSettingsService.list/update never default a missing settings row to enabled or disabled (404). Both workers treat an absent, disabled, or channel-less settings row as "send nothing," logged and returned rather than thrown.

Rate limits. None specific to this module; it relies on whatever global throttling the application applies.

13. Error Handling

14. Observability

No metrics are emitted by this module beyond what the global logging interceptor and BullMQ's own instrumentation provide.

15. Testing and Validation

All five suites connect only through TEST_DATABASE_URL, seed and assert against the real schema, and never mock the database, Redis, or BullMQ — per this repository's testing rule. Validation commands:

find apps packages -name '*.tsbuildinfo' -not -path '*/node_modules/*' -delete && pnpm check-types
pnpm test
pnpm --filter @skoolsewa/api test:structure
pnpm turbo run build:docs

16. Mandatory Backend Deep-Dive Pack

16.1 Submodule Coverage Matrix

Every file under apps/api/src/modules/attendance/ is represented above except pure DTO files (covered in the API doc) and dto/index.ts barrels, which re-export and contain no behavior.

16.2 UML and Architecture Diagram Pack

16.3 Code Flow Narrative — StudentAttendanceWriteService.bulkMark

1. Entry point and caller. StudentAttendanceController.mark (admin PUT) or TeacherAttendancePortalService.markAttendance (portal, after assertTeacherStaffRow/assertOwnClass).
2. DTO/command shape. BulkMarkAttendanceInput { classPublicId, date, expectedVersion, submissionId, entries, force?, forcedReason? }, plus BulkMarkAttendanceOptions { refuseIfCompleted?, requireToday? } supplied only by the portal.
3. Auth/identity assumptions. actor: AuthUser is already authenticated by JwtAuthGuard; the admin path has already passed RoleGuard on StudentAttendance_CREATE/_UPDATE, the portal path has already passed assertTeacherStaffRow and assertOwnClass.
4. Input normalization. None beyond DTO-level validation — every text field arrives already checked against the CHECK-matching regex.
5. Validation order. Non-empty entries → no duplicate studentId → not a future date → (requireToday only) is today → (inside the transaction) date within the class's own session range → calendar gate → session open → idempotency → concurrency → (refuseIfCompleted only) not completed → every entry enrolled.
6. Reads performed. classes/grades/sections (via resolveClass), academic_sessions (range check), academic_calendar_days (via CalendarDayService.require), student_attendance_sessions (open-or-find), student_attendance_session_runtime (idempotency), student_class_enrollments/students/users/student_attendance_records (via forSession, both for validation and as the pre-image for the log diff).
7. Business decisions. Whether the write is a force-write (isForceWrite = !calendarDayState.attendanceExpected); whether the session was just created (created truthy) versus pre-existing (governs the expectedVersion === null branch); which entries upsert versus delete; whether the session should advance to in_progress.
8. Writes performed. INSERT ... ON CONFLICT DO NOTHING on the session; one INSERT ... ON CONFLICT DO UPDATE covering every marked entry; one DELETE ... WHERE studentId IN (...) covering every unmarked entry; attendance_change_log insert (diffed); conditional UPDATE advancing session status; INSERT ... ON CONFLICT DO UPDATE on the runtime row's last_submission_id.
9. Transactions. The entire method after the pre-transaction validation runs inside one this.db.transaction(async (tx) => ...) — thirteen steps, one commit.
10. Cache behavior. None — this module has no cache layer.
11. Jobs/events/notifications. None synchronous; the two sweeps that later read this state run on their own schedule.
12. Response mapping. The transaction's return value is this.read.loadState(tx, resolvedClass, input.date) — always a fresh read inside the same transaction, never an echo of input.
13. Error handling. Every refusal is a typed Nest exception carrying a named errorCode (see §13); none is a bare 500 except the practically-unreachable WRITE_RETURNED_NO_ROW.
14. Logs/metrics/audit events. ActivityAuditInterceptor records the route call at the controller boundary; attendance_change_log records the domain change inside the same transaction as the state it describes.
15. Known tradeoffs. The upsert-then-delete pair is exactly two statements regardless of roster size, by design (§16.6); the idempotency check trades a second SELECT for the guarantee that a retried submit never double-applies.

16.4 Data Layer Deep Dive

Covered field-by-field in §5.2–§5.6. The one recurring pattern worth restating here: three tables in this module (student_attendance_session_runtime, school_holiday_days — owned by the calendar module, and attendance_change_log) deliberately carry no version column and no bump_row_version trigger, and each has a distinct reason — the runtime table so a per-minute cron can never invalidate an operator's token (§5.3); the change log because it is append-only and a version column on a table nothing ever updates would be meaningless. bump_row_version itself is schema-level infrastructure (function created in migration 0012); this module's migration 0020 only attaches or deliberately withholds the trigger.

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/index barrels).
• Every controller, service, provider, processor, scheduler, DTO, enum, and schema table is documented.
• Every method with business behavior has a code-flow narrative (§16.3 for the central write; §6 and §7 for the rest).
• Every table has field-level detail (§5.2).
• Every index, constraint, relation, and delete behavior has rationale (§5.2, §5.6).
• Every lifecycle/status transition has a state diagram and transition table (§7.2).
• Every read/write/action/job flow has a sequence or flow diagram (§7).
• Every business invariant is cataloged (§16.5).
• Every cache key (none), queue job, and external call is documented (§8, §9).
• 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, and event is covered (§3, §4, §6, §9).
• Every database table has a field table and relationship diagram (§5).
• Every runtime flow has a diagram and branch notes (§7).
• API, features/flows docs are linked (below).
• No claim is made without a source file or documented source reference.

See Also

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