Session Operations
Coordinators manage all session operations from the admin dashboard -- attendance recording, schedule changes, discrepancy resolution, and session oversight. This page covers every endpoint and workflow available for session management.
Appointments Operations
GET /admin/appointments/operations -- paginated list of all sessions with attendance data, pricing details, and change logs. This is the primary operational view for coordinators.
The operations endpoint returns enriched appointment objects including tutor and student names, attendance timestamps, pricing breakdown, and any schedule change history. Results are paginated and support filtering by status, tutor, student, and date range.
Frontend page: /admin/appointments
Session Status Flow
| Status | Description | Coordinator Action |
|---|---|---|
| Scheduled | Session is on the calendar, not yet started | Monitor; can reschedule or cancel |
| Checked_In | Tutor has checked in, session is in progress | Monitor for no-shows or issues |
| Awaiting_Approval_Parent | Tutor checked out, waiting for parent confirmation | Follow up if parent does not respond within 2 days |
| Approved | Parent confirmed; session counted toward billing | No action needed |
| Disputed | Parent flagged a problem with this session | Investigate and resolve discrepancy |
| Cancelled_By_Tutor | Tutor cancelled before the session started | Arrange replacement or notify parent |
Attendance Recording
POST /admin/appointments/:id/attendance
Coordinators can manually record or override attendance for any session. This is used when automatic check-in/check-out fails, or when corrections are needed.
| Field | Type | Description |
|---|---|---|
attendance_status | string | Pending, Present, Absent, Late, No_Show |
actual_start_at | datetime | Actual session start time |
actual_end_at | datetime | Actual session end time |
clock_in_source | string | How the check-in was recorded (telegram, web, admin_override) |
clock_out_source | string | How the check-out was recorded (telegram, web, admin_override) |
no_show_party | string | Who was absent: tutor or student |
late_minutes | integer | Number of minutes late (if applicable) |
attendance_notes | string | Free-form coordinator notes on the attendance record |
Check-in / Check-out Windows
Check-in opens 30 minutes before the scheduled start time. Check-out is available from 30 minutes before the scheduled end until 24 hours after the scheduled end.
- Tutors check in via Telegram (
/checkin) or the web dashboard. - Check-in transitions the session from Scheduled to Checked_In and records
checked_in_at. - Check-out transitions from Checked_In to Awaiting_Approval_Parent and records
checked_out_at. - If the tutor checks in early, the bot responds with the exact minutes until the window opens.
Session Confirmation
Sessions cannot be confirmed before they occur (future date guard). After the session date, both parent and tutor have a 2-day window to confirm. If the parent does not respond, the coordinator should follow up directly.
Schedule Changes
POST /admin/appointments/:id/schedule-change
Coordinators can reschedule, cancel, or arrange replacement sessions. Each change is logged with full audit trail.
| Field | Type | Description |
|---|---|---|
change_type | string | reschedule, cancellation, or replacement |
new_start_at | datetime | New start time (for reschedule) |
new_end_at | datetime | New end time (for reschedule) |
cancellation_reason | string | Why the session was cancelled |
financial_treatment | string | How billing is affected (refund, credit, no_charge) |
payout_treatment | string | Whether the tutor is paid (full, partial, none) |
replacement_appointment_id | integer | ID of the replacement session (if applicable) |
notes | string | Coordinator notes on the change |
Flag Mismatch
POST /admin/appointments/:id/flag-mismatch -- flag a tutor/student mismatch on a session. Used when the wrong tutor shows up or a scheduling error assigned the wrong student.
Discrepancies
When a parent and tutor disagree on session hours, a discrepancy is created. Coordinators review and resolve these from the discrepancies page.
| Endpoint | Method | Description |
|---|---|---|
/admin/discrepancies/open | GET | List all open hour disputes |
/admin/discrepancies/:id/resolve | POST | Resolve a discrepancy with coordinator decision |
Frontend page: /admin/discrepancies
Session Notes
PATCH /appointments/:id/notes -- tutor submits tutor_notes after check-out. An ai_summary is automatically generated from the notes, providing structured observations on engagement and learning patterns.
Session notes are visible to coordinators and parents. The AI summary highlights key themes, engagement levels, and follow-up recommendations.