Academic Calendar Backend Documentation

1. Documentation Evidence

2. Backend Scope and Boundaries

Owns

• The materialised, one-row-per-Gregorian-date academic calendar for a session (academic_calendar_days), its generation and repair (POST .../calendar/generate), its paginated list and BS-month grid reads, and single-day correction via PATCH.
• The school-wide weekend and attendance-cutoff configuration (school_week_config) — a single row that gates every calendar generation and has no seeded default.
• Holiday intent (school_holidays) and its application onto calendar days through the join table school_holiday_days, including the precedence recomputation that runs on every create, update, delete, and regeneration.
• The Bikram Sambat ↔ Gregorian conversion wrapper (packages/db/src/calendar/bikram-sambat.ts) and the vocabulary/attendance-decision constant (packages/db/src/calendar/calendar-contract.ts) that both this module and the seed package depend on.
• The audience-facing calendar read (CalendarPortalController/CalendarPortalService, physically in apps/api/src/modules/attendance/portal/calendar/), which every pupil, parent, teacher, and staff member reaches with no @Permissions() check at all — see §11 for why that is safe.

Does Not Own

• Whether attendance was actually taken on a date — student_attendance_sessions/student_attendance_records, owned by the attendance module. This module only answers "is attendance expected" (isAttendanceRequired) and, for the admin day detail, "does at least one attendance record already exist" (CalendarReadService.attendanceExistsFor).
• Academic session lifecycle and the non-overlap guarantee that makes "which session contains this date" a single answer — academic_sessions, academic_sessions_no_active_overlap (packages/db/src/migrations/0020_attendance_module.sql:292). This module resolves a session by its public id or by containment and refuses ACADEMIC_SESSION_NOT_FOUND otherwise, but does not create, close, or overlap-check sessions.
• The Bikram Sambat library itself (nepali-date-converter). packages/db/src/calendar/bikram-sambat.ts is stated to be the only file in the repository allowed to import it directly (packages/db/src/calendar/bikram-sambat.ts:1-38); every conversion in this module and in the portal goes through the wrapper.
• Authentication and role/permission evaluation — JwtAuthGuard, RoleGuard, RoleModule. This module declares @Permissions() codes (or deliberately none, for the portal route) and imports RoleModule so the guard can resolve, but implements no guard logic itself.
• School clock / "what is today" resolution for the portal's default month — SchoolClockService, owned by the attendance module's shared layer and only consumed here.

Source of Truth

3. Module Composition

AcademicCalendarModule is registered directly in ADMIN_MODULES (apps/api/src/config/swagger/swagger-documents.ts:88), because Swagger's include does not recurse and this module declares its controllers itself — it is the leaf, not an aggregate. CalendarPortalModule is registered as a MOBILE_CHILDREN leaf in apps/api/src/modules/mobile/mobile.module.ts:69, which is the only thing that both mounts its controller under /api/mobile (via RouterModule.register) and publishes it in the mobile Swagger document, whose membership is reflected from that same array (apps/api/src/modules/mobile/mobile.module.ts:64-68).

4. File and Directory Map

apps/api/src/modules/academic-calendar/
  academic-calendar.module.ts
  config/
    school-week-config.controller.ts
    school-week-config.service.ts
  days/
    academic-calendar.controller.ts
    calendar-read.service.ts
    calendar-generate.service.ts
    calendar-day-write.service.ts
  holidays/
    holiday-day-apply.service.ts
    school-holiday.controller.ts
    school-holiday.service.ts
  upcoming/
    calendar-upcoming.controller.ts
    calendar-upcoming.service.ts
    __tests__/
  today/
    calendar-today.controller.ts
    calendar-today.controller.spec.ts
  dto/
    calendar-day.dto.ts
    calendar-today.dto.ts
    holiday.dto.ts
    week-config.dto.ts
    index.ts
  __tests__/
    academic-calendar.integration.spec.ts

apps/api/src/modules/attendance/portal/calendar/
  calendar-portal.controller.ts
  calendar-portal.service.ts
  calendar-portal.module.ts
  dto/
    portal-calendar.dto.ts
    index.ts

apps/api/src/utils/calendar/
  calendar-today.util.ts
  calendar-today.util.spec.ts
  bikram-sambat.spec.ts

packages/db/src/calendar/
  bikram-sambat.ts
  calendar-contract.ts

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

packages/db/src/seed/
  seed-calendar-holidays.ts

5. Data Model

5.1 Schema Source

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

All four tables live in this one file; there is no separate enums.ts for this schema — the two enums (calendarDayClassificationEnum, calendarDaySourceEnum) are declared at the top of calendar.ts (packages/db/src/schema/school/calendar.ts:51-78).

5.2 Tables and Collections

school_week_config

No row is seeded (packages/db/src/migrations/0020_attendance_module.sql:228-232). Row existence is the "configured" flag: school_week_config_single_row (calendar.ts:149) is what keeps the table from ever holding more than one row, and there is deliberately no schema-level default weekend — Nepal's standard school week is Sunday–Friday while an international-curriculum school in Kathmandu runs Monday–Friday, and a wrong default would silently mis-classify a year of Fridays nobody is prompted to check.

school_holidays

Index: school_holidays_session_range_idx on (academic_session_id, from_date, to_date) — calendar.ts:238-242, serving the range lookups HolidayDayApplyService runs on every apply.

academic_calendar_days

Indexes: academic_calendar_days_session_bs_month_idx on (academic_session_id, bs_year, bs_month) for the month view (calendar.ts:339-343); academic_calendar_days_session_classification_idx on (academic_session_id, classification), which is also regeneration's delete predicate (calendar.ts:344-348); academic_calendar_days_date_idx on gregorian_date alone, for the two attendance sweeps that probe "is this date a school day" before they know the session (calendar.ts:349-354).

school_holiday_days

This table has no version column and no bump_row_version trigger — the migration says so explicitly (packages/db/src/migrations/0020_attendance_module.sql:254-260): the trigger function fails at runtime, not at DDL time, on a table with no version column, and this join table is created/deleted wholesale rather than updated. It exists precisely because a single holiday_id column on the day row cannot represent two holidays covering one date, which happens whenever a school closure overlaps a public holiday — deleting one must recompute the day from the holidays that remain, not blindly revert it (calendar.ts:358-376).

5.3 Relationship Diagram

SCHOOL_WEEK_CONFIG is drawn with no edge to the day tables: nothing references it by foreign key, and it participates only through the runtime read every generation and recomputation performs.

6. Services and Responsibilities

6.1 CalendarReadService

This service is the shared read layer: calendar-generate.service.ts and calendar-day-write.service.ts both depend on it for session resolution and the just-written re-read, matching the ClassTimeslotsReadService/ClassTimeslotsWriteService split in the timetable module (calendar-read.service.ts:43-49). Input normalization: none needed on reads. Validation order: session resolution always precedes row resolution. Transaction boundaries: every method accepts an explicit executor so a caller's open transaction is reused rather than a second pooled connection opened mid-write (db-executor.type.ts:1-12). attendanceExistsFor is a single correlated EXISTS query for the whole date set, never one query per date (calendar-read.service.ts:289-314). coverage treats staleDays as scoped to source = 'auto' rows only, because a holiday-covered day's classification does not come from the weekend rule and cannot be "stale" with respect to it (calendar-read.service.ts:316-321).

6.2 CalendarGenerateService

Input normalization: none — the only input is the path parameter. Validation order: session resolution → week-config existence → BS-range enumeration → the transaction's own read/delete/insert/reapply sequence. Transaction boundary: one db.transaction, covering the delete, the insert, and the full holiday reapplication. Idempotency: idempotent in result, not in reported diff — every run deletes every unlinked auto row and reinserts it, so a stale generated_from_weekend_days snapshot self-heals on every call, not only on request (calendar-generate.service.ts:31-38). Fail-closed: the session's end date is exclusive (academic_sessions_dates_ordered is end_date > start_date), so the calendar covers up to but never including it (calendar-generate.service.ts:66-68).

6.3 CalendarDayWriteService

Input normalization: eventName/note are trimmed server-side (calendar-day-write.service.ts:156-161) and pre-validated against the same pattern the database CHECK enforces (TEXT_FORMAT_PATTERN, calendar-day-write.service.ts:53-55), so a constraint violation is a backstop rather than the guard. Validation order: text-format assertion → session resolution → transaction with existing-row load → patch construction → version-guarded update. Concurrency: optimistic — version is part of the UPDATE's WHERE, and zero affected rows raises ATTENDANCE_VERSION_CONFLICT (this module reuses the attendance module's version-conflict code rather than declaring a calendar-specific one). Response mapping: always the freshly re-read row inside the same transaction, never an echo of the request body (calendar-day-write.service.ts:130-138). An empty patch still assigns a real column (needsReview to its own current value) purely so the UPDATE is non-trivial and the bump_row_version trigger fires, advancing the token even when nothing else changed (calendar-day-write.service.ts:107-112).

6.4 SchoolWeekConfigService

get() is the one method in this module documented to never fail: with no row, it returns { configured: false, weekendDays: [], schoolDayCutoffMinute: 1020, version: null } rather than a partial shape (school-week-config.service.ts:38-49). Validation order in update: distinctness check on weekendDays → transaction → existing-row branch. On the first configuration, an expectedVersion other than null/undefined is refused with ATTENDANCE_VERSION_CONFLICT — the caller cannot claim to have read a version that never existed (school-week-config.service.ts:77-84). On a later update, dto.expectedVersion ?? -1 guarantees a null/undefined token can never accidentally match a real version and always produces the same 409 a genuinely stale token would (school-week-config.service.ts:113-119).

6.5 SchoolHolidayService

Input normalization: name/reason trimmed server-side; text-format and date-order assertions run before the transaction opens, mirroring the CHECK constraints (school-holiday.service.ts:76-78,144-147). Validation order in create: not-school-day → dates-ordered → text-format → session resolution → range-inside-session → transaction. update is the more involved of the two: the range or classification may move, so every existing link is deleted and the holiday is relinked from the new range — narrowing reverts the days that fall out, widening applies to the days newly covered, and a classification change rewrites every day the holiday still owns (school-holiday.service.ts:294-319). remove refuses a source = 'seed' holiday with SCHOOL_HOLIDAY_NOT_DELETABLE — reclassification via PATCH is offered instead, so the record of what the platform populated is never lost (school-holiday.service.ts:326-350). Response mapping: toDto enumerates every field by hand; there is no spread from the raw row.

6.6 HolidayDayApplyService

This is the single owner of every write to school_holiday_days and of the precedence recomputation; holiday create, update, delete, and calendar generation all share this one implementation rather than four (holiday-day-apply.service.ts:18-26). Every method takes its executor as an explicit first parameter with no default db field, because every call happens inside a caller's already-open transaction (holiday-day-apply.service.ts:22-26). linkAndRecompute refuses with ACADEMIC_CALENDAR_NOT_GENERATED if the day count in the requested range does not match the expected inclusive day count — never a partial link (holiday-day-apply.service.ts:34-60). recomputeDay is the precedence engine: it reads every holiday still linked to a day, finds the first classification in HOLIDAY_PRECEDENCE order that has a match, and falls back to weekend-or-school-day (recomputing against the live school_week_config) when no holiday remains — except when the day's source is already admin_modified, in which case the method returns false immediately and touches nothing, because the administrator's edit wins over any holiday membership change (holiday-day-apply.service.ts:96-147). reapplyAllForSession exists specifically so a holiday created before the first generate() call is not silently lost — the freshly-inserted day rows from that generation have no links yet, and this method builds them (holiday-day-apply.service.ts:171-176).

6.7 CalendarPortalService (audience read, owned by the attendance module)

This service physically lives outside apps/api/src/modules/academic-calendar/, in apps/api/src/modules/attendance/portal/calendar/, but reads the same academic_calendar_days table and is the audience-facing counterpart to CalendarReadService. It resolves "this month" in two steps that are refused rather than half-completed: supplying bsYear without bsMonth (or vice versa) is a 400, because silently defaulting the missing half to the current year would answer a different question than the one asked (calendar-portal.service.ts:38-55). With neither supplied, it asks SchoolClockService for today and converts through gregorianToBs — the same wrapper the admin side uses, so the two boundary defects documented in bikram-sambat.ts are fixed in exactly one place rather than risking a second, unaudited implementation in the portal (calendar-portal.service.ts:52-55). The response mapper enumerates every field by hand and never spreads a row — see §11 for why that is the actual security control on this route, not the guard.

6.8 CalendarUpcomingService

• Window. enumerateDates(today, days) returns days ISO dates by UTC arithmetic from the school-local date.
• One row per date. selectDistinctOn(gregorian_date) over rows from active sessions, ordered so the current session wins and the lowest session id breaks any tie. Archived sessions never surface.
• Field-by-field read. The select lists the date, classification, event name and BS parts. note is not selected, because the route is open to every session.
• Days. A date with a row carries its classification, isOperatingDay = isAttendanceRequired(classification) and its stored BS date. A date without a row carries null classification, null isOperatingDay, null event name and a BS date converted from the Gregorian date, or null when the converter throws.
• Events. groupEvents walks the days and merges consecutive notable days that share classification and event name. A day is notable when it has an event name, or its classification is not school_day or weekend.
• Cache. See §8.

7. Runtime Flows

7.1 Generate (or repair) a calendar

7.2 Configure the school week — first save vs. later update

Distinctness of weekendDays is a service rule (assertNoDuplicateWeekendDays), never a CHECK — an array CHECK cannot express "no repeated element" without a subquery, and a CHECK with no application refusal in front of it is an unmapped SQLSTATE rather than validation (school-week-config.service.ts:143-149).

7.3 Create a holiday

7.4 Update a holiday — narrow, widen, or reclassify

Every existing link is deleted and rebuilt from the new range rather than diffed, because the classification may also have changed — rewriting every day the holiday still owns is simpler and provably correct, at the cost of recomputing days whose membership did not actually change (school-holiday.service.ts:294-319).

7.5 Delete a holiday

The links are read before the delete so the ids to recompute are known — the ON DELETE cascade on school_holiday_days removes them a moment later, and by the time recomputeMany runs, each day's remaining holidays (if any) are exactly what decides its new classification (school-holiday.service.ts:352-364).

7.6 PATCH a calendar day

7.7 Portal month view

Guest vs. logged-in branch: not applicable — every caller must hold a JWT, and the route makes no audience distinction at all (see §11). Cache miss/hit: no cache exists. Race/concurrency: none — this is a pure read with no write side.

8. Caching

Only GET /api/calendar/upcoming is cached. Every other read in this module and in calendar-portal.service.ts runs directly against PostgreSQL.

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 reads PostgreSQL. cacheSetFast does not await, so a slow or lost write costs the next reader a miss and never delays the response. The value is identical for every caller, so a single entry per date and window length serves all audiences.

9. BullMQ, Schedulers, and Async Work

None owned by this module. Generation, holiday application, and every write are synchronous within the request's own transaction. (The attendance module's own schedulers separately read academic_calendar_days.classification to decide whether to expect a register or wake a teacher, but they are documented in the attendance module's own docs, not here.)

10. Realtime and Events

None. No Socket.IO gateway, room, or emitted event exists in this module.

11. Security, Auth, and Abuse Controls

• Guards. Every controller — SchoolWeekConfigController, AcademicCalendarController, SchoolHolidayController, CalendarPortalController, and CalendarTodayController — carries @UseGuards(JwtAuthGuard, RoleGuard).
• Permissions. The three admin controllers gate every route with @Permissions("AcademicCalendar_..."). CalendarPortalController.monthView carries no @Permissions() decorator at all — the calendar names no person, so unlike every other portal route in the attendance module, it needs no audience assertion (calendar-portal.controller.ts:9-31).
• The no-permission route's real safety mechanism. Because RoleGuard reads a non-mobile-prefixed-looking handler with no @Permissions() as an admin surface and throws unless allowlisted, CalendarPortalController.monthView must be listed in NO_PERMISSION_ADMIN_HANDLERS (apps/api/src/common/authorization/role.guard.ts:228, key "CalendarPortalController.monthView") and its CI mirror test/structure/route-permissions.spec.ts. What actually keeps the route safe with no guard behind it is the frozen response shape — PortalCalendarDayDto enumerates every field by hand and never spreads a row, so note (administrator-internal free text) can never reach a pupil or parent through a column added later to academic_calendar_days (apps/api/src/modules/attendance/portal/calendar/dto/portal-calendar.dto.ts:71-93).
• The today route. CalendarTodayController.today (GET /api/calendar/today) also carries no @Permissions() and is listed in NO_PERMISSION_ADMIN_HANDLERS under "CalendarTodayController.today", with its mirror in test/structure/route-permissions.spec.ts. It reads no database, cache, queue, Redis or MongoDB: the response is today's date in Asia/Kathmandu and its BS equivalent, computed from the clock alone, so it carries no user, school or row data.
• Object-level vs. field-level scope. AcademicCalendar_* (full CRUD) is held by no seeded role except superadmin — packages/db/src/seed/seed-auth.ts:214-220 shows staff, teacher, guardian, and student all hold at most AcademicCalendarView_READ, never the CRUD codes, because the day and holiday rows carry an administrator's free-text note/reason plus the id of who wrote them (packages/db/src/authorization/permission-catalog.ts:225-233). AcademicCalendarView_READ itself gates the panel screen, not any route — it appears on zero API routes, exactly like Schedule_READ (permission-catalog.ts:234-243) — and is granted to staff/teacher (seed-auth.ts:110), guardian (seed-auth.ts:162), and student (seed-auth.ts:195).
• Guest identity. Not applicable; every route in this module requires an authenticated JWT.
• Rate limits. No module-specific limiter; relies on the platform-wide default.
• Input normalization. label-equivalent free text (eventName, note, holiday name/reason) is trimmed server-side before every write, matching the database CHECK constraints that reject leading/trailing whitespace and control characters.
• Sensitive data redaction. note/reason never leave the admin surface. CalendarDayDto/CalendarDayDetailDto/MonthCalendarDayDto (admin-facing) all carry note; PortalCalendarDayDto (audience-facing) is a deliberately smaller, hand-enumerated class that carries neither note, reason, source, needsReview, any holiday id, createdByUserId, configuredByUserId, version, nor generatedFromWeekendDays (portal-calendar.dto.ts:71-82).
• Audit logs. school_week_config.configured_by_user_id and school_holidays.created_by_user_id are the only accountability trail this module writes — both real foreign keys to users, both asserted by the integration test (academic-calendar.integration.spec.ts:157-186).
• Fail-closed behavior. Generation refuses outright while school_week_config has no row (CALENDAR_WEEKEND_NOT_CONFIGURED) rather than assuming a default weekend; a holiday can never link a day the calendar has not generated yet (ACADEMIC_CALENDAR_NOT_GENERATED); a holiday's classification can never be school_day (checked in the service, since the enum itself cannot express the exclusion without a CHECK that would break on a future enum value — see §16.6).

13. Error Handling

14. Observability

15. Testing and Validation

Validation commands, from the repository root: pnpm --filter @skoolsewa/api test runs the whole suite; pnpm --filter @skoolsewa/api test:int runs the integration specs alone, including this module's real-database test against TestDatabase (academic-calendar.integration.spec.ts:1-15).

16. Mandatory Backend Deep-Dive Pack

16.1 Submodule Coverage Matrix

Every file in apps/api/src/modules/academic-calendar/ is represented above. CalendarPortalController/CalendarPortalService physically live under apps/api/src/modules/attendance/portal/calendar/ — a deliberate placement documented in this file per the task's own instruction, since the calendar read is an attendance-adjacent audience surface rather than an admin-CRUD one — and are included here because they are the audience-facing counterpart of CalendarReadService. SchoolClockService and CalendarDayService, imported by CalendarPortalService, are shared attendance-module infrastructure documented in the attendance module's own docs, not duplicated here.

16.2 UML and Architecture Diagram Pack

No BullMQ or realtime dependency exists for this module, and Redis serves only the 60-second read cache of GET /api/calendar/upcoming, which falls back to PostgreSQL. The deployment diagram is deliberately just the two API surfaces and PostgreSQL.

16.3 Code Flow Narrative — HolidayDayApplyService.recomputeDay

1. Entry point. Called from recomputeMany, itself called by linkAndRecompute, reapplyAllForSession, SchoolHolidayService.update, and SchoolHolidayService.remove — every holiday-touching write path converges here.
2. Command shape. (executor, calendarDayId: string).
3. Auth/identity. None checked here — the caller has already resolved and authorized the surrounding operation; this method is purely a data-consistency step.
4. Input normalization. None; the id is opaque.
5. Validation order. Load the day row; if absent, return false immediately. If source === "admin_modified", return false immediately — the administrator's edit is never overwritten by a holiday membership change.
6. Reads performed. The day row itself; the join of school_holiday_days to school_holidays for that day, ordered by holiday id (a stable tie-break); school_week_config, but only on the fallback branch where no holiday remains linked.
7. Business decisions. HOLIDAY_PRECEDENCE.find(...) picks the first classification in precedence order that has at least one matching linked holiday. If one is found, its source (holiday's own source, school or seed) is copied onto the day; if none is found, the day falls back to weekend/school_day against the live week configuration and source: 'auto'.
8. Writes performed. UPDATE academic_calendar_days SET classification, source, generated_from_weekend_days WHERE id = calendarDayId — but only when at least one of those three actually changed (sameSet comparison on the weekend array).
9. Transactions. None opened here; always runs inside the caller's already-open transaction.
10. Cache behavior. None.
11. Jobs/events/notifications. None.
12. Response mapping. Returns a boolean — whether the stored row actually changed — which callers sum into a changedCount/repairedCount.
13. Error handling. None thrown from this method; a missing day row is treated as "nothing to do", not an error, because the caller (e.g. a holiday delete) may be recomputing ids for a day whose calendar row genuinely does not exist in an edge case.
14. Logs/metrics/audit. None.
15. Known tradeoffs. Precedence is a linear scan over four possible classifications and a handful of linked holidays per day — deliberately not expressed as a database rule; see §16.6.

16.4 Data Layer Deep Dive

Covered exhaustively in §5 for all four tables: full field tables, nullability, index rationale, constraint rationale, FK delete behavior, versioning fields (school_week_config, school_holidays, academic_calendar_days all carry version and a bump_row_version trigger; school_holiday_days deliberately carries neither), audit fields (configured_by_user_id, created_by_user_id), timezone interpretation (every date column is a bare date, always read and written as a Kathmandu-local YYYY-MM-DD string — never through Date.toISOString(), per the wrapper's own documented defect), and seed-data dependency (school_holidays.source = 'seed' rows, populated from seed-calendar-holidays.ts's vocabulary — though see §16.6 for the gap in how that seed reaches the table today).

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.
• Every controller, service, provider, processor, scheduler, helper, mapper, DTO, enum, and schema is documented.
• Every method with business behavior has a code-flow narrative (recomputeDay in full; others summarized in §6/§7 tables).
• Every table/collection/cache object/job payload has field-level detail.
• Every index, constraint, relation, and delete behavior has rationale.
• Every lifecycle/status transition (day classification/source transitions) has a table; no separate state diagram is drawn because the transitions are read-and-recompute, not a formal state machine — see the feature/flows doc for the day lifecycle table.
• Every read/write/action/job flow has sequence and activity diagrams.
• Every business invariant is cataloged.
• Every cache key, invalidation path, queue job, realtime event, and external call is documented (all absent, and stated as such).
• Every architectural tradeoff is documented with alternatives and revisit triggers, including the unwired seed-data gap.
• Every operational failure mode has a runbook entry.

18. Backend Completion Checklist

• Module boundaries are documented.
• Every controller, service, DTO, schema file, job, cache key, and event is covered.
• Every database table has a field table and relationship diagram.
• Every runtime flow has a diagram and branch notes.
• API, feature/flows, and TDD docs are linked below (no TDD doc exists for this module; only API and feature/flows are linked, matching what was produced).
• No claim is made without a source file or documented source reference.

See Also

• API doc: /docs/developer/academic-calendar/api
• Features and flows doc: /docs/developer/academic-calendar/feature