01 — Product Overview (Timetable Module)

• 1. Purpose
• 2. Module boundary
• 3. Entry lifecycle (end-to-end)
• 4. Conflict detection — the one real business rule
• 5. Permissions reality
• 6. Events & side-effects
• 7. Dependencies
• 8. Business goals
• 9. Success metrics
• 10. Edge cases (derived)
• 11. Assumptions (module)
• 12. Open questions (module-level)

StudyLyon — multi-tenant ERP / School Management API. This package designs the Timetable module client (Flutter, forward-looking spec) against the implemented NestJS backend. All endpoints, DTO fields, schemas, events, and business rules are derived directly from src/modules/timetable/**, src/modules/academics/** (class/subject references), src/modules/teachers/**, src/modules/rooms/**, src/modules/rbac/**, and docs/IMPLEMENTATION_PLAN.md. No feature is invented; gaps are flagged and marked (planned) / (proposed) / (forward-looking).

1. Purpose

Timetable is the scheduling domain: the weekly grid of teaching slots — one timetable_entries document per (class, subject, teacher, day, time range), optionally pinned to a room, all scoped to one academic year. It answers "what happens where and with whom, on which day and at what time" for classes, teachers, and rooms.

2. Module boundary

A Class may carry its own default roomId string (class.schema.ts:30-31) — a separate field from the timetable entry's roomId ObjectId; the client must not treat them as the same source of truth.

3. Entry lifecycle (end-to-end)

Catalog ready (classes, subjects, teachers, rooms, academic years exist)
   → Entry created   POST /timetable          [conflict check → 409]
      → TimetableEntryCreated event emitted (no queue routing found — gap, see §6)
      → Read back     GET /timetable?classId= | GET /timetable?teacherId=
   → Edit / Delete    — **no endpoints implemented** (planned)

Deletion semantics today: none — there is no DELETE /timetable/:id. The schema extends BaseSchema (soft-delete columns exist) but no route, service method, or repository call uses them for timetable. Any "remove slot" UI is (planned).

4. Conflict detection — the one real business rule

TimetableService.create loads existing entries for the same day where teacherId or roomId matches the new entry (timetable.service.ts:17-22), then throws ConflictException('Schedule conflict detected') if any of them overlaps in time (timetable.service.ts:24-30, 62-69):

When roomId is absent from the DTO, Mongoose strips undefined from the query, so the roomId clause is a no-op — effectively teacher-only conflict detection for room-less entries.

5. Permissions reality

• timetable.read and timetable.create exist in the permission catalog (permissions.constants.ts:44-45).
• TimetableController is guarded only by @UseGuards(JwtAuthGuard) (timetable.controller.ts:9); no @Roles/@Permissions metadata is applied, so the global RbacGuard passes any authenticated request (rbac.guard.ts:29).
• Therefore the client must enforce timetable.read / timetable.create in UI/routing itself (mirror guard), and should not assume server-side 403s.

6. Events & side-effects

Gap: the event is emitted but never routed; subscribers (e.g. teacher notification, audit trail) are (planned).

7. Dependencies

8. Business goals

9. Success metrics

• Grid renders from a single GET /timetable?classId= response, server-sorted (timetable.service.ts:48-53) — client never re-sorts.
• Entry create with conflict → inline AppBanner in the editor, form values kept.
• Grid cells render ≥ 40 slots without jank on low-end devices (see 15 §9).
• Zero tenantId leaks in bodies; cross-tenant reads are 404s (base.repository.ts:20-30).

10. Edge cases (derived)

• GET /timetable with neither classId nor teacherId → [] (timetable.controller.ts:26-28).
• Both params present → classId wins (timetable.controller.ts:26-27).
• Conflict on create → 409 ConflictException — no error code in body beyond the default NestJS shape; client matches on 409 status + message.
• Times are plain strings (@IsString, create-timetable-entry.dto.ts:28-33): overlap math is lexical string comparison (timetable.service.ts:62-69) — valid only while times are zero-padded HH:MM; client must enforce the format (server does not).
• dayOfWeek values: monday–saturday only (timetable.schema.ts:7-14); sunday is rejected by @IsEnum (create-timetable-entry.dto.ts:23-25).

11. Assumptions (module)

• Client is forward-looking: backend implements only create + two reads; the full client (grid UX, editors, room view) is specced here per user instruction. The PRD lists native mobile as a later-phase, read-only companion; this package specs a full client (read + write) anyway — the two mandates coexist; write surfaces target admin/coordinator roles.
• Update/delete/bulk-import/substitution/workload/export are not implemented (IMPLEMENTATION_PLAN.md:226 marks "Bulk create, conflicts, substitution, workload, export" as a planned phase-4 row) → all such surfaces are (planned).
• Room view exists only as a client composition (fetch per-class grids and merge); a dedicated GET /timetable?roomId= is (planned).
• No Sunday teaching; saturday is a legal teaching day.

12. Open questions (module-level)