v2 Admin Spec — Scheduling

Scheduling

Domain 5 of the Enhanced Candidate A navigation structure. Contains: Calendar View, Live Sessions, Upcoming Appointments, TA Schedules, Holidays, One-to-One Appointment Usability (NEW in v2). Primary workflow served: WF5 (Scheduling — reduced from 4-6 screens to 1-2 screens) Key new screen (v1): Calendar View — unified calendar showing all live sessions and 1:1 appointments across all TAs Key new screen (v2): One-to-One Appointment Usability — gender-split slot fill rates and underutilization tracking (§7)

1. Domain Overview

Scheduling groups all time-based events: live sessions and 1:1 appointments. Previously these were split between Program (Live Sessions) and Appointments (Upcoming, TA Schedules, Holidays). In Enhanced Candidate A, they're unified under one domain with a new Calendar View providing the unified overview the admin requested (Interview: "Calendar view of all live sessions and 1:1 appointments across all TAs, filterable by gender").

Key changes (v1):

Calendar View provides the unified cross-TA view
Holidays merged: system holidays + live session holidays (from dissolved Students Management grab-bag) into one screen
Live Sessions moved from Program (time-based, not passive content)

Key changes (v2):

Live Sessions gains teacher assignment, recurrence/date-range controls, bulk-add, "Needs replacement" flag
Calendar View gains cancel-session, mark-inactive, reassign-session actions, and cancellation-reason templates
Upcoming Appointments gains a date-range filter, reschedule action, and cancellation-reason templates
TA Schedules gains date-bound slots and bulk-add
NEW §7: One-to-One Appointment Usability dashboard

2. Screen: Calendar View

2.1 Purpose

Unified visual calendar of all live sessions and 1:1 appointments across all TAs. Addresses interview request for "calendar view filterable by gender."

2.2 Entry Points

Sidebar: Scheduling > Calendar View
Dashboard: Appointment Utilization tile click
Student Detail > Appointments tab: "Calendar View" link
One-to-One Appointment Usability: underutilized-slot drilldown [v2]

2.3 Layout

Calendar grid with filter bar above. Supports week view (default) and month view toggle.

2.4 Data Displayed

Events on calendar:

Event Type	Source	Display	Color
Live Session	`live_sessions` table	Time block with session title, level badge, teacher initials	Blue
Live Session — Needs Replacement `[v2]`	`live_sessions` where assigned teacher is on personal break	Time block with warning badge "Needs Replacement" overlay	Blue + amber border
1:1 Appointment	`appointments` table	Time block with student name, TA name	Green
Cancelled	`appointments` / `live_sessions` with cancelled status	Strikethrough, faded	Gray
Rescheduled	`appointments` where `re_schedule=1`	Original time shown faded, new time highlighted	Orange
Inactive `[v2]`	`live_sessions` where `active=0`	Dashed border, faded	Gray

2.5 Filters

Filter	Options	Default
View	Week / Month	Week
TA	All TAs / specific TA	All
Gender	All / Male / Female	All (filters by TA gender; appointment gender filter scope TBD — see §2.9)
Level	All / Level 0-4 / Year 2	All
Event Type	All / Live Sessions / Appointments	All
Needs Replacement `[v2]`	All / Only sessions needing replacement	All

2.6 Actions

Action	Trigger	Permission	Behavior
Create Live Session	"+" button on time slot or "New Session"	Admin	Opens create session modal (see §3.6)
Create Appointment	Click empty TA slot	Admin	Opens create appointment modal
View/Edit Event	Click existing event	Admin (edit), All (view)	Opens event detail modal
Cancel Session `[v2]`	"Cancel" in event detail modal for live session	Admin	Destructive confirmation with cancellation-reason template picker + optional "send message" toggle (see §8)
Mark Session Inactive `[v2]`	"Mark Inactive" in event detail modal	Admin	Toggles `live_sessions.active=0`; confirmation prompt; event renders as Inactive on calendar
Reassign Session `[v2]`	"Reassign" in event detail modal for live session	Admin	Modal: select new teacher from TA list (filtered by level + gender); confirmation; clears Needs Replacement flag if it was set
Cancel Appointment `[v2]`	"Cancel" in event detail modal for appointment	Admin	Destructive confirmation with cancellation-reason template picker + optional "send message" toggle
Reschedule Appointment `[v2]`	"Reschedule" in event detail modal for appointment	Admin	Opens reschedule modal (see §4.6)
Navigate Weeks	◀ ▶ arrows	All	Shifts week/month view
Today	"Today" button	All	Returns to current week/month
Export	"Export" button	Admin	Exports visible events as CSV

2.7 States

State	Display
Has events	Calendar with color-coded events
Empty week	Calendar grid with no events. "No sessions or appointments this week."
Loading	Skeleton calendar grid
Error	"Unable to load schedule data." + Retry

2.8 Role Visibility

Admin: Full view + all actions
TA: Filtered to own events only (accessible as "My Schedule")
View-Only: Full view, no create/edit actions

2.9 TBDs `[v2]`

Gender filter scope for appointments: filter by TA gender or student gender? (Framework v2 ambiguity — transcript not definitive)
"Needs replacement" computation: driven automatically from TA personal-break overlap (§6), manually flagged, or both? Default assumption: automatic on TA break creation + manual override available.

3. Screen: Live Sessions

3.1 Purpose

Schedule group learning sessions. Relocated from Program > Live Sessions.

3.2 Entry Points

Sidebar: Scheduling > Live Sessions
Calendar View: click on live session event
Semester Hub > Setup Checklist: "Configure →" link (pre-filtered)

3.3 Layout

Filter bar + data table with primary actions (Create, Bulk Add) above.

3.4 Key Changes from Current

New location (Scheduling section, was Program)
Semester filter pre-population from Setup Checklist
"Return to Checklist" banner when accessed from checklist

v2 additions:

Teacher field on create form
Recurrence + date-range controls (semester-bound default, end-date override, single-date option)
Bulk-add live sessions (same name, different times/days/teachers)
"Needs replacement" flag column
Cancellation-reason template on cancel + optional send-message toggle

3.5 Data Displayed

Column	Source	Sortable
Session Title	`live_sessions.title`	Yes
Date/Time	`live_sessions.date` (first occurrence shown for recurring)	Yes
Recurrence `[v2]`	Derived: "Weekly", "One-time", "Custom range"	Yes
Level	level assignment	Yes
Teacher `[v2]`	`live_sessions.teacher_id` → `users.name`	Yes
Semester	semester scope	Yes
Status	active / inactive / completed / cancelled	Yes
Needs Replacement `[v2]`	Boolean flag — amber badge when true	Yes

3.6 Create / Edit Session Form `[v2 — expanded]`

Fields:

Field	Type	Required	Notes
Session Title	text	Yes	Preserved from v1
Level	select (Level 0-4, Year 2, or All)	Yes	"All" triggers auto-create one session per level (preserved from v1)
Teacher `[v2]`	select (TAs filtered by level + gender)	Yes	New in v2; stakeholder said "the session teacher" is required
Zoom Link	url	Yes	Preserved from v1
Recurrence `[v2]`	radio: Weekly (semester-bound) / Single date / Custom range	Yes	Default: Weekly
Start Date `[v2]`	date picker	Yes when Weekly or Custom range	Default: semester start
End Date `[v2]`	date picker	Optional (Weekly) / Yes (Custom range)	Default: semester end; override supported
Session Date `[v2]`	date picker	Yes when Single date	Hides Start/End fields
Day of Week `[v2]`	select (Mon-Sun)	Yes when Weekly or Custom range	Hidden for Single date
Time	time picker	Yes	Preserved from v1
Duration	number (minutes)	Yes	Preserved from v1

Recurrence semantics:

Weekly (default): Creates a recurring session each Day of Week at Time from Start Date (semester start by default) through End Date (semester end by default, overridable).
Single date: Creates one session on Session Date at Time.
Custom range: Creates a recurring session bounded by explicit Start Date and End Date.

3.7 Actions

Action	Trigger	Permission	Behavior
Create Session	"Create Session" button	Admin	Opens create modal (§3.6)
Bulk Add Sessions `[v2]`	"Bulk Add" button	Admin	Opens bulk-add modal (§3.8)
Edit	Row dropdown → Edit	Admin	Opens edit modal (same form as create)
Cancel Session `[v2]`	Row dropdown → Cancel	Admin	Destructive confirmation with cancellation-reason template picker + "send message" toggle (see §8)
Mark Inactive `[v2]`	Row dropdown → Mark Inactive	Admin	Toggles `active=0`; row renders as Inactive
Reassign Session `[v2]`	Row dropdown → Reassign	Admin	Modal: select new teacher; clears Needs Replacement flag
Delete	Row dropdown → Delete	Admin	Destructive confirmation; hard delete (preserved from v1)

3.8 Bulk Add Sessions Modal `[v2 — NEW]`

Purpose: Create multiple live sessions sharing the same title but differing by time/day/teacher (stakeholder example: "bulk add Sisters' QRCs... just keep adding different... times and days").

Layout: Dialog with shared header fields + repeatable row grid + "Add Row" button.

Shared fields (applied to all rows):

Session Title
Level
Zoom Link (optional; can be overridden per-row)
Recurrence (Weekly / Single date / Custom range)
Start Date / End Date (for Weekly or Custom range)

Per-row fields:

Day of Week (if Weekly/Custom range) or Session Date (if Single date)
Time
Duration
Teacher (TA selector, filtered by level + gender)
Zoom Link override (optional)

Actions:

Add Row
Remove Row (per row; disabled if only one row)
Create All (validates each row; shows per-row errors inline; on success creates all sessions atomically and closes modal with success toast "N sessions created")
Cancel

TBD: UX pattern for error recovery if some rows are valid and others invalid — fail-all vs. create-valid-and-flag-invalid. Default assumption: fail-all with inline validation errors.

3.9 States

Standard (loaded, empty: "No live sessions for this semester.", loading, error)

3.10 Role Visibility

Admin: Full CRUD + bulk add + cancel/inactive/reassign. View-Only: View only. TA: Hidden from nav (sees events on Calendar/My Schedule).

4. Screen: Upcoming Appointments

4.1 Purpose

View and manage scheduled 1:1 sessions. Relocated from Appointments > Upcoming Appointments.

4.2 Entry Points

Sidebar: Scheduling > Upcoming Appointments
Calendar View: appointment event click
Student Detail > Appointments tab: appointment click

4.3 Layout

Filter bar + data table

4.4 Data Displayed

Column	Source	Sortable
Date/Time	`appointments.apt_time`	Yes
Student	student name via enrollment	Yes
TA	`users.name` via `appointments.ta_id`	Yes
Group	`group_name.name` via `appointments.group_id`	Yes
Status	Derived (upcoming/completed/cancelled/rescheduled/no-show)	Yes
Rescheduled To	`appointments.new_apt_time`	No

4.5 Filters `[v2 — expanded]`

Filter	Options	Default
Search	Student or TA name	—
Status	All / Upcoming / Completed / Cancelled / Rescheduled / No-Show	All
TA	All TAs / specific TA	All
Date Range `[v2]`	Single date or date range picker	(none)

4.6 Existing Capabilities (preserved from v1)

View all scheduled appointments
Create appointment for a group
Add single student appointment
Cancel appointments

4.7 Actions

Action	Trigger	Permission	Behavior
Create Group Appointment	"Create" button	Admin	Modal: select group, date, TA
Create Individual Appointment	"Add Student Appointment" button	Admin	Modal: search student, select date, TA
Cancel	Cancel icon on row	Admin	Destructive confirmation with cancellation-reason template picker + "send message" toggle `[v2]` (see §8)
Reschedule `[v2]`	"Reschedule" icon on row	Admin	Opens Reschedule modal: current date/time shown, pick new date/time, optional "notify student" toggle; sets `appointments.re_schedule=1` and `new_apt_time`
View Student	Student name click	All	→ Student Detail Page
View in Calendar	"Calendar" link	All	→ Calendar View filtered to this TA/date

4.8 States

Standard list states

4.9 Role Visibility

Admin: Full CRUD
TA: Own appointments only (via "My Schedule" sidebar item)
View-Only: View only

5. Screen: TA Schedules

5.1 Purpose

Configure when TAs are available for 1:1 booking. Relocated from Appointments > TA Schedules.

5.2 Entry Points

Sidebar: Scheduling > TA Schedules
TA Detail Page > Schedule tab links here
Semester Hub > Setup Checklist: "Configure →" link
One-to-One Appointment Usability: "Remove Slot" drilldown [v2] (§7)

5.3 Layout

TA selector + weekly availability grid + Personal Holidays card + Bulk-Add drawer [v2].

5.4 Data Displayed

Field	Source
TA Name	Selected TA
Timezone	`users.timezone` for selected TA
Weekly Grid	Days × time slots with available/unavailable indicators
Slot Date Bounds `[v2]`	Per-slot `valid_from` / `valid_to` dates (semester start/end default)
TA Holidays	Personal holidays for this TA

5.5 Slot Date Bounds `[v2 — NEW]`

Each availability slot in the weekly grid carries a valid_from and valid_to date, defaulting to the selected semester's start and end. Admins can override per-slot via the slot detail popover:

Click a slot → popover shows "Available: [valid_from] – [valid_to]" with editable date pickers
A slot outside its date bounds renders as striped/faded in the grid (when viewing a week outside its range)
Week navigation within the grid respects slot date bounds (slot only booking-eligible within range)

Rationale: Stakeholder said "a weekday from and to date... defining a start date and end date." Enables mid-semester schedule changes (e.g., "TA is only available Mondays for the first 4 weeks, then switches to Tuesdays").

5.6 Existing Capabilities (preserved from v1)

Configure TA weekly availability
Set timezone for TA
Add/remove appointment slots
Manage TA holidays

5.7 Actions

Action	Trigger	Permission
Select TA	TA dropdown	Admin
Toggle Slot	Click time slot	Admin
Edit Slot Date Bounds `[v2]`	Click slot → popover date pickers	Admin
Set Timezone	Timezone dropdown	Admin
Add TA Holiday	"Add Holiday" button on Personal Holidays card	Admin
Bulk Add Slots `[v2]`	"Bulk Add Slots" button	Admin
Clone Schedule	"Clone to [New Semester]" button	Admin — copies this TA's schedule to next semester (preserved from v1)

5.8 Bulk Add Slots Modal `[v2 — NEW]`

Purpose: Add multiple appointment slots for the currently selected TA in one go (stakeholder: "bulk add... multiple appointment slots in one go, just keeping the same TA by just adding different time slots").

Layout: Dialog with shared header (TA name read-only, semester context) + repeatable row grid + "Add Row" button.

Per-row fields:

Day of Week (Mon-Sun)
Start Time
End Time (or Duration)
Valid From (date; default: semester start)
Valid To (date; default: semester end)

Actions:

Add Row
Remove Row (disabled if only one row)
Create All (validates each row; checks for overlap with existing slots; creates all slots atomically on success; toast "N slots added")
Cancel

TBD: Conflict-resolution UX when a bulk row overlaps an existing slot — skip, overwrite, or error. Default assumption: error with inline warning, admin must remove conflicting row.

5.9 States

TA selected, has schedule: Weekly grid populated
TA selected, no schedule: Empty grid. "No availability configured for [TA Name]."
No TA selected: "Select a TA to view and configure their schedule."

5.10 Role Visibility

Admin: Full edit
TA: Own schedule only (via "My Schedule" sidebar item), view-only
View-Only: View only

6. Screen: Holidays

6.1 Purpose

Define system-wide non-working days. Merged: system holidays (from Appointments > Holidays) + live session holidays (from dissolved Students Management grab-bag #14).

6.2 Entry Points

Sidebar: Scheduling > Holidays
Semester Hub > Setup Checklist: "Configure →" link

6.3 Layout

Calendar view or list view (toggle)

6.4 Data Displayed

Column	Source
Holiday Name	holiday title
Date	holiday date
Type (NEW)	System-wide / Live Sessions only / Appointments only
Affects	What this holiday blocks (all sessions, appointments only, etc.)

6.5 Key Change from Current

Merged: Previously holidays for appointments and live session holidays were in different screens. Now unified. Type field distinguishes scope.

6.6 Existing Capabilities (preserved)

Manage public holidays (system-wide)
Remove holidays

6.7 Actions

Action	Trigger	Permission
Add Holiday	"Add Holiday" button	Admin
Edit	Edit icon	Admin
Remove	Delete icon	Admin (destructive)

6.8 States

Standard (loaded, empty: "No holidays configured.", loading, error)

6.9 Role Visibility

Admin: Full CRUD. View-Only: View only. TA: Hidden.

6.10 Cross-Reference with Needs Replacement Flag `[v2]`

While this screen covers system-wide holidays, TA personal breaks are still managed in TA Schedules §5 (Personal Holidays card). When a TA personal break is added, any live session assigned to that TA during the break period is automatically flagged "Needs Replacement" on Live Sessions (§3) and Calendar View (§2). The flag clears automatically when the session is reassigned via the Reassign Session action.

TBD (from Framework v2): Whether Needs Replacement flagging is fully automatic, manual-only, or both.

7. Screen: One-to-One Appointment Usability `[v2 — NEW]`

7.1 Purpose

Dashboard showing 1:1 appointment slot utilization across TAs, segmented by gender, with week-by-week underutilization visibility. Enables admins to identify and remove chronically unfilled slots. Stakeholder description (ramblings line 232): "Show utilization by gender... Week-by-week underutilized slots... Remove slot from calendar button."

7.2 Entry Points

Sidebar: Scheduling > One-to-One Appointment Usability
Dashboard: Appointment Utilization tile → "View details" link
TA Detail Page > Schedule tab: "View usability report" link

7.3 Layout

Three-section layout:

Top: Summary metrics strip — overall fill rate, sisters' fill rate, brothers' fill rate (for current semester)
Middle: Gender-split slot fill rate panel — side-by-side stacked bars or cards per gender showing filled / unfilled / cancelled slot counts and percentages
Bottom: Underutilized slots table — week-by-week breakdown of slots below a fill-rate threshold, with inline Remove Slot action

7.4 Data Displayed

Summary metrics (top strip):

Metric	Computation
Overall Fill Rate	(filled appointments / available slots) × 100 for current semester
Sisters' Fill Rate	Same, scoped to female TAs' slots
Brothers' Fill Rate	Same, scoped to male TAs' slots
Total Slots Available	Count of active slots in date range
Total Appointments Booked	Count of non-cancelled appointments in date range

Gender-split panel (middle):

Metric	Sisters	Brothers
Slots Available	count	count
Slots Filled	count + %	count + %
Slots Unfilled	count + %	count + %
Avg Weekly Fill Rate	%	%

Underutilized slots table (bottom):

Column	Source	Notes
TA	`users.name`	Links to TA Detail
Gender	`users.gender`	Badge
Day/Time	slot definition	e.g., "Mon 3:00–4:00 PM"
Weeks Observed	count of weeks in filter range
Weeks Filled	count of weeks with a booking
Fill Rate	%	Red badge if < threshold
Trend	sparkline (week-by-week fill 1/0)	Visual indicator

7.5 Filters

Filter	Options	Default
Semester	current / past semesters	Current
Date Range	single week / month / semester / custom	Semester
Gender	All / Sisters / Brothers	All
TA	All / specific TA	All
Fill Rate Threshold	< 25% / < 50% / < 75%	< 50%

7.6 Actions

Action	Trigger	Permission	Behavior
Remove Slot	Row action in underutilized table	Admin	Destructive confirmation: "Remove [Day/Time] slot for [TA]? This deletes the recurring slot from [TA]'s schedule. Existing bookings will not be affected." On confirm, deletes the slot from TA Schedules; toast "Slot removed"
View TA Schedule	TA name click	Admin	→ TA Schedules §5 pre-filtered to this TA
View in Calendar	Row → Calendar icon	All	→ Calendar View §2 filtered to this TA/slot
Export Report	"Export" button	Admin	CSV export of underutilized slots table
Set Threshold	Threshold filter	All	Re-computes underutilized table

7.7 States

State	Display
Has data	Metrics strip + panel + underutilized table
No underutilized slots	Metrics strip + panel + "No slots below [threshold] in this range. Nice work."
Loading	Skeleton metrics + skeleton bars + skeleton table
Error	"Unable to load utilization data." + Retry
No slots configured	"No appointment slots configured for this semester. Configure in TA Schedules."

7.8 Role Visibility

Admin: Full view + Remove Slot action + Export
TA: Filtered to own slots only, view-only (no Remove)
View-Only: Full view, no actions

7.9 TBDs

Whether "underutilized" threshold is user-configurable per-session or a system default
Whether Remove Slot also cancels any existing future bookings on that slot (default assumption: no — existing bookings preserved per confirmation copy above)
Interaction with cross-semester slot data (past semester fill rates shown for context, but slots can only be removed for current/future semesters)

8. Cancellation Reason Templates `[v2 — NEW — cross-cutting]`

8.1 Purpose

Stakeholder described needing to "send a message or an email... make different templates for the reason why we cancelled... select from the template and send it." Applies to both live session cancels (Calendar View §2.6, Live Sessions §3.7) and appointment cancels (Calendar View §2.6, Upcoming Appointments §4.7).

8.2 Template Management

Templates are managed via Admin & System > Settings > Cancellation Templates (TBD: exact settings location — default assumption here; may be spec'd in domain 10)
Each template has: Name, Subject (for emails), Body (supports merge tags: {{student_name}}, {{session_title}}, {{date}}, {{ta_name}})
Templates are categorized by event type: Live Session / Appointment

8.3 Cancel Flow Integration

When Cancel is triggered on a live session or appointment:

Destructive confirmation dialog with:
- Summary of the event being cancelled
- "Cancellation Reason" select (dropdown of templates filtered by event type, plus "No template / custom" option)
- "Send message to student(s)" toggle (default: ON)
- If template selected: preview pane showing rendered message with merge tags filled
- If "No template / custom": free-text area for one-off message
- "Cancel Event" (destructive) / "Keep Event" buttons
On confirm:
- Event marked cancelled
- If "Send message" ON: message sent to affected student(s) via their preferred channel (email/push — TBD, resolved in Communication domain)
- Toast confirms "Event cancelled" + "Message sent to N recipient(s)" if applicable

8.4 TBDs

Storage location for templates (Settings vs. Communication domain templates library)
Message delivery channel (email, push, or both — likely defers to Communication domain routing)
Whether TA also receives a cancellation notification (default assumption: yes)

9. Cross-Domain Integration Points

Calendar View and Live Sessions cross-reference TA personal breaks (§6.10) for Needs Replacement flagging [v2].
Live Sessions Teacher field (§3.6) pulls from Teacher Management (TA list, gender and level scoping applied).
One-to-One Appointment Usability (§7) reads from TA Schedules (slot definitions) and Upcoming Appointments (booking data).
Cancellation Reason Templates (§8) are managed in Admin & System > Settings (TBD — see §8.2). Message delivery resolves through Communication domain (see v2 domain 11).
Semester Hub > Setup Checklist deep-links into Live Sessions, TA Schedules, and Holidays (preserved from v1).