hamid/baya-monorepo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

clean and refine product docs structure

Browse Source
This commit is contained in:
hamid
2026-06-24 01:32:46 +03:30
parent be07c703ec
commit 1df3cd9f64
113 changed files with 6078 additions and 4973 deletions
Download Patch File Download Diff File Expand all files Collapse all files
product/data-model/diagrams.html
+164
View File
@@ -0,0 +1,164 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Diagrams — Balinyaar docs</title>
<link rel="stylesheet" href="../assets/doc.css">
</head>
<body>
<div class="layout">
<aside class="sidebar">
<a class="brand" href="../index.html"><span class="dot"></span> Balinyaar docs</a>
<p class="tagline">Trust-first home-nursing marketplace · Iran</p>
<nav><div class="group"><div class="label">Start here</div><ul><li><a href="../index.html">Docs home</a></li><li><a href="../overview/platform-summary.html">Platform summary &amp; ground truths</a></li></ul></div><div class="group"><div class="label">Business requirements</div><ul><li><a href="../business/index.html">Overview &amp; MVP scope</a></li><li><a href="../business/01-actors-and-onboarding.html">1. Actors &amp; onboarding</a></li><li><a href="../business/02-nurse-verification.html">2. Nurse verification</a></li><li><a href="../business/03-service-catalog-and-pricing.html">3. Service catalog &amp; pricing</a></li><li><a href="../business/04-search-and-matching.html">4. Search &amp; matching</a></li><li><a href="../business/05-booking-and-scheduling.html">5. Booking &amp; scheduling</a></li><li><a href="../business/06-evv-and-service-delivery.html">6. EVV / service delivery</a></li><li><a href="../business/07-cancellation-and-refunds.html">7. Cancellation &amp; refunds</a></li><li><a href="../business/08-payments-and-escrow.html">8. Payments &amp; escrow</a></li><li><a href="../business/09-installments-bnpl.html">9. Installments / BNPL</a></li><li><a href="../business/10-payouts.html">10. Payouts to nurses</a></li><li><a href="../business/11-reviews-trust-and-safety.html">11. Reviews, trust &amp; safety</a></li><li><a href="../business/12-messaging-and-emergencies.html">12. Messaging &amp; emergencies</a></li><li><a href="../business/13-tax-invoicing-and-legal.html">13. Tax, invoicing &amp; legal</a></li><li><a href="../business/14-notifications-and-admin.html">14. Notifications &amp; admin</a></li></ul></div><div class="group"><div class="label">Database model</div><ul><li><a href="index.html">Overview &amp; decisions</a></li><li><a class="active" href="diagrams.html">Diagrams</a></li><li><a href="01-identity-and-access.html">1. Identity &amp; access</a></li><li><a href="02-geography.html">2. Geography</a></li><li><a href="03-services-and-pricing.html">3. Services &amp; pricing</a></li><li><a href="04-verification-and-credentials.html">4. Verification &amp; credentials</a></li><li><a href="05-booking-and-scheduling.html">5. Booking &amp; scheduling</a></li><li><a href="06-payments-ledger-and-refunds.html">6. Payments, ledger &amp; refunds</a></li><li><a href="07-payouts.html">7. Payouts</a></li><li><a href="08-bnpl.html">8. BNPL / installments</a></li><li><a href="09-messaging.html">9. Messaging</a></li><li><a href="10-reviews-and-records.html">10. Reviews &amp; records</a></li><li><a href="11-notifications.html">11. Notifications</a></li><li><a href="12-audit-config-and-reference.html">12. Audit, config &amp; reference</a></li><li><a href="13-partner-centers-and-future.html">13. Partner centers &amp; future</a></li></ul></div><div class="group"><div class="label">Payments deep-dive</div><ul><li><a href="../payments/index.html">Overview &amp; exec summary</a></li><li><a href="../payments/iranian-payment-reality.html">Iranian payment reality</a></li><li><a href="../payments/escrow-ledger.html">Escrow as a ledger</a></li><li><a href="../payments/bnpl-landscape.html">BNPL landscape &amp; finding</a></li><li><a href="../payments/cancellation-and-payout.html">Cancellation &amp; nurse payout</a></li><li><a href="../payments/integration-notes.html">Integration &amp; schema touchpoints</a></li><li><a href="../payments/sources.html">Recommendations &amp; sources</a></li></ul></div><div class="group"><div class="label">Research &amp; strategy</div><ul><li><a href="../research/index.html">Overview &amp; exec summary</a></li><li><a href="../research/market-and-competitors.html">Market &amp; competitors</a></li><li><a href="../research/problems-and-risks.html">Problems &amp; risks</a></li><li><a href="../research/verification.html">Verification (research)</a></li><li><a href="../research/legal-landscape.html">Legal landscape</a></li><li><a href="../research/go-to-market.html">Go-to-market &amp; sources</a></li></ul></div><div class="group"><div class="label">Notes &amp; more</div><ul><li><a href="../notes/open-questions.html">Open questions</a></li><li><a href="../notes/future-ideas.html">Future ideas</a></li><li><a href="../wireframes/index.html">Wireframes</a></li><li><a href="../fa/index.html">Farsi documents</a></li></ul></div></nav>
</aside>
<main class="main"><div class="content">
<div class="topbar"><button class="theme-toggle" type="button" onclick="__t()">theme</button></div>
<h1 id="diagrams">Diagrams</h1>
<p><a href="index.html">← Database Model</a></p>
<h3 id="1-domain-map-how-the-clusters-relate">1. Domain map — how the clusters relate <a class="anchor" href="#1-domain-map-how-the-clusters-relate" aria-hidden="true">#</a></h3>
<pre class="mermaid">flowchart LR
PARTNER["🏥 Partner Centers (launch)&lt;br/&gt;partner_centers"]
IDENTITY["🧑 Identity &amp; Access&lt;br/&gt;users · nurse_profiles · customer_profiles&lt;br/&gt;patients · customer_addresses · nurse_bank_accounts"]
GEO["📍 Geography&lt;br/&gt;provinces · cities · districts · nurse_service_areas"]
VERIFY["✅ Verification&lt;br/&gt;nurse_verifications · step_types · steps&lt;br/&gt;documents · nurse_credentials"]
SERVICES["🩺 Services &amp; Pricing&lt;br/&gt;service_categories · option_groups · option_values&lt;br/&gt;variants · variant_options · search_index · availability"]
BOOKING["📅 Booking &amp; Scheduling&lt;br/&gt;booking_requests · bookings · booking_sessions&lt;br/&gt;care_instructions · visit_verifications · cancellation_policies"]
PAY["💳 Payments &amp; Ledger&lt;br/&gt;payment_gateways · payment_transactions · webhook_events&lt;br/&gt;refunds · ledger_entries · nurse_clawbacks · invoices"]
BNPL["🧾 BNPL&lt;br/&gt;bnpl_transactions"]
PAYOUT["🏦 Payouts&lt;br/&gt;payout_batches · payouts · booking_links"]
REVIEW["⭐ Reviews &amp; Records&lt;br/&gt;reviews · review_tags · patient_care_records"]
MSG["💬 Messaging&lt;br/&gt;tickets · participants · messages"]
NOTIFY["🔔 Notifications&lt;br/&gt;notifications · support_alerts"]
AUDITCFG["📜 Audit &amp; Config&lt;br/&gt;audit_logs · system_events&lt;br/&gt;platform_configs · iranian_holidays"]
PARTNER -. "sponsors / merchant-of-record" .-&gt; VERIFY
IDENTITY --&gt; VERIFY
VERIFY --&gt; SERVICES
SERVICES --&gt; GEO
IDENTITY --&gt; BOOKING
SERVICES --&gt; BOOKING
BOOKING --&gt; PAY
PAY --&gt; BNPL
PAY --&gt; PAYOUT
BOOKING --&gt; REVIEW
BOOKING --&gt; MSG
PAY --&gt; NOTIFY
PAY --&gt; AUDITCFG</pre>
<h3 id="2-core-booking-spine-who-books-whom">2. Core booking spine (who books whom) <a class="anchor" href="#2-core-booking-spine-who-books-whom" aria-hidden="true">#</a></h3>
<pre class="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
}</pre>
<h3 id="3-payments-ledger-payouts">3. Payments, ledger &amp; payouts <a class="anchor" href="#3-payments-ledger-payouts" aria-hidden="true">#</a></h3>
<pre class="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
}</pre>
<h3 id="4-financial-lifecycle-escrow-payout-clawback">4. Financial lifecycle — escrow → payout → clawback <a class="anchor" href="#4-financial-lifecycle-escrow-payout-clawback" aria-hidden="true">#</a></h3>
<pre class="mermaid">flowchart TD
A["Family submits booking_request"] --&gt; B{"Nurse responds in time?"}
B --&gt;|"reject / expire"| X["request closed — no money moved"]
B --&gt;|"accept"| C["30-min payment window"]
C --&gt; D{"Payment method"}
D --&gt;|"Card (IPG)"| E["payment_transactions = succeeded"]
D --&gt;|"BNPL (SnappPay)"| F["bnpl_transactions = settled&lt;br/&gt;full amount minus provider commission"]
E --&gt; G["Ledger posting:&lt;br/&gt;DR escrow_held / CR nurse_payable + platform_revenue"]
F --&gt; G
G --&gt; H["Booking confirmed (escrow held)"]
H --&gt; I["Nurse EVV check-in / check-out per session"]
I --&gt; J["Booking completed"]
J --&gt; K["dispute_window_ends_at = completed_at + 72h"]
K --&gt; L{"Window passed &amp; no dispute?"}
L --&gt;|"yes"| M["payout_eligible"]
M --&gt; N["Weekly batch → PAYA to nurse IBAN&lt;br/&gt;payout = gross − balinyaar_commission"]
K -.-&gt;|"refund BEFORE payout"| O["Clean ledger reversal&lt;br/&gt;PSP refund / bnpl_revert"]
N --&gt; P{"Refund AFTER payout?"}
P --&gt;|"yes"| Q["nurse_clawbacks receivable&lt;br/&gt;netted next batch or written off"]
P --&gt;|"no"| Z["Settled and reconciled"]</pre>
<a class="back-to-top" href="#">↑ Back to top</a>
</div></main>
</div>
<script>
(function(){var k='balinyaar-docs-theme';var s=localStorage.getItem(k);
if(s)document.documentElement.setAttribute('data-theme',s);
else if(matchMedia('(prefers-color-scheme: dark)').matches)document.documentElement.setAttribute('data-theme','dark');})();
function __t(){var d=document.documentElement;var n=d.getAttribute('data-theme')==='dark'?'light':'dark';
d.setAttribute('data-theme',n);localStorage.setItem('balinyaar-docs-theme',n);}
</script>
<script type="module">
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
const dark = document.documentElement.getAttribute('data-theme') === 'dark';
mermaid.initialize({ startOnLoad: true, theme: dark ? 'dark' : 'neutral' });
</script>
</body>
</html>