Academic Calendar - API Reference

Audience: Frontend engineers, mobile engineers, backend engineers, QA, and API consumers. Scope: Admin calendar generation/read/correction, admin holiday CRUD, admin week configuration, and the one mobile-audience calendar read owned by Academic Calendar.

1. Documentation Evidence

2. Module Summary

3. Concepts and Terminology

4. API Surface Map

Every path above is read directly from the controller's @Controller() base plus its method decorator: AcademicCalendarController declares @Controller("academic-sessions/:sessionPublicId/calendar") (days/academic-calendar.controller.ts:35); SchoolHolidayController declares a bare @Controller() and states its own full path per method (holidays/school-holiday.controller.ts:42-112), which is why the list/create routes are session-scoped while update/delete are holiday-id-scoped with no common prefix; SchoolWeekConfigController declares @Controller("school/week-config") (config/school-week-config.controller.ts:23); CalendarPortalController declares @Controller("calendar") (calendar-portal.controller.ts:35), and the /api/mobile prefix is added by RouterModule.register() in apps/api/src/modules/mobile/mobile.module.ts:64-80, never by the controller decorator itself. The global prefix /api is applied in apps/api/src/main.ts:86.

AcademicCalendarModule is registered in ADMIN_MODULES (apps/api/src/config/swagger/swagger-documents.ts:88) and therefore appears in the admin Swagger document; CalendarPortalModule is registered as a MOBILE_CHILDREN leaf (apps/api/src/modules/mobile/mobile.module.ts:69) and therefore appears only in the mobile Swagger document, which is filtered by isMobilePath/isAdminPath in apps/api/src/config/swagger/swagger.shared.ts:29-38.

5. Auth, Identity, and Permissions

Which roles actually hold the admin permission codes: only superadmin is granted fullAccessPermissions, which includes every AcademicCalendar_* CRUD code (packages/db/src/seed/seed-auth.ts:214). The other four seeded roles — staff, teacher, guardian, student — hold only AcademicCalendarView_READ (seed-auth.ts:110,162,195), a code that gates the panel's calendar screen and appears on zero API routes (packages/db/src/authorization/permission-catalog.ts:234-243). In practice this means every admin route in this module is reachable only by superadmin out of the box, and a school that wants a non-superadmin operator to manage the calendar must grant AcademicCalendar_* to a custom role explicitly.

CalendarPortalController.monthView carries no @Permissions() decorator at all (calendar-portal.controller.ts:36-49) — the calendar names no person, so unlike every other portal route in the attendance module, it asserts no audience. Because RoleGuard otherwise treats a non-mobile-looking handler with no @Permissions() as an admin surface and throws, this handler is explicitly allowlisted in NO_PERMISSION_ADMIN_HANDLERS under the key "CalendarPortalController.monthView" (apps/api/src/common/authorization/role.guard.ts:228) and mirrored in test/structure/route-permissions.spec.ts. What actually makes the route safe with no permission check is the response shape: PortalCalendarDayDto enumerates every field by hand and is never built by spreading a row, so a column such as note (administrator-internal text) can never reach this response even if added to academic_calendar_days later (apps/api/src/modules/attendance/portal/calendar/dto/portal-calendar.dto.ts:71-93).

6. DTO and Model Reference

6.1 SchoolWeekConfigDto (response, GET/PUT school/week-config)

weekendDays and schoolDayCutoffMinute are always present, even when configured is false — the service returns { configured: false, weekendDays: [], schoolDayCutoffMinute: 1020, version: null } rather than omitting them (school-week-config.service.ts:38-49). This is a deliberate fix for a real defect: the settings screen crashed on weekendDays is not iterable the first time it met an unconfigured school, which is every school, exactly once (week-config.dto.ts:33-40).

6.2 UpdateSchoolWeekConfigDto (request, PUT school/week-config)

weekendDays may be an empty array — a seven-day residential school has no weekend, and this is a legal, saved configuration, not an incomplete one. Distinctness (no repeated day) is checked server-side, not by class-validator and not by a CHECK — an array CHECK cannot express "no duplicates" without a subquery (school-week-config.service.ts:143-149).

6.3 CalendarDayHolidayDto (response, nested)

6.4 CalendarDayDto (response, base shape)

6.5 MonthCalendarDayDto (response, GET .../calendar/months/:bsYear/:bsMonth)

CalendarDayDto plus:

6.6 CalendarDayDetailDto (response, GET/PATCH .../calendar/days/:date)

CalendarDayDto plus:

6.7 CalendarCoverageDto (response, nested)

6.8 CalendarDayListDto (response, GET .../calendar)

6.9 GenerateCalendarDto (response, POST .../calendar/generate)

6.10 ListCalendarDaysQueryDto (query, GET .../calendar)

Inherits pagination, page, size, sort, order, search from QueryDto (apps/api/src/common/dto/query.dto.ts:14-64) — sort/order/search are accepted but ignored, since the list is always ordered by gregorianDate.

6.11 UpdateCalendarDayDto (request, PATCH .../calendar/days/:date)

Setting any field other than expectedVersion on an auto/seed day moves it to admin_modified, protecting it from the next regeneration and from holiday precedence recomputation.

6.12 SchoolHolidayDto (response)

6.13 CreateSchoolHolidayDto (request, POST .../holidays)

Server-generated/overwritten fields not accepted from the client: id, source (always written as "school" for this route), createdByUserId (from @CurrentAdmin()), version (always 0 on insert).

6.14 UpdateSchoolHolidayDto (request, PATCH holidays/:holidayId)

Every field optional except expectedVersion.

6.15 PortalCalendarDayDto (response, GET /api/mobile/calendar)

FROZEN — enumerated by hand at CalendarPortalService.monthView's mapper, never a spread.

Deliberately absent: note, reason, source, needsReview, any holiday id, createdByUserId, configuredByUserId, version, generatedFromWeekendDays — every one of them either administrator-internal, an internal-provenance field, or a concurrency/staleness detail the audience side has no use for (portal-calendar.dto.ts:71-82).

6.16 CalendarPortalQueryDto (query, GET /api/mobile/calendar)

Both bsYear and bsMonth must be supplied together or omitted together — supplying only one is refused with CALENDAR_BS_DATE_INVALID rather than silently defaulting the missing half to the current year (calendar-portal.service.ts:38-55).

6.17 CalendarTodayDto (response, GET /api/calendar/today)

The six bs*/*Np fields are null together when the date is outside the converter's range. date and dayOfWeek are always present.

6.18 Upcoming DTOs (GET /api/calendar/upcoming)

Source: dto/calendar-upcoming.dto.ts.

CalendarUpcomingQueryDto (query):

CalendarUpcomingDto (response):

CalendarUpcomingDayDto:

CalendarUpcomingEventDto:

The administrator note column is never selected and appears in no field.

7. Enum Reference

classification = school_day on a school_holidays row is refused by SchoolHolidayService.assertNotSchoolDay, not by the database enum itself — see the backend doc's §16.6 for why this is a service rule rather than a CHECK.

8. Endpoint Reference

8.1 POST /api/academic-sessions/:sessionPublicId/calendar/generate

Purpose

Generates or repairs the calendar for one academic session. Call it once after a session is created and its week is configured, and again any time the week configuration changes, a holiday was created before the calendar existed, or the coverage response reports staleDays > 0. It is additive-with-repair and safe to call repeatedly.

Source Evidence

Auth and Permissions

• Auth: JWT.
• Guard chain: JwtAuthGuard, RoleGuard.
• Permission: AcademicCalendar_CREATE.
• Guest support: No.
• Rate limit: None module-specific.
• Idempotency: Result-idempotent, not diff-idempotent — every call deletes and reinserts every unlinked auto row, so a stale weekend snapshot self-heals on every run.

Request

Response

{
  "message": "Academic calendar generated.",
  "data": {
    "generated": 240,
    "deleted": 0,
    "repaired": 0,
    "coverage": {
      "expectedDays": 240,
      "presentDays": 240,
      "staleDays": 0
    }
  }
}

Side Effects

• Database writes: deletes unlinked auto rows of academic_calendar_days, inserts every missing date, re-links and recomputes every existing holiday of the session via HolidayDayApplyService.reapplyAllForSession.
• No cache, job, realtime, notification, or external call.

Error Cases

Edge Cases

• A session with zero calendar rows and no existing holidays generates every day as auto, generated = expectedDays, deleted = 0, repaired = 0.
• Calling generate a second time with nothing changed reports generated = presentDays, deleted = presentDays (every previously-inserted auto row is unlinked and gets rewritten) — the response's coverage is identical both times; only the diff counters differ (confirmed by the integration spec's "generates a full session and is idempotent (in RESULT) on a second run" case).
• An admin_modified day is excluded from the delete predicate entirely — it is never deleted or reinserted, and generated/deleted both drop by exactly one relative to a run with no such day.
• A holiday created before the first generate() call is picked up on the next run through reapplyAllForSession, not lost.

Example Requests

curl -X POST "$API_URL/api/academic-sessions/018f2f3e-.../calendar/generate" \
  -H "Authorization: Bearer TOKEN"

8.2 GET /api/academic-sessions/:sessionPublicId/calendar

Purpose

The paginated, filterable day list for one session, plus a session-wide coverage summary that is always computed independently of the list's own filters. Used to power a table/list view of the calendar, and to detect staleness after a week-configuration change.

Source Evidence

Auth and Permissions

• Auth: JWT.
• Guard chain: JwtAuthGuard, RoleGuard.
• Permission: AcademicCalendar_READ.
• Guest support: No.
• Rate limit: None module-specific.
• Idempotency: N/A (read).

Request

Response

{
  "message": "Calendar days fetched.",
  "data": {
    "days": [
      {
        "id": "018f2f40-...",
        "gregorianDate": "2026-04-15",
        "bsYear": 2083,
        "bsMonth": 1,
        "bsDay": 1,
        "dayOfWeek": 3,
        "classification": "public_holiday",
        "source": "seed",
        "eventName": "Nepali New Year",
        "note": null,
        "needsReview": false,
        "attendanceExpected": false,
        "attendanceExists": false,
        "version": 0
      }
    ],
    "coverage": {
      "expectedDays": 240,
      "presentDays": 240,
      "staleDays": 0
    }
  }
}

Side Effects

None — read-only.

Error Cases

Edge Cases

• coverage is computed independently of every filter on the list — filtering to classification=weekend still returns the session's full expectedDays/presentDays/staleDays, not a filtered subset.
• An empty filtered result returns days: [] with a populated, non-empty coverage block.
• staleDays is scoped to source = 'auto' rows only — a holiday-covered day is never counted as stale, since its classification does not come from the weekend rule.

Example Requests

curl -X GET "$API_URL/api/academic-sessions/018f2f3e-.../calendar?bsYear=2083&bsMonth=1" \
  -H "Authorization: Bearer TOKEN"

8.3 GET /api/academic-sessions/:sessionPublicId/calendar/months/:bsYear/:bsMonth

Purpose

One Bikram Sambat month rendered as a grid, with each day carrying the names of every holiday covering it. This is the admin calendar screen's primary month view.

Source Evidence

Auth and Permissions

• Auth: JWT.
• Guard chain: JwtAuthGuard, RoleGuard.
• Permission: AcademicCalendar_READ.
• Guest support: No.
• Rate limit: None module-specific.
• Idempotency: N/A (read).

Request

Response

{
  "message": "Calendar month fetched.",
  "data": [
    {
      "id": "018f2f40-...",
      "gregorianDate": "2026-04-15",
      "bsYear": 2083,
      "bsMonth": 1,
      "bsDay": 1,
      "dayOfWeek": 3,
      "classification": "public_holiday",
      "source": "seed",
      "eventName": "Nepali New Year",
      "note": null,
      "needsReview": false,
      "attendanceExpected": false,
      "attendanceExists": false,
      "version": 0,
      "holidayNames": ["Nepali New Year"]
    }
  ]
}

Side Effects

None — read-only.

Error Cases

Edge Cases

• A BS month with zero generated rows returns an empty array [], never a 404 — the calendar simply has not been generated that far, or the session does not cover that month.
• holidayNames is [] for a day covered by no holiday, never omitted.
• The range check on bsYear/bsMonth runs before session resolution, so an out-of-range year is refused even for a session id that would itself not resolve.

Example Requests

curl -X GET "$API_URL/api/academic-sessions/018f2f3e-.../calendar/months/2083/1" \
  -H "Authorization: Bearer TOKEN"

8.4 GET /api/academic-sessions/:sessionPublicId/calendar/days/:date

Purpose

The single-day detail view — used by the day drawer/dialog when an administrator clicks a date, showing the full holiday rows (not just names) currently covering it.

Source Evidence

Auth and Permissions

• Auth: JWT.
• Guard chain: JwtAuthGuard, RoleGuard.
• Permission: AcademicCalendar_READ.
• Guest support: No.
• Rate limit: None module-specific.
• Idempotency: N/A (read).

Request

Response

{
  "message": "Calendar day fetched.",
  "data": {
    "id": "018f2f40-...",
    "gregorianDate": "2026-04-15",
    "bsYear": 2083,
    "bsMonth": 1,
    "bsDay": 1,
    "dayOfWeek": 3,
    "classification": "public_holiday",
    "source": "seed",
    "eventName": "Nepali New Year",
    "note": null,
    "needsReview": false,
    "attendanceExpected": false,
    "attendanceExists": false,
    "version": 0,
    "holidays": [
      { "id": "018f2f50-...", "name": "Nepali New Year", "classification": "public_holiday" }
    ]
  }
}

Side Effects

None — read-only.

Error Cases

Edge Cases

• A date never generated for the session returns 404 CALENDAR_DAY_NOT_FOUND, never a synthesized default row — a missing row is never treated as a school day.
• holidays is [] for a day covered by no holiday.
• attendanceExists reflects real recorded attendance regardless of attendanceExpected — a day where attendance was recorded despite not being expected still reports attendanceExists: true.

Example Requests

curl -X GET "$API_URL/api/academic-sessions/018f2f3e-.../calendar/days/2026-04-15" \
  -H "Authorization: Bearer TOKEN"

8.5 PATCH /api/academic-sessions/:sessionPublicId/calendar/days/:date

Purpose

Corrects one calendar day — reclassifying it, adding an event name or an internal note, or flagging it for review. Every write moves an auto/seed day to admin_modified, which is what protects it from the next regeneration and from holiday precedence recomputation.

Source Evidence

Auth and Permissions

• Auth: JWT.
• Guard chain: JwtAuthGuard, RoleGuard.
• Permission: AcademicCalendar_UPDATE.
• Guest support: No.
• Rate limit: None module-specific.
• Idempotency: Not idempotent by design — expectedVersion is required and a repeat with the same stale version is refused with 409.

Request

{
  "classification": "special_school_day",
  "eventName": "Sports Day",
  "expectedVersion": 0
}

Response

Same shape as §8.4's response — the freshly re-read CalendarDayDetailDto.

Side Effects

• Database write: academic_calendar_days UPDATE, version-guarded; moves source to admin_modified when the existing row was auto or seed.
• No cache, job, realtime, notification, or external call.

Error Cases

Edge Cases

• A body carrying only expectedVersion (no other field) still succeeds and still bumps version by exactly one — the service assigns needsReview to its own current value so the UPDATE is non-trivial and the trigger fires (calendar-day-write.service.ts:107-112).
• Patching a day that is already admin_modified keeps it admin_modified — the source transition is one-directional through this route.
• note and eventName can each be cleared by sending null.
• The re-read after the write is inside the same transaction — the response is never an echo of the request body.

Example Requests

curl -X PATCH "$API_URL/api/academic-sessions/018f2f3e-.../calendar/days/2026-04-15" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"classification":"special_school_day","expectedVersion":0}'

8.6 GET /api/academic-sessions/:sessionPublicId/holidays

Purpose

Lists the holidays of one academic session, for the holiday management screen.

Source Evidence

Auth and Permissions

• Auth: JWT.
• Guard chain: JwtAuthGuard, RoleGuard.
• Permission: AcademicCalendar_READ.
• Guest support: No.
• Rate limit: None module-specific.
• Idempotency: N/A (read).

Request

Response

The array is the top-level data; count/currentPage/totalPage are top-level envelope fields, not nested a second time inside data — the service deliberately returns { items, count, page, size } rather than { data, count }, because nesting a second data broke a screen that called holidays.map on an object (school-holiday.service.ts:88-91).

{
  "message": "Holidays fetched.",
  "data": [
    {
      "id": "018f2f50-...",
      "name": "Nepali New Year",
      "classification": "public_holiday",
      "fromDate": "2026-04-14",
      "toDate": "2026-04-14",
      "reason": null,
      "source": "seed",
      "version": 0
    }
  ],
  "count": 1,
  "currentPage": 1,
  "totalPage": 1
}

Side Effects

None — read-only.

Error Cases

Edge Cases

• A session with no holidays returns data: [], count: 0, currentPage: 1, totalPage: 0.
• pagination=false returns every holiday of the session up to PaginationUtil.UNPAGINATED_HARD_CAP (1000), with count computed from the returned row count rather than a separate COUNT(*).

Example Requests

curl -X GET "$API_URL/api/academic-sessions/018f2f3e-.../holidays" \
  -H "Authorization: Bearer TOKEN"

8.7 POST /api/academic-sessions/:sessionPublicId/holidays

Purpose

Creates a holiday and immediately applies it: every calendar day in [fromDate, toDate] is linked and recomputed in the same transaction. The range must already be fully generated.

Source Evidence

Auth and Permissions

• Auth: JWT.
• Guard chain: JwtAuthGuard, RoleGuard.
• Permission: AcademicCalendar_CREATE.
• Guest support: No.
• Rate limit: None module-specific.
• Idempotency: Not idempotent — every call creates a new holiday row.

Request

{
  "name": "School closed",
  "classification": "school_holiday",
  "fromDate": "2026-04-16",
  "toDate": "2026-04-18",
  "reason": "Maintenance"
}

Response

{
  "message": "Holiday created.",
  "data": {
    "id": "018f2f60-...",
    "name": "School closed",
    "classification": "school_holiday",
    "fromDate": "2026-04-16",
    "toDate": "2026-04-18",
    "reason": "Maintenance",
    "source": "school",
    "version": 0
  }
}

Side Effects

• Database writes: school_holidays insert; school_holiday_days insert for every covered day; academic_calendar_days update for every day whose classification/source actually changes (via HolidayDayApplyService).
• createdByUserId is set from the authenticated caller (@CurrentAdmin()).
• No cache, job, realtime, notification, or external call.

Error Cases

Edge Cases

• A single-day holiday is created with fromDate === toDate.
• Creating a holiday whose range overlaps an existing holiday of a different classification does not error — both link to the shared days, and HOLIDAY_PRECEDENCE decides which classification the overlapping days show.
• Creating a holiday over a range that includes an admin_modified day still links it (school_holiday_days gets the row), but recomputeDay leaves that day's classification/source untouched — the admin's edit wins.

Example Requests

curl -X POST "$API_URL/api/academic-sessions/018f2f3e-.../holidays" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"School closed","classification":"school_holiday","fromDate":"2026-04-16","toDate":"2026-04-18","reason":"Maintenance"}'

8.8 PATCH /api/holidays/:holidayId

Purpose

Updates a holiday's name, classification, range, or reason. Narrowing the range reverts the days that fall out; widening applies to the days that fall in; a classification change rewrites every day the holiday still owns.

Source Evidence

Auth and Permissions

• Auth: JWT.
• Guard chain: JwtAuthGuard, RoleGuard.
• Permission: AcademicCalendar_UPDATE.
• Guest support: No.
• Rate limit: None module-specific.
• Idempotency: Not idempotent — expectedVersion is required and a repeat with a stale version is refused with 409.

Request

{
  "toDate": "2026-04-20",
  "expectedVersion": 0
}

Response

Same shape as §8.7's response, reflecting the updated row.

Side Effects

• Database writes: school_holidays update (version-guarded); every existing school_holiday_days link for this holiday deleted; new links inserted for the new range; recomputation of every day newly covered and every day that fell out.
• No cache, job, realtime, notification, or external call.

Error Cases

Edge Cases

• Narrowing toDate reverts every day that fell out of the range to whatever classification the remaining holidays (or the weekend rule) dictate — never left classified as the old holiday.
• Changing only classification (same range) rewrites every currently-linked day's classification/source, without touching the link set itself.
• A patch body that changes nothing meaningful still sends name = existing.name internally so the UPDATE is non-trivial and the version bumps (school-holiday.service.ts:255).

Example Requests

curl -X PATCH "$API_URL/api/holidays/018f2f60-..." \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"toDate":"2026-04-20","expectedVersion":0}'

8.9 DELETE /api/holidays/:holidayId

Purpose

Deletes a holiday and recomputes every day it covered from whichever holidays remain. Refused for seeded holidays — reclassify instead of deleting, so the record of what the platform populated is preserved.

Source Evidence

Auth and Permissions

• Auth: JWT.
• Guard chain: JwtAuthGuard, RoleGuard.
• Permission: AcademicCalendar_DELETE.
• Guest support: No.
• Rate limit: None module-specific.
• Idempotency: The second delete of the same id 404s — not naturally idempotent.

Request

Response

{
  "message": "Holiday deleted.",
  "data": null
}

Side Effects

• Database writes: school_holidays delete, cascading school_holiday_days via the foreign key; recomputation of every day that was linked.
• No cache, job, realtime, notification, or external call.

Error Cases

Edge Cases

• Deleting a holiday that is the only one covering a set of days reverts each to weekend/school_day (against the live week configuration) and source: 'auto'.
• Deleting a holiday that shares days with another still-active holiday leaves those days classified by whichever remaining holiday wins under HOLIDAY_PRECEDENCE.
• Deleting a holiday that covers an admin_modified day leaves that day's classification/source untouched.

Example Requests

curl -X DELETE "$API_URL/api/holidays/018f2f60-..." \
  -H "Authorization: Bearer TOKEN"

8.10 GET /api/school/week-config

Purpose

Reads the school-wide weekend and attendance-cutoff configuration. Called before offering calendar generation, to decide whether to show the "configure your week first" prompt.

Source Evidence

Auth and Permissions

• Auth: JWT.
• Guard chain: JwtAuthGuard, RoleGuard.
• Permission: AcademicCalendar_READ.
• Guest support: No.
• Rate limit: None module-specific.
• Idempotency: N/A (read).

Request

Response — unconfigured (no row exists)

{
  "message": "School week configuration fetched.",
  "data": {
    "configured": false,
    "weekendDays": [],
    "schoolDayCutoffMinute": 1020,
    "version": null
  }
}

Every field is present even though the school has never saved a configuration — weekendDays is [], schoolDayCutoffMinute is the shipped default (1020 = 17:00), and version is null so the client knows to send expectedVersion: null on its first save. This shape exists because the settings screen previously crashed with weekendDays is not iterable when the array was omitted entirely (school-week-config.service.ts:38-49).

Response — configured

{
  "message": "School week configuration fetched.",
  "data": {
    "configured": true,
    "weekendDays": [5, 6],
    "schoolDayCutoffMinute": 1020,
    "version": 2
  }
}

Side Effects

None — read-only.

Error Cases

None. This endpoint never errors; the unconfigured state is a valid response, not a failure.

Edge Cases

• weekendDays: [] is returned both when the school is genuinely unconfigured and when a configured school has deliberately chosen a seven-day week — configured is the only field that distinguishes the two.

Example Requests

curl -X GET "$API_URL/api/school/week-config" \
  -H "Authorization: Bearer TOKEN"

8.11 PUT /api/school/week-config

Purpose

Upserts the single school-week-configuration row. Must be called successfully at least once before any session's calendar can be generated.

Source Evidence

Auth and Permissions

• Auth: JWT.
• Guard chain: JwtAuthGuard, RoleGuard.
• Permission: AcademicCalendar_UPDATE.
• Guest support: No.
• Rate limit: None module-specific.
• Idempotency: Not idempotent by design — expectedVersion is required after the first save, so a repeat with a stale version is a 409.

Request

Minimal valid request, first configuration:

{
  "weekendDays": [6],
  "schoolDayCutoffMinute": 1020,
  "expectedVersion": null
}

Full valid request, a later update:

{
  "weekendDays": [5, 6],
  "schoolDayCutoffMinute": 990,
  "expectedVersion": 2
}

Response

SchoolWeekConfigDto with configured: true — see §8.10's "configured" example.

Side Effects

• Database write: school_week_config insert (first save) or version-guarded update.
• configuredByUserId is set from the authenticated caller (@CurrentAdmin()) on every save.
• No cache, job, realtime, notification, or external call.

Error Cases

Edge Cases

• weekendDays: [] is accepted and saved — a seven-day school is a legal, complete configuration.
• Sending expectedVersion: null when a row already exists is refused with the same ATTENDANCE_VERSION_CONFLICT a stale numeric version would produce — the ?? -1 fallback guarantees null can never accidentally match a real version.
• schoolDayCutoffMinute accepts the full 0..1440 range, including 1440 (midnight-exclusive end of day) and 0 (a school with no cutoff grace at all).

Example Requests

curl -X PUT "$API_URL/api/school/week-config" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"weekendDays":[6],"schoolDayCutoffMinute":1020,"expectedVersion":null}'

8.12 GET /api/mobile/calendar

Purpose

The one calendar read every audience shares — pupil, guardian, teacher, and staff alike. Renders one Bikram Sambat month, defaulting to the session containing today and the BS month containing today when no query parameters are supplied. This is the mobile/portal counterpart of §8.3, with a deliberately narrower response shape and no permission check.

Source Evidence

Auth and Permissions

• Auth: JWT.
• Guard chain: JwtAuthGuard, RoleGuard — but no @Permissions() decorator.
• Permission: None. Allowlisted in NO_PERMISSION_ADMIN_HANDLERS under "CalendarPortalController.monthView" (apps/api/src/common/authorization/role.guard.ts:228) so RoleGuard does not treat the missing decorator as a misconfigured admin route.
• Guest support: No — a valid JWT is still required; there is simply no role/permission check beyond it.
• Rate limit: None module-specific.
• Idempotency: N/A (read).

Request

Response

{
  "message": "Calendar fetched.",
  "data": [
    {
      "gregorianDate": "2026-04-15",
      "bsYear": 2083,
      "bsMonth": 1,
      "bsDay": 1,
      "dayOfWeek": 3,
      "classification": "public_holiday",
      "attendanceExpected": false,
      "eventName": "Nepali New Year"
    }
  ]
}

Note the smaller field set relative to the admin day/month responses (§8.3, §8.4): no id, note, source, needsReview, attendanceExists, or version.

Side Effects

None — read-only.

Error Cases

Edge Cases

• Omitting both bsYear and bsMonth resolves "today" through SchoolClockService, in the school's own timezone, and converts to BS via the same wrapper the admin side uses.
• A pupil, parent, teacher, or staff member all receive the identical response shape for the same query — there is no audience-conditional field.
• Requesting a month that is technically covered by the session but was never generated (e.g. the session exists but generate() was never called) returns 409 ACADEMIC_CALENDAR_NOT_GENERATED, not an empty array.

Example Requests

curl -X GET "$API_URL/api/mobile/calendar?bsYear=2083&bsMonth=1" \
  -H "Authorization: Bearer TOKEN"

8.13 GET /api/calendar/today

Purpose

Today's date in Asia/Kathmandu, its Bikram Sambat equivalent, and a Devanagari rendering of the BS date and the weekday. Every audience's page header renders it. It is pure computation: no database, cache, queue, Redis or MongoDB is touched.

Source Evidence

Auth and Permissions

• Auth: JWT.
• Guard chain: JwtAuthGuard, RoleGuard — but no @Permissions() decorator.
• Permission: None. Allowlisted in NO_PERMISSION_ADMIN_HANDLERS under "CalendarTodayController.today". The response holds only today's date in Asia/Kathmandu and its BS equivalent — no user, school or row data — so a session is the whole requirement.
• Guest support: No — a valid JWT is required.
• Rate limit: None module-specific.
• Idempotency: N/A (read).

Request

Response

{
  "message": "Today fetched.",
  "data": {
    "date": "2026-09-30",
    "bs": "2083-06-14",
    "bsYear": 2083,
    "bsMonth": 6,
    "bsDay": 14,
    "dayOfWeek": 3,
    "bsDisplayNp": "आश्विन १४, २०८३",
    "weekdayNp": "बुधबार"
  },
  "errorCode": null
}

Field semantics are in §6.17.

Side Effects

None — read-only. A GET is not recorded by the audit interceptor.

Error Cases

A date outside the converter's range is not an error; see the edge cases.

Edge Cases

• The date is taken in Asia/Kathmandu (UTC+05:45), not in the server's timezone. The day rolls at Nepal midnight, which is 18:15 UTC.
• dayOfWeek is computed from the Nepal date string through UTC arithmetic, so the server's timezone cannot move it. 0 is Sunday.
• When the Nepal date is outside the converter's supported range (BS 2000–2090), the response is still 200. bs, bsYear, bsMonth, bsDay, bsDisplayNp and weekdayNp are all null together; date and dayOfWeek are present.
• A BS day below 10 renders zero-padded in bsDisplayNp (for example आश्विन ०५, २०८३).

Example Requests

curl -X GET "$API_URL/api/calendar/today" \
  -H "Authorization: Bearer TOKEN"

8.14 GET /api/calendar/upcoming

Purpose

The next N days of the school calendar, starting today, with each day's Bikram Sambat date, classification and whether attendance is expected, plus the multi-day events inside the window. Every audience's dashboard renders it.

Source Evidence

Auth and Permissions

• Auth: JWT.
• Guard chain: JwtAuthGuard, RoleGuard — but no @Permissions() decorator.
• Permission: None. Allowlisted in NO_PERMISSION_ADMIN_HANDLERS under "CalendarUpcomingController.upcoming". The response names no person, enumerates its fields and never includes the administrator note, so a session is the whole requirement.
• Guest support: No.
• Idempotency: N/A (read).

Request

Response

{
  "message": "Upcoming calendar days fetched.",
  "data": {
    "today": "2026-10-06",
    "academicSessionName": "2082/83",
    "days": [
      {
        "date": "2026-10-06",
        "dayOfWeek": 2,
        "bsYear": 2083,
        "bsMonth": 6,
        "bsDay": 20,
        "classification": "school_day",
        "isOperatingDay": true,
        "eventName": null
      },
      {
        "date": "2026-10-07",
        "dayOfWeek": 3,
        "bsYear": 2083,
        "bsMonth": 6,
        "bsDay": 21,
        "classification": "public_holiday",
        "isOperatingDay": false,
        "eventName": "Dashain"
      }
    ],
    "events": [
      {
        "name": "Dashain",
        "classification": "public_holiday",
        "startDate": "2026-10-07",
        "endDate": "2026-10-07",
        "startBs": { "year": 2083, "month": 6, "day": 21 },
        "endBs": { "year": 2083, "month": 6, "day": 21 }
      }
    ]
  },
  "errorCode": null
}

The example shows two of the requested days. Field semantics are in §6.18.

How the window is built

• today is the school-local date, not the server's. The window is days consecutive dates from it, enumerated by UTC arithmetic on the date string, so it cannot fail near the edge of the Bikram Sambat range.
• One calendar row is chosen per date from active academic sessions only. When two active sessions hold the same date, the current session's row wins, then the lower session id. Archived (inactive) sessions never contribute.
• A date with no row has classification, isOperatingDay and eventName set to null; its BS fields are converted from the Gregorian date.
• events groups consecutive days that share a classification and an event name. A day is notable when it has an event name, or its classification is neither school_day nor weekend. A day that is not notable, or has no row, ends the current run.

Side Effects

• Database reads: the current session and the calendar rows between the first and last date of the window.
• Cache: reads and writes calendar:upcoming:; see Caching. No writes to the database.

Caching

• Key: calendar:upcoming: with the school-local date and the requested days; the value is the whole response.
• TTL 60 seconds. No calendar write invalidates the key: a holiday create, update or delete, a day correction or a regeneration is visible within 60 seconds.
• The read goes through cacheGetFast: the Redis read races a 250 ms budget, and a timeout, an error or an outage is a miss, so the route reads PostgreSQL. The write is fire-and-forget (cacheSetFast).
• The response is the same for every caller, so one entry serves all audiences.

Error Cases

Edge Cases

• Omitting days returns seven days; days=1 returns only today.
• The response always holds exactly days entries, even when the calendar has not been generated: every day then carries null classification and events is empty.
• A session with no current flag gives academicSessionName: null; calendar rows are still returned for active sessions.

Example Requests

curl -X GET "$API_URL/api/calendar/upcoming?days=14" \
  -H "Authorization: Bearer TOKEN"

9. Flow Diagrams

9.1 Route Ownership

9.2 Request Sequence — Generate

9.3 Error Branch — Holiday Create

9.4 Auth and Permission Flow — Admin vs. Portal

10. Pagination, Sorting, Filtering, and Search

No endpoint in this module supports free-text search — the inherited QueryDto.search field is accepted (it is part of the shared base class) but has no effect on any query built by these services. No relevance scoring exists. Only GET /api/calendar/upcoming is cached; see §11.

11. Caching, Jobs, and External Integrations

13. Mandatory Deep API Documentation Pack

13.1 Route-by-Route Completeness Matrix

13.2 Request/Response Exhaustiveness

Every applicable example type is present in §8 per endpoint: minimal/full request bodies (holiday create, week-config update), public/guest behavior (not applicable — every route requires a JWT), authenticated and admin requests (all endpoints), success responses with full envelopes, empty-list responses (§8.2, §8.6, §8.3), validation errors, domain errors, and version-conflict errors. 401/403 are not shown as JSON bodies because they are produced by the shared guard stack, not by any service in this module, and their shape is documented once in the platform's own auth documentation rather than duplicated per endpoint here.

13.3 API Diagram Pack

See §9 for the route-ownership graph, the generate sequence, the holiday-create error decision tree, and the admin-vs-portal auth flow. A cache-flow diagram is omitted — no route in this module reads or writes a cache. An async/job-flow diagram is omitted for the same reason regarding BullMQ. A realtime/event-flow diagram is omitted — no event is ever emitted.

13.4 Consumer Integration Notes

13.5 API Tradeoffs and Rationale

13.6 API Change Impact

14. Zero-Omission API Checklist

• Every controller route is documented (§4, §8).
• Every parent route prefix and runtime URL is documented, including the mobile-mounting distinction (§4, §9.1).
• Every DTO field, nested field, enum, default, transform, and validator is documented (§6, §7).
• Every response field, nullable field, generated field, and omitted raw entity field is documented, including the portal DTO's deliberate omissions (§6.15).
• Every auth, guard, permission, role, and the one no-permission branch is documented (§5, §9.4).
• Every success, validation, auth, permission, not-found, conflict, and server-error branch is documented (§8, §13.1).
• Every database read/write is documented; no cache, queue, realtime, notification, or external call exists to document (§11).
• Every route has examples for minimal request, full request (where applicable), success response, and representative failures (§8).
• Every endpoint family has route, sequence, activity, and error diagrams (§9).
• Every tradeoff and compatibility risk is documented (§13.5, §13.6).
• The API doc links to backend and features/flows.

15. Integration Checklist

• Every route from controllers is documented.
• Every DTO field is documented.
• Every enum value is documented.
• Every response envelope is documented, including the holiday list's top-level (not double-nested) pagination fields.
• Every error code is documented.
• Every auth guard and permission is documented, including the one deliberately permission-less route.
• The only cache key is calendar:upcoming:; no queue job or realtime event exists in this module.
• Every diagram matches the current code.
• The API doc links to backend and features/flows.

See Also

• Backend doc: /docs/developer/academic-calendar/backend
• Features and flows doc: /docs/developer/academic-calendar/feature