v2 Gap Analysis — Scheduling

Scheduling — V2 Review Gap Analysis

Source: BACKEND-RAMBLINGS.md lines 188-232 Spec: docs/admin-spec/06-scheduling.md Implementation: src/pages/scheduling/

Screens Covered

• Live Sessions (list, create/edit, filters)
• Live Sessions — Calendar view
• Appointment Schedules (TA Schedules: slot management, availability grid)
• Upcoming Appointments (list, create, filters, cancel)
• Holidays (list + calendar views)
• One-to-one Appointment Usability (net-new: utilization tracking)

Live Sessions — List & Create/Edit

Matches

• Title, Date/Time, Level, Semester, Status columns present
• Sortable columns (all spec-defined)
• Create Session dialog with: Title, Date, Time, Zoom Link
• Edit/Delete actions via dropdown
• Semester pre-filter integration (Setup Checklist)
• Filter by Semester and Level

Expands

• Session Title field confirmed (matches spec)
• Zoom Link field in create form (stakeholder said "Zoom link")
• One-per-level auto-creation mentioned in dialog description (spec implies this)

Deviates

• Missing: Explicit recurring flag. Stakeholder said "the ability to signal that it's recurring" with semester start/end dates, override end date, single-occurrence variants. Current form doesn't expose recurrence, start-semester, or end-date override. (Likely deferred to backend logic, but form hides it.)
• Missing: Teacher field on create form. Stakeholder said "the session teacher" is required. Current form omits this.
• Missing: Bulk-add UI. Stakeholder described pattern: "bulk add Sisters' QRCs... just keep adding different... times and days." Not implemented.

Adds

(None notable beyond spec.)

Ambiguous

• Recurrence logic: Is it always "semester start to end"? Can it be a single date? How does the form enforce this?
• Auto-create-one-per-level: Is this always true, or configurable per creation?
• Teacher assignment: Does session auto-assign to the TA/teacher stored elsewhere, or does it need a form field?

Live Sessions — Calendar View

Matches

• New calendar view screen (spec § 2)
• Filter bar: TA, Gender, Level, Event Type
• Week and Month view toggle
• Display: event title, time, TA name, color coding by session type
• Color scheme: Blue for Live Sessions, Green for Appointments, Orange for Rescheduled, Gray for Cancelled
• Create Session button (opens modal)
• Export button (stub)
• Navigate weeks (◀ ▶, Today button)

Expands

• Search bar (by event title, TA name, student name)
• Event detail modal with: Type, Date/Time, TA, Student, Level, Status

Deviates

• Missing: Gender filter behavior. Stakeholder said "filter by... gender" on calendar. Spec § 2.5 shows "filters by TA gender." Implementation filters TA gender only, not student gender for appointments. Spec doesn't clarify gender filter scope for appointments.
• Missing: Session-level actions. Stakeholder said "select a session... cancel it" and "mark it as inactive" and "reassign that session to another teacher." Calendar view shows event detail modal (read-only), not edit/cancel/reassign actions.
• Missing: "Needs replacement" flag visual. Stakeholder said sessions should be "flagged as needs replacement" for TAs on break. No visual indicator in calendar.

Adds

• Week/Month view both implemented (spec mentions both, implementation has both)
• Search across events

Ambiguous

• Cancel vs. Mark Inactive: Stakeholder wants both, but spec doesn't distinguish. Implementation has no cancel/inactive on calendar detail.
• Reassign action: Where is it triggered? Should it be on the detail modal (not present) or a separate workflow?
• "Needs replacement" flag: How is it computed? (TA holiday overlap? Manual flag? Automatic from TA break registration?)

Appointment Schedules (Slot Management)

Matches

• TA dropdown selector
• Weekly availability grid (Sun–Sat, 8 AM–7 PM)
• Timezone selector (per TA)
• Click to toggle slot availability (green = available, empty = unavailable)
• Clone to Next Semester button
• Personal Holidays card per TA

Expands

• Visual legend: available/unavailable colors
• TA selector drives all content (no pre-selection)
• Slot granularity: 1-hour blocks (8 AM–7 PM)

Deviates

• Missing: Bulk-add UI for slots. Stakeholder said "bulk add... multiple appointment slots in one go, just keeping the same TA by just adding different time slots." Current UI is click-to-toggle grid only. No multi-select or bulk action.
• Missing: Slot date-range configuration. Stakeholder said "a weekday from and to date... defining a start date and end date." Current grid is weekly repeating, no start/end date bounds visible on slots.
• Missing: Calendar+list view toggle for appointment schedules. Spec § 5.3 doesn't mention it, stakeholder said "list view and calendar view." Not in this screen; only TA Schedules (slot config) shown. (May be on "Upcoming Appointments" screen instead.)

Adds

• Personal Holidays subsection per TA (spec § 5.4, implemented as Card)

Ambiguous

• Slot date bounds: If a slot is "Mon 2–3 PM from Jan 1 to Feb 28," how is that represented in the 1-hour toggle grid?
• Bulk add: Should it be row-selection in a modal form, or inline addition of multiple rows?

Upcoming Appointments

Matches

• Data table: Date/Time, Student, TA, Group, Status, Rescheduled To columns
• Status values: Upcoming, Rescheduled, Completed, No-Show, Cancelled
• Sortable columns (all spec-defined)
• Search by student or TA name
• Filters: Status, TA
• Actions: Cancel (for non-cancelled, non-completed)
• Create Group Appointment dialog: Group, Date, Time, TA
• Add Student Appointment dialog: Student, Date, Time, TA
• Link to Calendar View (Calendar icon)

Expands

• Date range filter missing from implementation, but spec § 4.5 says "filter by... date (selecting a date or a date range)." Only search/status/TA filters present.

Deviates

• Missing: Reschedule action. Stakeholder said "be able to reschedule an appointment from this section." Only Cancel is shown; no Reschedule button/modal.
• Missing: Cancellation reason templates and messaging. Stakeholder said "send a message or an email... make different templates for the reason why we cancelled... select from the template and send it." Not in UI.

Adds

(None; mostly faithful to spec and stakeholder.)

Ambiguous

• Reschedule flow: Modal to pick new date/time? Inline edit? Link to calendar?
• Cancellation message: Is it optional, required, or both with/without template paths?

Holidays

Matches

• List view: Holiday Name, Date, Type, Affects columns
• Calendar view: month-based grid with color-coded holidays
• Type filter: System-wide, Live Sessions only, Appointments only
• Type colors: Red (System-wide), Blue (Live Sessions), Amber (Appointments)
• Add Holiday dialog: Name, Date, Type
• Edit and Remove actions
• List/Calendar toggle

Expands

• Merged system holidays + live session holidays as spec says § 6.2

Deviates

• Missing: TA personal breaks/holidays integration. Spec § 6.2 says "merged: system holidays + live session holidays." Stakeholder said "If any of the TAs are taking a break, we add that here so we specify this teacher will not be available... flags their live sessions... as needing to be assigned to another teacher." Holidays screen is global only; TA personal time-off is isolated to TA Schedules > Personal Holidays (Card per TA). No unified "TA break" entity that both blocks appointments AND flags live sessions.

Adds

• Holidays also appear in calendar-events data (integrated with calendar view)

Ambiguous

• TA break workflow: Should TA personal holidays (in TA Schedules) also flag live sessions as "needs replacement"? Spec doesn't say; stakeholder implies cross-concern (holidays block both, flag sessions).

One-to-one Appointment Usability

Status: Not Implemented

Stakeholder description (lines 232):

• Show utilization by gender (sisters' vs. brothers' appointments)
• Week-by-week underutilized slots
• "Remove slot from calendar" button for underutilized slots

Spec: No dedicated section for this. (May be intended as a Dashboard tile or subsection under TA Schedules.)

Implementation: No screen found. TA Schedules shows slot management, not utilization metrics.

Gaps

• No utilization dashboard showing slot fill rate by gender
• No week-by-week underutilization report
• No "remove slot" action linked to underutilization detection

Summary

Net-New Screens/Sections

1. Calendar View — unified live sessions + appointments calendar (spec § 2, fully impl.)
2. One-to-one Appointment Usability — utilization dashboard (spec silent, not impl.)

Biggest Deviations

1. Live Sessions Create/Edit

   • Missing teacher field
   • Missing recurrence/date-range controls (semester start, end override, single-date)
   • Missing bulk-add UI

2. Live Sessions Calendar

   • Missing cancel/inactive/reassign actions (read-only detail modal only)
   • Missing "needs replacement" flag visual
   • "Gender filter" scope unclear (TA gender only vs. student gender)

3. TA Schedules (Slot Management)

   • Missing bulk-add UI for slots
   • Missing start/end date bounds on slots (only weekly repeating grid shown)
   • Missing calendar+list view toggle

4. Upcoming Appointments

   • Missing date range filter
   • Missing reschedule action
   • Missing cancellation reason templates + messaging

5. Holidays

   • TA personal time-off isolated; no integration with "needs replacement" flag on live sessions

Top Ambiguities

1. Recurrence semantics: Are sessions always semester-scoped? Can a single-date session be created? How is recurrence signaled in the UI?
2. Teacher assignment on sessions: Form omits teacher field; is it inherited from elsewhere, or should it be present?
3. Needs replacement flag: How is it computed? Manual, automatic from TA break, or both?
4. Bulk-add patterns: Live Sessions (dates, times, days) and TA Schedules (slots) both mention bulk operations; neither has UI.
5. Reschedule flow: Full modal? Inline? Does it re-use the Create modal or open a new one?
6. Utilization dashboard: Intended as dashboard tile, TA Schedules subsection, or standalone page?

Implementation Readiness

Production Ready: Calendar View, Upcoming Appointments (core CRUD), Holidays Design Needed: Recurrence controls (Live Sessions), Bulk-add (Sessions & TA slots), Session actions on calendar (cancel/inactive/reassign), Cancellation templates, Utilization dashboard Clarification Needed: Gender filter scope, TA break → session flagging workflow, slot date bounds representation