5. Booking & Scheduling

← Business Requirements

(a) Business requirements

The lifecycle has two phases separated into two tables so each table's invariants stay clean: a request phase (no money) and a booking phase (always implies captured payment).

Request → accept → pay → confirm lifecycle:

  1. Customer submits a booking request (nurse, patient, variant, address, date/time, requested caregiver gender, customer notes). Status pending_nurse_response.
  2. The nurse must respond before a response deadline (nurse_response_deadline_at, computed from config and frozen on the request). The nurse accepts → accepted_awaiting_payment, or rejects → rejected_by_nurse, or the deadline passes → expired_no_response.
  3. On accept, a 30-minute payment window opens (payment_deadline_at). The customer pays within it → a bookings row is created (confirmed). If the window lapses → payment_deadline_expired.

Single-visit AND multi-session / long-duration engagements must both be representable. Home nursing is frequently multi-visit: post-surgery daily visits for ten days, month-long nightly or شبانه‌روزی (24h live-in) care. A booking therefore carries a session_count and owns N booking_sessions (one row per scheduled visit), each with its own schedule, its own EVV check-in/out, and its own payout eligibility. A single EVV per booking cannot represent a multi-day engagement, so the engagement-to-session split is the core scheduling model.

Booking lifecycle: pending_payment → confirmed (payment captured) → in_progress (first/relevant session check-in) → completed (sessions checked out) → optionally disputed → closed; or cancelled before service. Allowed transitions are guarded explicitly so the booking and EVV state machines cannot silently contradict.

Snapshots: variant_snapshot_json and address_snapshot_json freeze the service and address at booking time.

(b) Iran-specific considerations

  • Multi-session and شبانه‌روزی live-in care is the dominant elder-care shape in Iran, not a niche — modeling only single visits would fail to represent demand.
  • Heavy platform control over multi-visit scheduling strengthens a worker-misclassification argument under labor law; this is flagged for counsel, and the platform deliberately keeps the nurse's accept/reject autonomy per request.
  • Availability slots/exceptions are soft guidance only (informing search), not hard blocks — the nurse still individually accepts or rejects each request, which also fits the Shamsi week and holiday rhythm.

(c) MVP vs DEFERRED

  • MVP: request→accept→pay→confirm lifecycle with response deadline + 30-min payment window; single-visit bookings; booking_sessions for multi-session/long-duration engagements with per-session EVV and payout; explicit status-transition guards; snapshots; soft availability slots/exceptions.
  • DEFERRED: open-ended recurring schedules (recurring_booking_schedules modeled, inactive — launch is all finite engagements); milestone/progress-payment UX beyond per-session accrual; hard availability-based booking blocks.

(d) Supporting database entities

booking_requests (carries nurse_response_deadline_at, payment_deadline_at, required_caregiver_gender), bookings (carries session_count, dispute_window_ends_at, fee split), booking_sessions, booking_care_instructions, nurse_availability_slots, nurse_availability_exceptions, nurse_service_variants, patients, customer_addresses.

Related: Data model — Booking & Scheduling.

↑ Back to top