Coordinator Services Framework — Transport (First Service Type)¶

Status: Deferred (design complete, spec when ready to implement) Date: 2026-04-15 Session: 41 Dependencies: Gap #4 (Travel Readiness Assessment), ADR-0018 Phase 5 (Coordination Lifecycle)

Overview¶

Ambulance and ground transport services across the full patient journey — from origin country to destination, between facilities, emergency dispatch, and repatriation. Built as the first service type within a generic Coordinator Services Framework that will later support translators, companions, and ground staff.

Commercial Model¶

• Hybrid: Scheduled transfers are coordinator-assigned from pre-negotiated vendor contracts. Emergency dispatch is fully coordinator-managed.
• Patient visibility: Patient sees assigned vendor details (name, vehicle type, driver info) but does not choose. Coordinator selects based on contracts and patient transport tier.
• No tenant access: Ambulance providers are vendor relationships, not platform tenants. The coordinator_vendors table can migrate to full provider status (provider_type: 'transport') if the model evolves to marketplace.
• Pricing: Not yet decided whether standalone add-on, bundled, or tiered. Transport cost feeds into the comprehensive cost estimate (Gap #9).

Transport Types¶

Coverage¶

Transport is coordinated in both origin and destination countries:

• Origin country: Home → airport. Required for T2+ patients (see Transport Tiers). Coordinator arranges local vendor.
• Destination country: Airport → hotel → hospital → recovery → airport. All legs coordinator-managed.
• Repatriation: Destination → origin country. Air ambulance vendor from registry.

For T1 (standard) patients in origin country, Curaway provides guidance only. For T2+ Curaway coordinates end-to-end.

Data Model¶

coordinator_vendors¶

coordinator_vendors
  id: UUID PK
  tenant_id: UUID FK → tenants  -- owning coordinator tenant, NOT the vendor's own tenant (vendors have no platform accounts)
  vendor_name: VARCHAR(200)
  service_type: ENUM('transport', 'translator', 'companion', 'ground_staff')
  country_code: VARCHAR(3)
  city: VARCHAR(100)
  contact_name: VARCHAR(200)
  contact_phone: VARCHAR(50)
  contact_email: VARCHAR(200)
  contract_status: ENUM('active', 'inactive', 'pending')
  service_capabilities: JSONB
  coverage_area: JSONB
  sla_response_minutes: INT
  cost_model: JSONB
  rating_internal: FLOAT
  notes: TEXT
  created_at, updated_at, deleted_at

service_capabilities JSONB for transport:

{
  "vehicle_types": ["standard", "accessible", "medical", "icu", "air"],
  "medical_escort_available": true,
  "icu_capable": true,
  "air_ambulance": false,
  "languages": ["en", "tr"],
  "available_24_7": true
}

coverage_area JSONB:

{
  "cities": ["Istanbul", "Ankara"],
  "radius_km": 100,
  "airport_codes": ["IST", "SAW"]
}

cost_model JSONB:

{
  "standard_transfer_flat": {"amount": 50, "currency": "USD"},
  "medical_per_km": {"amount": 3.5, "currency": "USD"},
  "icu_per_hour": {"amount": 200, "currency": "USD"},
  "medical_escort_surcharge": {"amount": 100, "currency": "USD"}
}

coordinator_service_bookings¶

coordinator_service_bookings
  id: UUID PK
  case_id: UUID FK → cases
  vendor_id: UUID FK → coordinator_vendors
  service_type: ENUM('transport', 'translator', 'companion', 'ground_staff')
  booking_type: ENUM('scheduled', 'emergency')
  status: ENUM('requested', 'confirmed', 'driver_assigned', 'in_progress', 'completed', 'cancelled')
  journey_leg: ENUM('origin_to_airport', 'airport_to_hotel', 'airport_to_hospital', 'hotel_to_hospital', 'hospital_to_recovery', 'recovery_to_hospital', 'recovery_to_airport', 'repatriation')
  case_phase: VARCHAR(50)
  pickup_location: JSONB
  dropoff_location: JSONB
  scheduled_at: TIMESTAMPTZ
  actual_pickup_at: TIMESTAMPTZ
  actual_dropoff_at: TIMESTAMPTZ
  vehicle_type: VARCHAR(50)
  medical_escort_required: BOOL
  driver_details: JSONB
  cost_quoted: DECIMAL
  cost_actual: DECIMAL
  currency: VARCHAR(3)
  coordinator_id: UUID FK → tenant_members
  patient_notified: BOOL DEFAULT false
  notes: TEXT
  created_at, updated_at

Migration path to full provider¶

1. Add provider_type = 'transport' to provider enum
2. Migrate vendor records into providers table (compatible fields: city, country_code, contact info)
3. Create tenant accounts for vendors needing platform access
4. Swap FK from vendor_id to provider_id in bookings

Travel Fitness → Transport Tier Mapping¶

Gap #4 (Travel Readiness Assessment, Intake Layer 4) captures the raw fitness factors. These factors feed into the Patient Fitness Score (Gap #1 — PFS), which outputs a transport tier (T1-T4).

Input factors (collected in Intake Layer 4 — Gap #4):

Transport tiers (computed as part of PFS — Gap #1):

Case Lifecycle Integration¶

Transport touchpoints by phase¶

PRE-OP PHASE
  ├─ Origin: home → airport (T2+ only)
  ├─ Destination: airport → hotel
  └─ Destination: hotel → hospital (admission day)

ADMITTED / PROCEDURE
  └─ No transport

POST-OP PHASE
  ├─ Hospital → recovery facility (if recovery opted in)
  └─ Hospital → hotel (if no recovery facility)

RECOVERY PHASE
  ├─ Recovery → hospital (escalation / complication)
  └─ Recovery → follow-up appointments

FOLLOW-UP / DEPARTURE
  ├─ Recovery/hotel → airport
  └─ Origin: airport → home (T2+ only)

EMERGENCY (any phase)
  ├─ Current location → nearest hospital
  └─ Repatriation: destination → home country (T4)

Coordinator workflow¶

1. Case enters coordinator_assigned → coordinator sees transport tier and suggested booking template
2. Coordinator creates bookings per leg — selects vendor from registry filtered by destination city + required capabilities
3. Patient sees bookings on timeline and transport panel
4. As each leg completes, coordinator updates status → patient notified
5. Emergency: coordinator creates emergency booking type → skips scheduling → requested → confirmed

Booking state transitions¶

Scheduled:  requested → confirmed → driver_assigned → in_progress → completed
Emergency:  requested → confirmed → in_progress → completed
Either:     any state → cancelled

Emergency Escalation → Transport¶

Connects to recovery milestone escalation rules (ADR-0018).

Repatriation workflow (Phase A — manual)¶

1. Coordinator determines repatriation needed (with surgical provider input)
2. Coordinator contacts air ambulance vendor from registry
3. Coordinator arranges receiving hospital in origin country
4. Booking: journey_leg: repatriation, vehicle_type: air
5. Patient/family notified
6. Insurance coordination off-platform (for now)

Path to Phase B (semi-automated)¶

• Escalation trigger auto-generates transport request with suggested vendor + vehicle type
• Coordinator reviews and confirms with one click

Patient-Facing UI¶

Timeline Card¶

Each booking appears chronologically in the patient's case journey:

┌──────────────────────────────────────────────┐
│ Airport Pickup — Apr 20, 8:00 AM             │
│ ABC Medical Transport · Medical ambulance     │
│ Status: Driver assigned                       │
│ Istanbul Airport → Grand Hyatt Istanbul       │
│ Driver details shared 24h before pickup       │
└──────────────────────────────────────────────┘

• Driver details (name, phone, vehicle plate) appear 24h before scheduled time
• Emergency bookings get urgent visual treatment
• Completed legs show actual times + checkmark

Transport Panel (dedicated section)¶

Persistent reference view — all legs grouped by phase:

TRANSPORT OVERVIEW                    Tier: T3 Medical
─────────────────────────────────────────────────
PRE-OP
  ✓ Home → Airport        Apr 18   Completed
  ✓ Airport → Hotel       Apr 18   Completed
  ◉ Hotel → Hospital      Apr 20   Driver assigned

POST-OP
  ○ Hospital → Recovery   TBD      Pending
  ○ Recovery → Airport    TBD      Pending

─────────────────────────────────────────────────
Emergency contact: Coordinator Ayse · +90 555 XXX

• Status indicators: ✓ completed, ◉ active/next, ○ pending
• Transport tier at top
• TBD legs as placeholders — dates populate when coordinator books
• Emergency coordinator contact always visible

Notifications¶

Gap Integration Map¶

Implementation Phase¶

• Depends on: ADR-0018 Phase 5 (Coordination Lifecycle) and Gap #4 (Travel Readiness)
• Effort: 2-3 weeks (on top of Phase 5, not within it)
• Build with Gap #4 — they are two sides of the same coin (assessment and action)
• Flagsmith flag: coordinator_services_transport_v1

Edge Cases¶