clean and refine product docs structure

2026-06-24 01:32:46 +03:30
parent be07c703ec
commit 1df3cd9f64
113 changed files with 6078 additions and 4973 deletions
@@ -0,0 +1,147 @@
+# 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"]
+```