baya-monorepo/product/data-model/diagrams.md

# Diagrams

[← Database Model](index.md)

### 1. Domain map — how the clusters relate

```mermaid
flowchart LR
  PARTNER["🏥 Partner Centers (launch)<br/>partner_centers"]
  IDENTITY["🧑 Identity & Access<br/>users · nurse_profiles · customer_profiles<br/>patients · customer_addresses · nurse_bank_accounts"]
  GEO["📍 Geography<br/>provinces · cities · districts · nurse_service_areas"]
  VERIFY["✅ Verification<br/>nurse_verifications · step_types · steps<br/>documents · nurse_credentials"]
  SERVICES["🩺 Services & Pricing<br/>service_categories · option_groups · option_values<br/>variants · variant_options · search_index · availability"]
  BOOKING["📅 Booking & Scheduling<br/>booking_requests · bookings · booking_sessions<br/>care_instructions · visit_verifications · cancellation_policies"]
  PAY["💳 Payments & Ledger<br/>payment_gateways · payment_transactions · webhook_events<br/>refunds · ledger_entries · nurse_clawbacks · invoices"]
  BNPL["🧾 BNPL<br/>bnpl_transactions"]
  PAYOUT["🏦 Payouts<br/>payout_batches · payouts · booking_links"]
  REVIEW["⭐ Reviews & Records<br/>reviews · review_tags · patient_care_records"]
  MSG["💬 Messaging<br/>tickets · participants · messages"]
  NOTIFY["🔔 Notifications<br/>notifications · support_alerts"]
  AUDITCFG["📜 Audit & Config<br/>audit_logs · system_events<br/>platform_configs · iranian_holidays"]

  PARTNER -. "sponsors / merchant-of-record" .-> VERIFY
  IDENTITY --> VERIFY
  VERIFY --> SERVICES
  SERVICES --> GEO
  IDENTITY --> BOOKING
  SERVICES --> BOOKING
  BOOKING --> PAY
  PAY --> BNPL
  PAY --> PAYOUT
  BOOKING --> REVIEW
  BOOKING --> MSG
  PAY --> NOTIFY
  PAY --> AUDITCFG
```

### 2. Core booking spine (who books whom)

```mermaid
erDiagram
  users ||--o| nurse_profiles : "role=nurse"
  users ||--o| customer_profiles : "role=customer"
  partner_centers ||--o{ nurse_profiles : "sponsors"
  customer_profiles ||--o{ patients : "registers"
  customer_profiles ||--o{ customer_addresses : "saves"
  nurse_profiles ||--o{ nurse_service_variants : "offers"
  customer_profiles ||--o{ booking_requests : "submits"
  nurse_profiles ||--o{ booking_requests : "receives"
  patients ||--o{ booking_requests : "for patient"
  nurse_service_variants ||--o{ booking_requests : "selects variant"
  booking_requests ||--o| bookings : "converts on payment"
  bookings ||--o{ booking_sessions : "has visits"
  booking_sessions ||--o| visit_verifications : "EVV per visit"
  bookings ||--o| booking_care_instructions : "clinical (encrypted)"
  bookings ||--o| reviews : "one review"

  booking_requests {
    bigint id PK
    string status
    string required_caregiver_gender
    datetime nurse_response_deadline_at
    datetime payment_deadline_at
  }
  bookings {
    bigint id PK
    bigint gross_price_irr
    bigint balinyaar_commission_irr
    bigint nurse_payout_amount
    smallint session_count
    datetime dispute_window_ends_at
    string status
  }
  booking_sessions {
    bigint id PK
    int session_index
    date scheduled_date
    string status
    datetime payout_eligible_at
  }
```

### 3. Payments, ledger & payouts

```mermaid
erDiagram
  bookings ||--o{ payment_transactions : "paid by (attempts)"
  payment_gateways ||--o{ payment_transactions : "via"
  payment_gateways ||--o{ payment_webhook_events : "emits"
  payment_transactions ||--o| bnpl_transactions : "if BNPL"
  payment_transactions ||--o{ refunds : "may be refunded"
  refunds ||--o| nurse_clawbacks : "if after payout"
  nurse_profiles ||--o{ nurse_clawbacks : "owes"
  bookings ||--o{ ledger_entries : "money postings"
  bookings ||--o| invoices : "billed"
  nurse_payout_batches ||--o{ nurse_payouts : "groups"
  nurse_profiles ||--o{ nurse_payouts : "receives"
  nurse_bank_accounts ||--o{ nurse_payouts : "to IBAN"
  nurse_payouts ||--o{ nurse_payout_booking_links : "covers"
  bookings ||--o| nurse_payout_booking_links : "settled in one"

  ledger_entries {
    bigint id PK
    uuid transaction_group_id
    string account_type
    string direction
    bigint amount_irr
  }
  refunds {
    bigint id PK
    bigint platform_fee_refunded_irr
    bigint nurse_payout_refunded_irr
    string refund_channel
  }
  bnpl_transactions {
    bigint id PK
    string provider_code
    bigint settled_amount_irr
    bigint bnpl_commission_irr
    string status
  }
```

### 4. Financial lifecycle — escrow → payout → clawback

```mermaid
flowchart TD
  A["Family submits booking_request"] --> B{"Nurse responds in time?"}
  B -->|"reject / expire"| X["request closed — no money moved"]
  B -->|"accept"| C["30-min payment window"]
  C --> D{"Payment method"}
  D -->|"Card (IPG)"| E["payment_transactions = succeeded"]
  D -->|"BNPL (SnappPay)"| F["bnpl_transactions = settled<br/>full amount minus provider commission"]
  E --> G["Ledger posting:<br/>DR escrow_held / CR nurse_payable + platform_revenue"]
  F --> G
  G --> H["Booking confirmed (escrow held)"]
  H --> I["Nurse EVV check-in / check-out per session"]
  I --> J["Booking completed"]
  J --> K["dispute_window_ends_at = completed_at + 72h"]
  K --> L{"Window passed & no dispute?"}
  L -->|"yes"| M["payout_eligible"]
  M --> N["Weekly batch → PAYA to nurse IBAN<br/>payout = gross − balinyaar_commission"]
  K -.->|"refund BEFORE payout"| O["Clean ledger reversal<br/>PSP refund / bnpl_revert"]
  N --> P{"Refund AFTER payout?"}
  P -->|"yes"| Q["nurse_clawbacks receivable<br/>netted next batch or written off"]
  P -->|"no"| Z["Settled and reconciled"]
```