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/business/index.html
+80
View File
@@ -0,0 +1,80 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Business Requirements — 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 class="active" href="index.html">Overview &amp; MVP scope</a></li><li><a href="01-actors-and-onboarding.html">1. Actors &amp; onboarding</a></li><li><a href="02-nurse-verification.html">2. Nurse verification</a></li><li><a href="03-service-catalog-and-pricing.html">3. Service catalog &amp; pricing</a></li><li><a href="04-search-and-matching.html">4. Search &amp; matching</a></li><li><a href="05-booking-and-scheduling.html">5. Booking &amp; scheduling</a></li><li><a href="06-evv-and-service-delivery.html">6. EVV / service delivery</a></li><li><a href="07-cancellation-and-refunds.html">7. Cancellation &amp; refunds</a></li><li><a href="08-payments-and-escrow.html">8. Payments &amp; escrow</a></li><li><a href="09-installments-bnpl.html">9. Installments / BNPL</a></li><li><a href="10-payouts.html">10. Payouts to nurses</a></li><li><a href="11-reviews-trust-and-safety.html">11. Reviews, trust &amp; safety</a></li><li><a href="12-messaging-and-emergencies.html">12. Messaging &amp; emergencies</a></li><li><a href="13-tax-invoicing-and-legal.html">13. Tax, invoicing &amp; legal</a></li><li><a href="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="../data-model/index.html">Overview &amp; decisions</a></li><li><a href="../data-model/diagrams.html">Diagrams</a></li><li><a href="../data-model/01-identity-and-access.html">1. Identity &amp; access</a></li><li><a href="../data-model/02-geography.html">2. Geography</a></li><li><a href="../data-model/03-services-and-pricing.html">3. Services &amp; pricing</a></li><li><a href="../data-model/04-verification-and-credentials.html">4. Verification &amp; credentials</a></li><li><a href="../data-model/05-booking-and-scheduling.html">5. Booking &amp; scheduling</a></li><li><a href="../data-model/06-payments-ledger-and-refunds.html">6. Payments, ledger &amp; refunds</a></li><li><a href="../data-model/07-payouts.html">7. Payouts</a></li><li><a href="../data-model/08-bnpl.html">8. BNPL / installments</a></li><li><a href="../data-model/09-messaging.html">9. Messaging</a></li><li><a href="../data-model/10-reviews-and-records.html">10. Reviews &amp; records</a></li><li><a href="../data-model/11-notifications.html">11. Notifications</a></li><li><a href="../data-model/12-audit-config-and-reference.html">12. Audit, config &amp; reference</a></li><li><a href="../data-model/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="business-requirements">Business Requirements</h1>
<blockquote><p><strong>Purpose.</strong> This document specifies the business requirements for <strong>Balinyaar</strong>, an MVP home-nursing marketplace in Iran where independent, individually-verified nurses list configurable services, families search and request a nurse, the nurse accepts, the family pays <em>through</em> the platform, the platform holds the money as an internal escrow ledger state, the nurse performs one or more visits with Electronic Visit Verification (EVV) check-in/out, and the platform pays the nurse weekly minus a commission. It is grounded in the verified payment/settlement research, the adversarial fact-checks, the database-model critiques, and the market/legal/verification research. It is written to be an MVP that is decisive but <strong>not naive</strong> about Iranian payment law, tax, and the realities of caring for vulnerable people at home. All monetary values are in <strong>IRR (Rials)</strong>; Toman is a display concern only and is converted to/from Rials solely at an external provider's API boundary.</p>
</blockquote>
<p><strong>Date:</strong> 2026-06-20</p>
<p>These sections assume the four <a href="../overview/platform-summary.html">cross-cutting ground truths</a>.</p>
<hr>
<h2 id="how-to-read-this-document">How to read this document <a class="anchor" href="#how-to-read-this-document" aria-hidden="true">#</a></h2>
<p>Each section covers one business area and states, in order:</p>
<ul>
<li><strong>(a) Business requirements</strong> — what the platform must do.</li>
<li><strong>(b) Iran-specific considerations</strong> — the local legal, fiscal, cultural, and infrastructural realities that shape the requirement.</li>
<li><strong>(c) MVP vs DEFERRED</strong> — an explicit callout of what ships at launch and what is intentionally postponed.</li>
<li><strong>(d) Supporting database entities</strong> — the entities (using the final names from the refined data model) that implement the requirement.</li>
</ul>
<hr>
<h2 id="areas">Areas <a class="anchor" href="#areas" aria-hidden="true">#</a></h2>
<ol>
<li><a href="01-actors-and-onboarding.html">Actors &amp; Onboarding</a> — three actor types, phone-OTP login, the customer/patient split, and role-staged KYC.</li>
<li><a href="02-nurse-verification.html">Nurse Verification &amp; Credentials</a> — the platform-owned, six-step verification pipeline and the structured credential registry.</li>
<li><a href="03-service-catalog-and-pricing.html">Service Catalog &amp; Pricing</a> — admin-defined catalog skeleton, nurse-priced variants, and the five price units.</li>
<li><a href="04-search-and-matching.html">Search &amp; Matching</a> — geo/category search, the denormalized search index, and same-gender caregiver matching.</li>
<li><a href="05-booking-and-scheduling.html">Booking &amp; Scheduling</a> — the request→accept→pay→confirm lifecycle and multi-session engagements.</li>
<li><a href="06-evv-and-service-delivery.html">EVV / Service Delivery</a> — Electronic Visit Verification check-in/out and payout gating on proof of service.</li>
<li><a href="07-cancellation-and-refunds.html">Cancellation &amp; Refunds</a> — tiered, snapshotted policies and admin-only, ticket-linked refunds.</li>
<li><a href="08-payments-and-escrow.html">Payments &amp; Escrow</a> — merchant-of-record card flow, the internal double-entry ledger, and webhook idempotency.</li>
<li><a href="09-installments-bnpl.html">Installments / BNPL</a> — full-upfront, provider-financed BNPL modeled as a single inbound settlement.</li>
<li><a href="10-payouts.html">Payouts to Nurses</a> — weekly batches gated on EVV + dispute window, clawbacks, and holiday-aware scheduling.</li>
<li><a href="11-reviews-trust-and-safety.html">Reviews, Trust &amp; Safety</a> — one-per-booking moderated reviews, low-rating alerting, and incident handling.</li>
<li><a href="12-messaging-and-emergencies.html">Messaging &amp; On-Site Emergencies</a> — ticket-only communication and the on-site emergency playbook.</li>
<li><a href="13-tax-invoicing-and-legal.html">Tax, Invoicing &amp; Legal</a> — nurse-as-seller / platform-as-commission-seller split, VAT, and the partner-center launch vehicle.</li>
<li><a href="14-notifications-and-admin.html">Notifications &amp; Admin / Backoffice</a> — in-app notifications, the admin operational spine, RBAC, and the audit trail.</li>
</ol>
<hr>
<h2 id="appendix-mvp-vs-deferred-at-a-glance">Appendix — MVP vs Deferred at a glance <a class="anchor" href="#appendix-mvp-vs-deferred-at-a-glance" aria-hidden="true">#</a></h2>
<div class="table-wrap"><table><thead><tr><th>Area</th><th>MVP</th><th>Deferred</th></tr></thead><tbody>
<tr><td>Onboarding</td><td>phone-OTP; customer/nurse/admin; patient split</td><td>customer KYC; org self-onboarding; push</td></tr>
<tr><td>Verification</td><td>6-step data-driven pipeline; <code>nurse_credentials</code>; IBAN ownership</td><td>MoH/INO API; liability-insurance step; ML fraud</td></tr>
<tr><td>Catalog</td><td>admin categories/options; nurse variants &amp; price units</td><td>holiday/surge pricing; companionship tier</td></tr>
<tr><td>Search</td><td>geo + category; <code>nurse_search_index</code>; same-gender filter</td><td>map discovery; availability hard-filter</td></tr>
<tr><td>Booking</td><td>request→accept→pay→confirm; <code>booking_sessions</code> multi-visit</td><td>recurring schedules; milestone-payment UX</td></tr>
<tr><td>EVV</td><td>per-session GPS check-in/out; payout gating</td><td>geofencing; tele-check-ins; cameras</td></tr>
<tr><td>Cancellation</td><td>tiered policy + snapshot; admin/ticket refunds; per-session</td><td>auto no-show penalty; self-service refunds</td></tr>
<tr><td>Payments/Escrow</td><td>ledger escrow; <code>payment_webhook_events</code>; provider abstraction</td><td>nurse wallet; multi-PSP live; bank escrow product</td></tr>
<tr><td>BNPL</td><td>full-upfront <code>bnpl_transactions</code>; provider-revert refunds</td><td>installment tracking (cut); tranched settlement; multi-provider</td></tr>
<tr><td>Payouts</td><td>weekly batches; clawbacks; holiday-aware; verified IBAN</td><td>instant withdrawal; per-nurse frequency</td></tr>
<tr><td>Reviews</td><td>one-per-booking; moderation; low-rating alerts</td><td>two-way reviews; tag aggregation; <code>incidents</code></td></tr>
<tr><td>Messaging</td><td>ticket-only; coordination ticket; emergency playbook</td><td>live chat; emergency-event entity</td></tr>
<tr><td>Tax/Legal</td><td><code>partner_centers</code>; minimal <code>invoices</code>; 10% VAT on commission; e-namad</td><td>full مودیان automation; nurse-side invoicing; B2B</td></tr>
<tr><td>Notifications/Admin</td><td>in-app + retention; verify/refund/payout tooling; RBAC</td><td>push; analytics warehouse; ML console</td></tr>
</tbody></table></div>
<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>
</body>
</html>