# Diagrams

← Database Model

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

    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) #

    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 #

    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 #

    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"]

↑ Back to top