Session Lifecycle

Every tutoring session moves through a defined set of lowercase backend statuses from creation to completion. The UI derives role-facing labels such as Awaiting Your Acknowledgement and Acknowledged, while not_completed is persisted for session-change threads that expire without agreement.

Status Flow

Statuses

Check-in Rules

• Check-in sets checked_in_at to the current timestamp and transitions the status to checked_in.
• If the tutor tries to check in too early, the bot responds with the exact number of minutes until the window opens.
• Check-in can be done via Telegram (/checkin command or inline button) or via the web dashboard.
• Only sessions with status scheduled can be checked into.
• If there is an unresolved reschedule request, tutor check-in is blocked until the request is approved or rejected.

Check-out Rules

• Check-out sets checked_out_at and transitions status to awaiting_approval_parent.
• Tutors can only check out of a session they have already checked into.
• Web and Telegram allow check-out from 30 minutes before scheduled end until 24 hours after scheduled end.
• After check-out, the tutor is prompted to submit session notes (text, photos, audio, documents).
• Notes are stored in R2 and linked to the appointment record.

Session Notes & AI Summary

After each session, tutors submit notes describing what was covered, student engagement, and any observations. These notes support multiple attachment types:

An AI summary is generated from the tutor's notes, providing structured observations on engagement, confidence levels, and learning patterns. These summaries are visible to coordinators and parents.

Parent Approval Flow

1. 1 After the tutor checks out, the session appears in the parent's dashboard as Awaiting Your Acknowledgement (persisted backend status: awaiting_approval_parent).
2. 2 The parent reviews the session details (date, time, tutor notes) and either acknowledges or disputes.
3. 3 On Acknowledge: status moves to approved and the parent-facing label changes to Acknowledged. Native sessions require both checked_in_at and checked_out_at before this transition is accepted.
4. 4 On Dispute: status moves to disputed. A coordinator is notified to investigate.
5. 5 Admin approval override uses the verify path with a required reason. Imported/legacy sessions are exempt from the attendance requirement and package deduction.

Ad-hoc Sessions

Tutors can batch-log extra sessions (e.g., exam preparation) with billed_as_addon=1. These are tracked separately in analytics and billing but follow the same approval flow.

Session Change Rules

• Direct Reschedule and Cancel session controls now live on the parent child sessions page and the tutor Sessions page.
• New self-service cancel and reschedule are available only while the session is still scheduled, still in the future, and more than 4 hours away from the scheduled start time.
• Parent family sessions now steer child-filtered users from an empty Upcoming tab to Future when the real actionable session is beyond the next 7 days.
• Only one reschedule proposal version can be open at a time for a session thread.
• Reschedule keeps the original session duration fixed: the server derives new_end_time from the original slot plus the proposed new start time.
• Both cancel and reschedule require a reason. Parent and tutor web forms now use role-specific reason pickers instead of free-text only.
• Cancellation panels show the current sheet-based penalty guidance plus the coordinator-waiver reminder before the user confirms.
• The proposed replacement slot must itself still be in the future. A stale proposal cannot be approved after its proposed start time has already passed.
• Reschedule approval must come from the counterparty: parent responds to tutor requests, tutor responds to parent requests. The responder can also counter-propose a different slot instead of rejecting outright.
• If a request is still unresolved at the original session start time, it expires and the appointment becomes not_completed.
• Cancellation is still allowed while a reschedule request is open. Cancelling the session closes the open reschedule thread.
• Trial sessions now use the same per-session reschedule/cancel flow as regular sessions.
• Backend session workflow projections are read-only. Expiry and reminder sweeps run from the scheduler, so reading an appointment feed should not mutate appointment or reschedule state.

Telegram still supports tutor session changes, but it now follows the same backend lockouts and expiry rules as the web flows. See Telegram Session Changes for the tutor bot conversation details.