Timetable - API Reference

Audience: Frontend engineers, mobile engineers, backend engineers, QA, and API consumers. Scope: Admin routes for the Timeslot Manager and Timetable Builder, and the mobile "my schedule" and "today" read routes owned by the teacher, student, and guardian portals.

1. Documentation Evidence

2. Module Summary

3. Concepts and Terminology

4. API Surface Map

Route prefixes for the two admin controllers come from their own @Controller() decorators (classes/:classPublicId/timeslots, classes/:classPublicId/timetable); TimetableModule adds no further prefix. The four portal controllers share their existing mobile-module @Controller("teacher"|"student"|"guardian") prefixes rather than being declared inside TimetableModule — a class declared in two modules would register its routes twice.

5. Auth, Identity, and Permissions

Schedule is the one permission module granted to staff, teacher, student, and guardian roles — the guardian role's first grant of any kind, made safe here because the guardian route takes an explicit ward parameter and asserts ownership of it, unlike an earlier withdrawn attempt to route guardians through a pupil-audience endpoint.

6. DTO and Model Reference

6.1 TimeslotDto (response)

6.2 ClassTimeslotsDto (response, GET .../timeslots)

There is no aggregate/summary endpoint; the admin panel derives its per-day tab counts from this one response.

6.3 CreateTimeslotDto (request, POST .../timeslots)

6.4 UpdateTimeslotDto (request, PATCH .../timeslots/:timeslotId)

Every field is optional except version, which is required.

A silently optional concurrency token is a token that is silently not checked, so version is required here even though every other field is optional; omitting it is a 400 from the global validation pipe.

6.5 CopyTimeslotsDto (request, POST .../timeslots/copy)

fromClassPublicId defaulting to the target class is what makes copying between classes (a session rollover from one year's class to the next) possible in the same endpoint used for same-class day duplication.

6.6 TimetableEntryDto (response)

6.7 StaleReferenceDto (response, nested in ClassTimetableDto)

6.8 ClassTimetableDto (response, GET .../timetable)

6.9 ReadTimetableQueryDto (query, GET .../timetable)

6.10 PutTimetableEntryDto (request, PUT .../draft/entries/:timeslotId)

One body serves both a drag-and-drop (sending classSubjectId alone) and the follow-up lesson-details dialog (sending the rest). A field omitted (undefined) is left untouched on an existing row; only an explicit value or explicit null changes it.

6.11 CreateDraftDto (request, POST .../timetable/draft)

6.12 SkippedEntryDto (response, nested in CreateDraftResultDto)

6.13 CreateDraftResultDto (response, POST .../timetable/draft)

6.14 TimetableVersionSummaryDto (response, GET .../timetable/versions)

The live version — the currently published header, not yet archived — is always first when present, ahead of every archived row.

6.15 ArchivedTimetableDto / ArchivedTimetableEntryDto (response, GET .../timetable/versions/:versionNo)

Enumerated from the stored snapshot, never the raw jsonb — this route is Timetables_READ-gated so notes is included here, but internal ids (timeslotId, classSubjectId, teacherId) that exist only to make restore possible are not part of this read shape. versionNo may name either an archived version or the currently live one; the live version's entries are read fresh and mapped through the same projection, so the shape returned is identical either way.

ArchivedTimetableEntryDto: dayOfWeek, startMinute, endMinute (all number, required), slotType (string enum, required), label (string \| null), subjectName (string \| null), teacherName (string \| null), roomName (string \| null), notes (string \| null).

6.16 SlotAvailabilityDto (response, GET .../timetable/slots/:timeslotId/availability)

6.17 ConflictDetailsDto / ConflictsWithDto (response, embedded in 409 error bodies)

The body both TIMETABLE_TEACHER_CONFLICT and TIMETABLE_ROOM_CONFLICT carry, in the details field of the error response. Obtained by a second query run inside the same transaction, before rollback, so the conflicting row is provably not yet moved.

ConflictDetailsDto: dayOfWeek, startMinute, endMinute (number, required), timeslotId (string, required), conflictsWith (ConflictsWithDto, required).

ConflictsWithDto: classPublicId (string), className (string), subjectName (string), teacherId (string \| null), teacherName (string \| null), roomId (number \| null), roomName (string \| null).

6.18 Portal DTOs

PortalScheduleEntryDto (response, student/guardian schedule entries):

TeacherScheduleEntryDto extends PortalScheduleEntryDto with four additional fields:

PortalScheduleDto / TeacherScheduleDto (the envelopes):

PupilTodayScheduleDto (response of both schedule/today routes; mobile/shared/portal-today.dto.ts):

PupilTodayCalendarDto:

PupilTodayPeriodDto:

Fields deliberately absent from every portal DTO, and why: notes (operator free text — "Cover for Mrs Sharma, medical leave" is a staff medical disclosure with a column name that gives no hint of that), teacherId, roomId, timetableId, timeslotId, version, publishedByUserId (internal identity/concurrency plumbing a read-only screen has no use for), and any teacher field beyond a name (no employeeCode, no employmentStatus — the field-level control that keeps this endpoint from telling every parent in a class whether a teacher has been terminated).

7. Enum Reference

8. Endpoint Reference

8.1 GET /api/classes/:classPublicId/timeslots

Purpose

Returns every day of the week, 0–6, in one response — including days with no slots at all. There is no aggregate/summary endpoint; the admin panel derives its per-day tab counts directly from this response's days array.

Source Evidence

Auth and Permissions

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

Request

Response

{
  "success": true,
  "message": "Timeslots fetched.",
  "data": {
    "classPublicId": "018f2f3e-...-...",
    "days": [
      { "dayOfWeek": 0, "slots": [] },
      {
        "dayOfWeek": 1,
        "slots": [
          {
            "id": "018f2f40-...",
            "dayOfWeek": 1,
            "startMinute": 480,
            "endMinute": 540,
            "slotType": "period",
            "label": null,
            "version": 0
          }
        ]
      }
    ]
  }
}

Side Effects

None — read-only.

Error Cases

Edge Cases

• A class with no timeslots at all returns all 7 days with empty slots arrays — never a 404.
• Slots are ordered dayOfWeek then startMinute within each day.

Example Requests

curl -X GET "$API_URL/api/classes/018f2f3e-.../timeslots" \
  -H "Authorization: Bearer TOKEN"

8.2 POST /api/classes/:classPublicId/timeslots

Purpose

Creates one timeslot for a class. Used by the Timeslot Manager to build up a class's daily structure one period, break, or lunch at a time.

Source Evidence

Auth and Permissions

• Auth: JWT.
• Guard chain: JwtAuthGuard, RoleGuard.
• Permission: Timetables_CREATE.
• Guest support: No.
• Rate limit: None module-specific.
• Idempotency: Not idempotent — repeated calls create repeated rows unless they would overlap.

Request

{ "dayOfWeek": 1, "startMinute": 480, "endMinute": 540, "slotType": "period", "label": null }

Response

201, TimeslotDto (§6.1), wrapped in the standard envelope with message "Timeslot created.".

Side Effects

• Database write: one class_timeslots insert.
• No cache, queue, realtime, notification, or external call.

Error Cases

Edge Cases

• label omitted or null is valid; a leading/trailing-space label is trimmed server-side before validation against the format CHECK, so a pasted " Tiffin " succeeds as "Tiffin".
• A value for startMinute/endMinute larger than a Postgres smallint (32767) raises 22003 at the database level before any CHECK runs — this is not translated to a module error code and surfaces as an unmapped 500 if the DTO's own @Max(1440) bound is somehow bypassed; the DTO bound is the actual first line of defense.

Example Requests

curl -X POST "$API_URL/api/classes/018f2f3e-.../timeslots" \
  -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
  -d '{"dayOfWeek":1,"startMinute":480,"endMinute":540,"slotType":"period"}'

8.3 PATCH /api/classes/:classPublicId/timeslots/:timeslotId

Purpose

Updates a timeslot's day, time range, type, or label, with optimistic concurrency. Because moving or retyping a slot cascades onto every class_timetable_entries row that occupies it — including published ones — this route requires an additional permission beyond the ordinary update code.

Source Evidence

Auth and Permissions

• Auth: JWT.
• Guard chain: JwtAuthGuard, RoleGuard.
• Permission: Timetables_UPDATE and TimetablePublish_UPDATE (both required).
• Guest support: No.
• Rate limit: None module-specific.
• Idempotency: Effectively idempotent for the same version (a stale version fails on retry).

Request

Minimal valid request (no field changes, only advancing the version by touching one field or resending it):

{ "version": 3 }

Full valid request:

{ "dayOfWeek": 2, "startMinute": 500, "endMinute": 560, "slotType": "break", "label": null, "version": 3 }

Response

200, TimeslotDto, message "Timeslot updated.".

Side Effects

• Database write: class_timeslots update.
• Cascading write: if dayOfWeek/startMinute/endMinute/slotType change, every class_timetable_entries row referencing this slot is rewritten via ON UPDATE cascade, including published rows.

Error Cases

Edge Cases

• Omitting every field but version is valid: the service self-assigns the existing value of one column so the UPDATE statement is non-trivial and the bump_row_version trigger still fires, advancing version.
• label: null explicitly clears an existing label (distinct from omitting label, which leaves it unchanged).

Example Requests

curl -X PATCH "$API_URL/api/classes/018f2f3e-.../timeslots/018f2f40-..." \
  -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
  -d '{"startMinute":500,"endMinute":560,"version":3}'

8.4 DELETE /api/classes/:classPublicId/timeslots/:timeslotId

Purpose

Hard-deletes a timeslot. Refused while any lesson still occupies it.

Source Evidence

Auth and Permissions

• Permission: Timetables_DELETE and TimetablePublish_UPDATE.
• Guest support: No.
• Idempotency: Not idempotent — a second call 404s.

Request

Response

200, data: null, message "Timeslot deleted.".

Side Effects

Database write: class_timeslots delete, refused by ON DELETE restrict if occupied.

Error Cases

Edge Cases

Deleting a slot that never existed and one that is currently occupied both fail, with different codes — the caller cannot distinguish "wrong id" from "occupied" without reading the error code.

Example Requests

curl -X DELETE "$API_URL/api/classes/018f2f3e-.../timeslots/018f2f40-..." \
  -H "Authorization: Bearer TOKEN"

8.5 POST /api/classes/:classPublicId/timeslots/copy

Purpose

Clones one day's timeslots onto one or more other days in a single transaction — the fast path for building a school's typical five- or six-day-identical week, and, via fromClassPublicId, for rolling a schedule forward into a new class at the start of a session.

Source Evidence

Auth and Permissions

• Permission: Timetables_CREATE, Timetables_DELETE, and TimetablePublish_UPDATE (all three required — copy can both create and, with replace: true, destroy existing timeslots).
• Guest support: No.
• Idempotency: Not idempotent with replace: false (re-running duplicates or overlaps); idempotent in effect with replace: true against an unchanged source day.

Request

{ "fromDayOfWeek": 1, "toDaysOfWeek": [2, 3, 4, 5], "replace": true, "fromClassPublicId": null }

See §6.5 for the full field table.

Response

200, ClassTimeslotsDto (the full 7-day listing after the copy), message "Timeslots copied.".

Side Effects

• Database writes: optional bulk delete of the target days' slots (replace: true), then bulk insert of the copied slots — all in one transaction.
• No cache, queue, or realtime side effect.

Error Cases

Edge Cases

• toDaysOfWeek is deduplicated server-side ([1, 1, 2] behaves as [1, 2]) so a client sending duplicates does not attempt the same insert twice inside one transaction.
• The entire operation is one transaction: a failure on the third of four target days rolls back all four, never leaving some days copied and others not.
• fromClassPublicId omitted defaults to the target class itself.

Example Requests

curl -X POST "$API_URL/api/classes/018f2f3e-.../timeslots/copy" \
  -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
  -d '{"fromDayOfWeek":1,"toDaysOfWeek":[2,3,4,5],"replace":true}'

8.6 GET /api/classes/:classPublicId/timetable

Purpose

Reads the live grid. Defaults to the draft if one exists, else the published version, else an empty grid — a brand-new class is not an error. Pass ?status=draft or ?status=published to require that exact version.

Source Evidence

Auth and Permissions

• Permission: Timetables_READ.
• Guest support: No.
• Idempotency: N/A (read).

Request

Response

{
  "success": true,
  "message": "Timetable fetched.",
  "data": {
    "classPublicId": "018f2f3e-...",
    "status": "draft",
    "versionNo": 5,
    "publishedAt": null,
    "hasDraft": true,
    "hasPublished": true,
    "slots": [ /* TimeslotDto[] */ ],
    "entries": [ /* TimetableEntryDto[] */ ],
    "staleReferences": []
  }
}

Side Effects

None — read-only.

Error Cases

An explicit ?status= naming a version that does not exist is not an error — see the next row.

Edge Cases

• No draft, no published, no explicit status: returns status: "draft", versionNo: null, hasDraft: false, hasPublished: false, empty slots/entries/staleReferences. An empty class is a normal state, not a 404.
• Explicit ?status=published on a class with no published version: same empty-grid shape, status echoed back as "published" — deliberately not a 404 (an earlier design that did 404 here produced a permanent error-retry loop in the admin panel for the ordinary case of an unpublished class).
• staleReferences is populated only for status === "published"; a draft response's staleReferences is always [] even if the draft's own references have decayed (that check runs only at publish time for drafts).

Example Requests

curl -X GET "$API_URL/api/classes/018f2f3e-.../timetable?status=published" \
  -H "Authorization: Bearer TOKEN"

8.7 GET /api/classes/:classPublicId/timetable/versions

Purpose

Lists every version of a class's timetable for a version-history screen: the currently live version first (if one exists), then every archived version, newest first.

Source Evidence

Auth and Permissions

• Permission: Timetables_READ.

Response

200, TimetableVersionSummaryDto[] (§6.14), message "Versions fetched.". An empty array is normal for a class that has never published. The read runs inside one read-only REPEATABLE READ transaction over both tables, so a concurrent publish or unpublish cannot duplicate, drop, or hide a version between the live lookup and the archive lookup.

Error Cases

Example Requests

curl -X GET "$API_URL/api/classes/018f2f3e-.../timetable/versions" -H "Authorization: Bearer TOKEN"

8.8 GET /api/classes/:classPublicId/timetable/versions/:versionNo

Purpose

Reads one version in full, for a read-only "view this version" screen — the version named by versionNo may be archived or the one currently live.

Source Evidence

Auth and Permissions

• Permission: Timetables_READ.

Response

200, ArchivedTimetableDto (§6.15), message "Version fetched.". An archived match is checked first; if none exists, versionNo is matched against the currently PUBLISHED header on this class — all three of classId, status = 'published' and versionNo must hold, or the request 404s. That predicate is deliberate: a versionNo matching neither branch always 404s, even when the class has a live version under a different number — the screen titles itself from the requested versionNo, so silently substituting the live week would show it under the wrong heading.

Error Cases

Example Requests

curl -X GET "$API_URL/api/classes/018f2f3e-.../timetable/versions/4" -H "Authorization: Bearer TOKEN"

8.9 POST /api/classes/:classPublicId/timetable/draft

Purpose

Creates a new draft. With no body, forks the currently-published version (or creates an empty draft if none exists). With fromVersionNo, rebuilds the draft from that archived version instead — resolving each entry against the current schema state, and skipping (never silently dropping, never failing the whole call) any entry whose referenced timeslot or subject assignment no longer matches.

Source Evidence

Auth and Permissions

• Permission: Timetables_UPDATE.
• Idempotency: Not idempotent — a second call while a draft already exists is refused.

Request

{ "fromVersionNo": 4 }

Or an empty body {} to fork the published version.

Response

201, CreateDraftResultDto (§6.13), message "Draft created.".

Side Effects

• Database writes: one class_timetables insert (status: "draft"), plus a bulk class_timetable_entries insert for every entry that resolved.
• Locks: both of this class's headers, FOR UPDATE, ORDER BY id — the same order publish locks in, so the two operations cannot deadlock against each other.

Error Cases

Edge Cases

• Restoring from an archive whose referenced timeslot has since moved, or whose subject is no longer assigned to the class, skips that entry with a specific reason in the response's skipped[] — the call still succeeds.
• Forking a published version with zero entries is valid — the new draft simply has zero entries (publishing it later will then fail with TIMETABLE_DRAFT_EMPTY).

Example Requests

curl -X POST "$API_URL/api/classes/018f2f3e-.../timetable/draft" \
  -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" -d '{}'

8.10 DELETE /api/classes/:classPublicId/timetable/draft

Purpose

Discards the current draft, discarding all its unpublished edits.

Source Evidence

Auth and Permissions

• Permission: Timetables_DELETE.
• Idempotency: Not idempotent — a second call 409s.

Response

200, data: null, message "Draft discarded.".

Side Effects

Database write: class_timetables delete (status = 'draft'); every class_timetable_entries row of that header is deleted by ON DELETE cascade.

Error Cases

Example Requests

curl -X DELETE "$API_URL/api/classes/018f2f3e-.../timetable/draft" -H "Authorization: Bearer TOKEN"

8.11 PUT /api/classes/:classPublicId/timetable/draft/entries/:timeslotId

Purpose

Places or updates a lesson in one timeslot of the current draft. An upsert — safe to retry after a timeout — that also serves as the drag-and-drop endpoint (send classSubjectId alone) and the lesson-details dialog (send the rest alongside it).

Source Evidence

Auth and Permissions

• Permission: Timetables_UPDATE.
• Idempotency: Yes, by design — safe to retry.

Request

Minimal (drop-only):

{ "classSubjectId": "018f2f41-..." }

Full:

{
  "classSubjectId": "018f2f41-...",
  "teacherId": "018f2f42-...",
  "roomId": 12,
  "notes": "Bring lab coats",
  "version": 2
}

Response

200, TimetableEntryDto (§6.6), message "Entry saved.".

Side Effects

• Database write: class_timetable_entries INSERT ... ON CONFLICT (timetable_id, timeslot_id) DO UPDATE.
• Read-only conflict lookup (findConflict) before the write, excluding the class being edited from the search.

Error Cases

Edge Cases

• Sending only classSubjectId never clears an existing teacherId/roomId/notes on that slot — only fields present in the body are overwritten.
• The conflict check excludes the class currently being edited: publishing deletes that class's own published rows before promoting, so its own published entries can never be the thing a draft edit collides with.
• version omitted entirely (a fresh placement) is always accepted; supplied and stale, it is rejected even though the write would otherwise have succeeded.

Example Requests

curl -X PUT "$API_URL/api/classes/018f2f3e-.../timetable/draft/entries/018f2f40-..." \
  -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
  -d '{"classSubjectId":"018f2f41-..."}'

8.12 DELETE /api/classes/:classPublicId/timetable/draft/entries/:timeslotId

Purpose

Clears a slot in the draft. Idempotent — clearing an already-empty slot is not an error.

Source Evidence

Auth and Permissions

• Permission: Timetables_UPDATE.
• Idempotency: Yes.

Response

200, data: null, message "Entry cleared.".

Error Cases

Example Requests

curl -X DELETE "$API_URL/api/classes/018f2f3e-.../timetable/draft/entries/018f2f40-..." \
  -H "Authorization: Bearer TOKEN"

8.13 GET /api/classes/:classPublicId/timetable/slots/:timeslotId/availability

Purpose

Returns which teachers and rooms are free for a given slot's day and minute range — the complement of the conflict check run on every drop, surfaced proactively so the builder UI can grey out or highlight options before the operator even attempts a placement.

Source Evidence

Auth and Permissions

• Permission: Timetables_READ.

Response

200, SlotAvailabilityDto (§6.16), message "Availability fetched.".

Error Cases

Edge Cases

Computed among published entries only, scoped to the class's academic session — a draft's own conflicting placements never make a teacher/room appear unavailable here.

Example Requests

curl -X GET "$API_URL/api/classes/018f2f3e-.../timetable/slots/018f2f40-.../availability" \
  -H "Authorization: Bearer TOKEN"

8.14 POST /api/classes/:classPublicId/timetable/publish

Purpose

Publishes the current draft: archives the superseded published version (if any), then promotes the draft. This is the action that makes a schedule visible to every pupil and parent in the class.

Source Evidence

Auth and Permissions

• Permission: TimetablePublish_UPDATE (superadmin-only in practice — see §5).
• Idempotency: Idempotent in the useful sense — retried with no draft but a published version already present, returns that version rather than failing.

Request

No body. HttpCode(200) overrides Nest's default 201 for a POST.

Response

200, ClassTimetableDto (§6.8, status: "published"), message "Timetable published.".

Side Effects

• Database writes: optional archive insert + published-header delete (if a published version existed), then the draft header's status update to "published".
• Cascading write: the header's status change cascades to every entry via the composite header FK, which is the exact moment the two EXCLUDE constraints are checked.
• No cache, queue, or realtime side effect.

Error Cases

Edge Cases

• Retrying a publish that already succeeded (no draft left, published version present) returns that published version with a 200, not an error.
• A conflict found during promotion is investigated before the surrounding transaction rolls back, so the named conflictsWith row is guaranteed still accurate at the moment it is reported.

Example Requests

curl -X POST "$API_URL/api/classes/018f2f3e-.../timetable/publish" -H "Authorization: Bearer TOKEN"

8.15 POST /api/classes/:classPublicId/timetable/unpublish

Purpose

Removes the currently published timetable after archiving it, returning the class to having no live schedule.

Source Evidence

Auth and Permissions

• Permission: TimetablePublish_UPDATE.
• Idempotency: Not idempotent — a second call 404s.

Response

200, data: null, message "Timetable unpublished.".

Side Effects

Database writes: archive insert, then delete of the published header (entries cascade away).

Error Cases

Example Requests

curl -X POST "$API_URL/api/classes/018f2f3e-.../timetable/unpublish" -H "Authorization: Bearer TOKEN"

8.16 GET /api/mobile/teacher/schedule

Purpose

Returns the calling teacher's own published weekly teaching schedule for the current academic session.

Source Evidence

Auth and Permissions

• Auth: JWT.
• Guard chain: JwtAuthGuard, RoleGuard.
• Permission: None — audience asserted by assertTeacherStaffRow, which resolves and returns the caller's own live staff.id (never a boolean), because classes.class_teacher_id and class_timetable_entries.teacher_id are both nullable and a predicate built from an undefined local would otherwise match the whole school.
• Guest support: No.

Response

200, TeacherScheduleDto, message "Schedule fetched.".

{
  "success": true,
  "message": "Schedule fetched.",
  "data": {
    "academicSessionName": "2026-27",
    "entries": [
      {
        "dayOfWeek": 1,
        "startMinute": 480,
        "endMinute": 540,
        "slotType": "period",
        "label": null,
        "subjectName": "Mathematics",
        "subjectCode": "MATH",
        "teacherName": "Ram Sharma",
        "roomName": "Room 204",
        "className": "Grade 5 A",
        "classPublicId": "0198f2c4-6b1e-7c3a-9d52-3a4f1b8e7a10",
        "subjectId": "0198f2c4-6b1e-7c3a-9d52-3a4f1b8e7a11",
        "classSubjectId": "0198f2c4-6b1e-7c3a-9d52-3a4f1b8e7a12"
      }
    ]
  }
}

Side Effects

None — read-only.

Error Cases

No module-specific error code is raised by this route; an audience-assertion failure returns the shared portal 403.

Edge Cases

• No current academic session: returns academicSessionName: null, entries: [] — not an error.
• A teacher with no assigned periods returns entries: [].
• Entries include className because one teacher's week spans multiple classes.
• Every entry is a published lesson, so classPublicId, subjectId and classSubjectId are always present; each is a public uuid, never an integer key.

Example Requests

curl -X GET "$API_URL/api/mobile/teacher/schedule" -H "Authorization: Bearer TOKEN"

8.17 GET /api/mobile/student/schedule

Purpose

Returns the calling pupil's own class's published weekly schedule for the current academic session.

Source Evidence

Auth and Permissions

• Permission: None — assertPortalAudience(actor, "student") only confirms the session is a pupil session, never which pupil; the row scope is the WHERE clause built from a live enrollment (students.deleted_at IS NULL, students.record_status = 'active', studentClassEnrollments.status = 'active', scoped to the current academic session).
• Guest support: No.

Response

200, PortalScheduleDto, message "Schedule fetched." — same entry shape as the teacher route minus className (every row already belongs to the pupil's one enrolled class).

Error Cases

None module-specific.

Edge Cases

• No current session, or no live enrollment: entries: [].
• A pupil holding an unclosed prior-year enrollment alongside the current year's is filtered to the current session only — without that filter this route would interleave two classes' weeks.

Example Requests

curl -X GET "$API_URL/api/mobile/student/schedule" -H "Authorization: Bearer TOKEN"

8.18 GET /api/mobile/guardian/children/:id/schedule

Purpose

Returns one of the calling guardian's children's published weekly class schedule for the current academic session.

Source Evidence

Auth and Permissions

• Permission: None — assertPortalAudience(actor, "guardian") confirms audience only; resolveOwnChildId is the actual authorization decision and runs before any schedule row is read.
• Guest support: No.

Request

Response

200, PortalScheduleDto.

Error Cases

Edge Cases

• The ward check runs first and can 404 before any timetable row is touched; only after it succeeds can an empty week ever be returned. Reversing that order would not itself leak data (an empty week from a foreign child id is indistinguishable from an own child with no timetable), but it would mean authorization ran after the query rather than before it.
• No current session, or the child has no live enrollment: entries: [], 200.

Example Requests

curl -X GET "$API_URL/api/mobile/guardian/children/018f2f43-.../schedule" -H "Authorization: Bearer TOKEN"

8.19 GET /api/mobile/student/schedule/today

Purpose

The periods of the caller's own class for today, each marked finished, in progress or upcoming against the server clock in the school's timezone, with the next moment the day changes. Feeds the pupil dashboard's "today" card.

Source Evidence

Auth and Permissions

• Guard chain: JwtAuthGuard, RoleGuard.
• Permission: None — assertPortalAudience(actor, "student"). The handler key StudentSchedulePortalController.myToday is in NO_PERMISSION_ADMIN_HANDLERS.
• The route takes no id. The pupil is resolved from the token (students.user_id = actor.id, deleted_at only).

Request

No params, query or body.

Response

{
  "message": "Schedule fetched.",
  "data": {
    "serverTime": "2026-10-06T04:30:12.000Z",
    "timezone": "Asia/Kathmandu",
    "date": "2026-10-06",
    "bsDate": { "year": 2083, "month": 6, "day": 20 },
    "dayOfWeek": 2,
    "academicSessionName": "2082/83",
    "calendar": {
      "status": "operating",
      "classification": "school_day",
      "eventName": null,
      "isOperatingDay": true
    },
    "periods": [
      {
        "id": "540-585-0",
        "state": "finished",
        "startMinute": 540,
        "endMinute": 585,
        "startsAt": "2026-10-06T03:15:00.000Z",
        "endsAt": "2026-10-06T04:00:00.000Z",
        "slotType": "period",
        "label": null,
        "subjectName": "Mathematics",
        "subjectCode": "MATH",
        "teacherName": "Ram Sharma",
        "roomName": "Room 204"
      }
    ],
    "currentPeriodId": null,
    "nextPeriodId": null,
    "nextTransitionAt": null,
    "summary": { "total": 1, "finished": 1, "remaining": 0 }
  },
  "errorCode": null
}

Fields are described under Portal DTOs in §6.18.

Calendar status

calendar.status is decided in a fixed order and the first match wins:

Every status other than operating returns an empty periods list and a zero summary. An operating day for a class with no published slots on this weekday also returns an empty list.

Side Effects

• Database reads: the school clock, the current session, the calendar day, the pupil's active enrolment, and the class's published timetable entries merged with its breaks, lunches and activities.
• Cache: the clock-independent base is cached for 60 seconds; see Caching below. No writes.

Caching

• Key: portal:today: with the pupil's student id and the school-local date. The cached value is the session name, the calendar block and the day's slot rows. Period states, serverTime and nextTransitionAt are recomputed on every request from the cached rows, so they are never stale.
• TTL 60 seconds. Nothing invalidates the key: a timetable publish or unpublish, a calendar edit, an enrolment change or a pupil status change 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 treated as a miss, so the route falls back to the database. The write is fire-and-forget (cacheSetFast).
• The key is reachable only after identity is resolved, so the pupil route and the guardian route share one entry per pupil and day.

Error Cases

Edge Cases

• An inactive or deleted-profile pupil who still holds a students row passes the identity check and receives 200 with calendar.status = "no_class" on an operating day.
• Slot instants are built from the school-local date and minute, not from host-local time, so the response does not depend on the server's timezone.
• currentPeriodId and nextPeriodId refer to any slot type, including breaks; summary counts only period slots.
• bsDate is null when the date is outside the converter's range; the response is still 200.

Example Requests

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

8.20 GET /api/mobile/guardian/children/:id/schedule/today

Purpose

One ward's periods for today, with the same payload as §8.19.

Source Evidence

Auth and Permissions

• Guard chain: JwtAuthGuard, RoleGuard.
• Permission: None — assertPortalAudience(actor, "guardian"), then resolveOwnChildId as the authorization decision. The handler key GuardianSchedulePortalController.childToday is in NO_PERMISSION_ADMIN_HANDLERS.
• The ward check runs before the cache or any schedule row is read.

Request

Params: id — the child's student id (uuid; a non-UUID value is a 400 from ParseUUIDPipe). No query or body.

Response

200, PupilTodayScheduleDto — identical to §8.19, with message: "Schedule fetched.". Calendar status, caching and edge cases are those of §8.19.

Error Cases

Example Requests

curl -X GET "$API_URL/api/mobile/guardian/children/018f2f43-.../schedule/today" \
  -H "Authorization: Bearer TOKEN"

8.21 GET /api/mobile/teacher/schedule/today

Purpose

The caller's own periods for today, each marked finished, in progress or upcoming against the server clock in the school's timezone, with the next moment the day changes. Feeds the teacher dashboard's "today" card.

Source Evidence

Auth and Permissions

• Guard chain: JwtAuthGuard, RoleGuard.
• Permission: None — assertTeacherStaffRow requires the active role named teacher and resolves the caller's live staff row. The handler key TeacherTodayPortalController.getToday is in NO_PERMISSION_ADMIN_HANDLERS.
• The route takes no id; the teacher is resolved from the token.

Request

No query, params or body.

Response

200, TeacherTodayScheduleDto, message: "Today's schedule fetched.": serverTime, timezone, date, bsDate, dayOfWeek, calendar (classification, eventName, isOperatingDay), periods, currentPeriodId, nextPeriodId, nextTransitionAt, summary (total, finished, remaining). Each period carries kind (class, exam or exam_invigilation), state (finished, in_progress or upcoming), start and end as minutes and instants, className, subjectName, room, and the public uuids classPublicId, subjectId and classSubjectId (always present, for every kind). Periods are ordered by start time; finished periods are kept.

The periods come from three sources that never suppress one another: the caller's published timetable entries for today, exam routine entries for class-subjects the caller currently teaches, and exam invigilation duties. Exam duties are returned on a non-operating day; isOperatingDay is informational. An exam_invigilation period names the class being invigilated, which the caller may neither teach nor be class teacher of; opening that class's roster through GET /api/mobile/teacher/classes/:publicId/roster then answers 404, so a client must not assume every period's classPublicId is openable.

Error Cases

Example Requests

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

9. Flow Diagrams

9.1 Route Ownership

9.2 Request Sequence — Entry Upsert

9.3 Error Branch — putEntry

9.4 Auth and Permission Flow — Admin vs. Portal

10. Pagination, Sorting, Filtering, and Search

No endpoint in this module paginates. GET .../timeslots always returns all 7 days; GET .../timetable always returns the full grid for one version; GET .../timetable/versions returns the live version (if any) plus every archived version for the class (bounded naturally by how many times the class has published/unpublished); the weekly portal routes return one week's entries with no upper bound beyond what a week can hold, and the schedule/today routes return one day's. There is no page/pageSize/cursor parameter anywhere in this module, no sort parameter (ordering is always dayOfWeek then startMinute, which is total because overlapping rows are unrepresentable), and no search/filter parameter.

11. Caching, Jobs, and External Integrations

13. Mandatory Deep API Documentation Pack

13.1 Route-by-Route Completeness Matrix

13.2 Request/Response Exhaustiveness

Covered per-endpoint in §8: every mutation route includes a minimal and full request example where applicable, every route documents its success envelope, empty-list/empty-grid behavior is documented for the list-shaped and grid-shaped reads, and every validation, domain, and auth/permission error is enumerated per endpoint with its exact code and condition.

13.3 API Diagram Pack

See §9 for the route-ownership graph, the entry-upsert sequence diagram, the putEntry error decision tree, and the auth/permission flow. A cache-flow diagram and an async/job-flow diagram are omitted deliberately — neither a cache nor a queue exists anywhere in this module (§11).

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 (18 routes across 5 controllers).
• Every parent route prefix and runtime URL is documented.
• Every DTO field, nested field, enum, default, and validator is documented.
• Every response field, nullable field, and generated field is documented; portal DTOs' deliberately-omitted fields are documented and why.
• Every auth, guard, permission, and audience-assertion branch is documented.
• Every success, validation, auth, permission, not-found, conflict, and server-error branch is documented.
• Every database read/write and cascade is documented; cache/queue/realtime/notification/audit are documented as absent where absent.
• Every route has examples for minimal and/or full requests, success responses, and representative failures.
• Route ownership, sequence, error-decision, and auth-flow diagrams are included.
• Every tradeoff and compatibility risk is documented.
• This 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.
• Every error code is documented.
• Every auth guard and permission is documented.
• Cache/queue/realtime/external calls are documented as absent.
• Every diagram matches the current code.
• This doc links to backend and features/flows.

See Also

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