# Liv Hospital International — Integrations & External Services Registry

### 1. Integration Landscape & Policy
To comply with the project execution protocol and protect real patient privacy, **all external integrations operate in Mock / Sandbox mode by default**. No real WhatsApp messages, financial debits, or live external API calls are executed during development without explicit coordinator override.

---

### 2. Service Integration Directory

#### 2.1 WhatsApp Business Platform (Meta Cloud API)
- **Primary Function**: Transactional, event-driven multilingual notifications for patients, companions, drivers, coordinators, and external dispatchers.
- **Current Mode**: `MOCK_SANDBOX` (Active)
- **Mock Behavior**:
  - Outbox jobs capture messages and write full delivery payloads to database table `notification_deliveries`.
  - Simulates instant network dispatch, followed by realistic delayed `delivered` and `read` webhook events.
  - Development UI Notification Log allows coordinators to view rendered templates in TR, EN, and AR, inspect payload parameters, and trigger manual delivery callbacks.
- **Production Activation Requirements**:
  - `WHATSAPP_API_TOKEN`: Meta System User permanent access token.
  - `WHATSAPP_PHONE_NUMBER_ID`: Verified business phone number ID.
  - `WHATSAPP_BUSINESS_ACCOUNT_ID`: WABA ID.
  - `WHATSAPP_WEBHOOK_VERIFY_TOKEN`: Shared secret for incoming webhook validation.
  - Pre-approved Meta Message Templates for each language (TR, EN, AR) matching the approved category (`UTILITY`).
- **Privacy Enforcement**:
  - Zero diagnosis, symptoms, or medical procedures permitted in templates.
  - Only operational details allowed: Patient Name, Flight Number, Pickup Location, Scheduled Time, Driver Name, Vehicle Plate Number, Tracking Link.

---

#### 2.2 Maps, Geocoding & Routing Services
- **Primary Function**: Route calculation, driving distance/duration estimation, geofence radius calculation, and real-time map rendering.
- **Current Mode**: `MOCK_HYBRID` (Leaflet / OpenStreetMap / OSRM with simulated telemetry fallback)
- **Mock Behavior**:
  - Uses OpenStreetMap vector tiles via Leaflet for zero-cost, zero-key map rendering.
  - Routing calculates accurate driving paths and polyline waypoints using open OSRM or mathematical great-circle fallback.
  - Vehicle telemetry simulator generates realistic step-by-step coordinates between Istanbul Airport, Sabiha Gökçen Airport, contracted hotels, and Liv Hospital branches (e.g. Liv Hospital Vadistanbul, Liv Hospital Ulus).
- **Production Activation Requirements (if switching to Google Maps / Mapbox)**:
  - `MAPS_PROVIDER`: `google` | `mapbox` | `osm`
  - `MAPS_API_KEY`: Google Maps JavaScript API & Distance Matrix API key or Mapbox Token.

---

#### 2.3 Flight Telemetry & Status API
- **Primary Function**: Real-time flight arrival time, delay tracking, and terminal/gate updates for airport transfers.
- **Current Mode**: `MOCK_SCHEDULED` (Active)
- **Mock Behavior**:
  - Detects flight numbers matching standard patterns (e.g., `TK1982`, `PC2014`, `EK121`).
  - Returns scheduled arrival times with optional simulated delay scenarios (e.g., 20-minute flight delay triggering automated transfer schedule adjustments).
- **Production Activation Requirements**:
  - `FLIGHT_RADAR_API_KEY` or `AERODATABOX_API_KEY`.

---

#### 2.4 Mobile Push Notifications (FCM / APNs)
- **Primary Function**: Driver notifications for incoming dispatch assignments, urgent route changes, and replacement dispatch requests.
- **Current Mode**: `MOCK_IN_APP` (Active)
- **Mock Behavior**:
  - Driver web and Flutter app poll/receive WebSocket notifications directly via Laravel Reverb / SSE event stream.
- **Production Activation Requirements**:
  - `FIREBASE_CREDENTIALS_JSON`: Service account key file for Firebase Cloud Messaging (FCM).
  - Apple Developer APNs authentication key (`.p8`) for iOS background wakeups.

---

### 3. Environment Variables Reference (.env.example excerpt)
```ini
# Liv Hospital Transfer Platform Integration Modes
INTEGRATION_MODE=sandbox

# WhatsApp Cloud API (Sandbox / Production)
WHATSAPP_DRIVER=mock
WHATSAPP_API_TOKEN=
WHATSAPP_PHONE_NUMBER_ID=
WHATSAPP_BUSINESS_ACCOUNT_ID=
WHATSAPP_WEBHOOK_VERIFY_TOKEN=liv_hospital_wh_secret_token

# Maps & Routing
MAPS_PROVIDER=osm
MAPS_API_KEY=

# Flight Data
FLIGHT_TRACKING_DRIVER=mock
FLIGHT_TRACKING_API_KEY=

# Mobile Push
FCM_SERVER_KEY=
```