clean and refine product docs structure
This commit is contained in:
hamid
@@ -0,0 +1,60 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<title>1. Actors & Onboarding — 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 & ground truths</a></li></ul></div><div class="group"><div class="label">Business requirements</div><ul><li><a href="index.html">Overview & MVP scope</a></li><li><a class="active" href="01-actors-and-onboarding.html">1. Actors & 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 & pricing</a></li><li><a href="04-search-and-matching.html">4. Search & matching</a></li><li><a href="05-booking-and-scheduling.html">5. Booking & 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 & refunds</a></li><li><a href="08-payments-and-escrow.html">8. Payments & 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 & safety</a></li><li><a href="12-messaging-and-emergencies.html">12. Messaging & emergencies</a></li><li><a href="13-tax-invoicing-and-legal.html">13. Tax, invoicing & legal</a></li><li><a href="14-notifications-and-admin.html">14. Notifications & admin</a></li></ul></div><div class="group"><div class="label">Database model</div><ul><li><a href="../data-model/index.html">Overview & 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 & 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 & pricing</a></li><li><a href="../data-model/04-verification-and-credentials.html">4. Verification & credentials</a></li><li><a href="../data-model/05-booking-and-scheduling.html">5. Booking & scheduling</a></li><li><a href="../data-model/06-payments-ledger-and-refunds.html">6. Payments, ledger & 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 & 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 & reference</a></li><li><a href="../data-model/13-partner-centers-and-future.html">13. Partner centers & future</a></li></ul></div><div class="group"><div class="label">Payments deep-dive</div><ul><li><a href="../payments/index.html">Overview & 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 & finding</a></li><li><a href="../payments/cancellation-and-payout.html">Cancellation & nurse payout</a></li><li><a href="../payments/integration-notes.html">Integration & schema touchpoints</a></li><li><a href="../payments/sources.html">Recommendations & sources</a></li></ul></div><div class="group"><div class="label">Research & strategy</div><ul><li><a href="../research/index.html">Overview & exec summary</a></li><li><a href="../research/market-and-competitors.html">Market & competitors</a></li><li><a href="../research/problems-and-risks.html">Problems & 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 & sources</a></li></ul></div><div class="group"><div class="label">Notes & 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="1-actors-onboarding">1. Actors & Onboarding</h1>
|
||||
<p><a href="index.html">← Business Requirements</a></p>
|
||||
<h2 id="a-business-requirements">(a) Business requirements <a class="anchor" href="#a-business-requirements" aria-hidden="true">#</a></h2>
|
||||
<ul>
|
||||
<li>Three actor types: <strong>customer</strong> (the family member / payer), <strong>nurse</strong> (the independent caregiver / seller), and <strong>admin</strong> (Balinyaar back-office staff: support, finance, moderation, super-admin).</li>
|
||||
<li><strong>Phone number is the primary login credential.</strong> Authentication is <strong>phone-OTP</strong> (one-time code by SMS). Email is optional/secondary (required only for admin accounts).</li>
|
||||
<li>The <strong>patient</strong> (care recipient) is a first-class entity distinct from the customer, because the payer (an adult child, a spouse) is frequently not the patient (an elderly parent, a newborn, a post-surgical adult). A customer may register multiple patients.</li>
|
||||
<li><strong>KYC timing is role- and risk-staged, not up-front-for-everyone:</strong><ul>
|
||||
<li>A <strong>customer</strong> can register and browse with only a verified phone (OTP). National-ID KYC for customers is anti-fraud only and is <strong>deferred</strong> at launch.</li>
|
||||
<li>A <strong>nurse</strong> must complete the full verification pipeline (Section 2) before any of their service variants become bookable. <code>national_id</code> is populated only after the identity step passes.</li>
|
||||
<li>An <strong>admin</strong> is provisioned internally with RBAC roles.</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>Each successful login creates a refresh-token session that can be revoked (logout, stolen-token detection).</li>
|
||||
</ul>
|
||||
<h2 id="b-iran-specific-considerations">(b) Iran-specific considerations <a class="anchor" href="#b-iran-specific-considerations" aria-hidden="true">#</a></h2>
|
||||
<ul>
|
||||
<li>Phone-OTP is the dominant Iranian login norm and is also the anchor for <strong>Shahkar</strong> SIM↔national-ID binding (Section 2).</li>
|
||||
<li>Storing <code>national_id</code> only post-KYC matches the reality that identity is verified through gated vendor APIs, not collected casually at signup.</li>
|
||||
<li>Cultural reality: the booking flow must let a family member act on behalf of a patient who cannot self-advocate (infant, dementia, post-anesthesia). The customer/patient split is essential, not cosmetic.</li>
|
||||
</ul>
|
||||
<h2 id="c-mvp-vs-deferred">(c) MVP vs DEFERRED <a class="anchor" href="#c-mvp-vs-deferred" aria-hidden="true">#</a></h2>
|
||||
<ul>
|
||||
<li><strong>MVP:</strong> phone-OTP login; customer/nurse/admin roles; customer→patient (1:N); session management; admin RBAC; nurse onboarding gated on verification.</li>
|
||||
<li><strong>DEFERRED:</strong> customer national-ID KYC (<code>customer_profiles.national_id_verified_at</code> exists but is optional/unused at launch); push notifications; social login; nursing-company (organization) self-onboarding.</li>
|
||||
</ul>
|
||||
<h2 id="d-supporting-database-entities">(d) Supporting database entities <a class="anchor" href="#d-supporting-database-entities" aria-hidden="true">#</a></h2>
|
||||
<p><code>users</code>, <code>user_sessions</code>, <code>roles</code>, <code>user_roles</code>, <code>nurse_profiles</code>, <code>customer_profiles</code>, <code>patients</code>, <code>customer_addresses</code>.</p>
|
||||
<blockquote><p><strong>Related:</strong> Data model — <a href="../data-model/01-identity-and-access.html">Identity & Access</a>.</p>
|
||||
</blockquote>
|
||||
<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>
|
||||
@@ -0,0 +1,27 @@
|
||||
# 1. Actors & Onboarding
|
||||
|
||||
[← Business Requirements](index.md)
|
||||
|
||||
## (a) Business requirements
|
||||
- Three actor types: **customer** (the family member / payer), **nurse** (the independent caregiver / seller), and **admin** (Balinyaar back-office staff: support, finance, moderation, super-admin).
|
||||
- **Phone number is the primary login credential.** Authentication is **phone-OTP** (one-time code by SMS). Email is optional/secondary (required only for admin accounts).
|
||||
- The **patient** (care recipient) is a first-class entity distinct from the customer, because the payer (an adult child, a spouse) is frequently not the patient (an elderly parent, a newborn, a post-surgical adult). A customer may register multiple patients.
|
||||
- **KYC timing is role- and risk-staged, not up-front-for-everyone:**
|
||||
- A **customer** can register and browse with only a verified phone (OTP). National-ID KYC for customers is anti-fraud only and is **deferred** at launch.
|
||||
- A **nurse** must complete the full verification pipeline (Section 2) before any of their service variants become bookable. `national_id` is populated only after the identity step passes.
|
||||
- An **admin** is provisioned internally with RBAC roles.
|
||||
- Each successful login creates a refresh-token session that can be revoked (logout, stolen-token detection).
|
||||
|
||||
## (b) Iran-specific considerations
|
||||
- Phone-OTP is the dominant Iranian login norm and is also the anchor for **Shahkar** SIM↔national-ID binding (Section 2).
|
||||
- Storing `national_id` only post-KYC matches the reality that identity is verified through gated vendor APIs, not collected casually at signup.
|
||||
- Cultural reality: the booking flow must let a family member act on behalf of a patient who cannot self-advocate (infant, dementia, post-anesthesia). The customer/patient split is essential, not cosmetic.
|
||||
|
||||
## (c) MVP vs DEFERRED
|
||||
- **MVP:** phone-OTP login; customer/nurse/admin roles; customer→patient (1:N); session management; admin RBAC; nurse onboarding gated on verification.
|
||||
- **DEFERRED:** customer national-ID KYC (`customer_profiles.national_id_verified_at` exists but is optional/unused at launch); push notifications; social login; nursing-company (organization) self-onboarding.
|
||||
|
||||
## (d) Supporting database entities
|
||||
`users`, `user_sessions`, `roles`, `user_roles`, `nurse_profiles`, `customer_profiles`, `patients`, `customer_addresses`.
|
||||
|
||||
> **Related:** Data model — [Identity & Access](../data-model/01-identity-and-access.md).
|
||||
@@ -0,0 +1,62 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<title>2. Nurse Verification & Credentials — 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 & ground truths</a></li></ul></div><div class="group"><div class="label">Business requirements</div><ul><li><a href="index.html">Overview & MVP scope</a></li><li><a href="01-actors-and-onboarding.html">1. Actors & onboarding</a></li><li><a class="active" href="02-nurse-verification.html">2. Nurse verification</a></li><li><a href="03-service-catalog-and-pricing.html">3. Service catalog & pricing</a></li><li><a href="04-search-and-matching.html">4. Search & matching</a></li><li><a href="05-booking-and-scheduling.html">5. Booking & 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 & refunds</a></li><li><a href="08-payments-and-escrow.html">8. Payments & 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 & safety</a></li><li><a href="12-messaging-and-emergencies.html">12. Messaging & emergencies</a></li><li><a href="13-tax-invoicing-and-legal.html">13. Tax, invoicing & legal</a></li><li><a href="14-notifications-and-admin.html">14. Notifications & admin</a></li></ul></div><div class="group"><div class="label">Database model</div><ul><li><a href="../data-model/index.html">Overview & 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 & 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 & pricing</a></li><li><a href="../data-model/04-verification-and-credentials.html">4. Verification & credentials</a></li><li><a href="../data-model/05-booking-and-scheduling.html">5. Booking & scheduling</a></li><li><a href="../data-model/06-payments-ledger-and-refunds.html">6. Payments, ledger & 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 & 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 & reference</a></li><li><a href="../data-model/13-partner-centers-and-future.html">13. Partner centers & future</a></li></ul></div><div class="group"><div class="label">Payments deep-dive</div><ul><li><a href="../payments/index.html">Overview & 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 & finding</a></li><li><a href="../payments/cancellation-and-payout.html">Cancellation & nurse payout</a></li><li><a href="../payments/integration-notes.html">Integration & schema touchpoints</a></li><li><a href="../payments/sources.html">Recommendations & sources</a></li></ul></div><div class="group"><div class="label">Research & strategy</div><ul><li><a href="../research/index.html">Overview & exec summary</a></li><li><a href="../research/market-and-competitors.html">Market & competitors</a></li><li><a href="../research/problems-and-risks.html">Problems & 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 & sources</a></li></ul></div><div class="group"><div class="label">Notes & 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="2-nurse-verification-credentials">2. Nurse Verification & Credentials</h1>
|
||||
<p><a href="index.html">← Business Requirements</a></p>
|
||||
<h2 id="a-business-requirements">(a) Business requirements <a class="anchor" href="#a-business-requirements" aria-hidden="true">#</a></h2>
|
||||
<p>Verified trust is the <strong>entire brand</strong>. Vetting is <strong>platform-owned, non-optional, and performed at the authoritative source</strong> — never delegated to families, and never marketed as a check the platform does not actually perform. A nurse is bookable only after all <em>required</em> verification steps pass.</p>
|
||||
<p>The pipeline is <strong>data-driven</strong>: the set of steps lives as rows in <code>verification_step_types</code> (not a code enum), so a new regulatory requirement (e.g., professional liability insurance) is one INSERT, not a migration. Each step can be <strong>automated</strong> (a KYC vendor API call) or <strong>manual</strong> (admin reviews an uploaded document). The aggregate <code>nurse_verifications</code> record rolls the step outcomes into a single status; <code>nurse_profiles.is_verified</code> flips to true <strong>only inside the same transaction</strong> that confirms every required step is <code>passed</code>.</p>
|
||||
<p>The verification steps:</p>
|
||||
<ol>
|
||||
<li><strong>Identity (KYC) — automated.</strong> Match person ↔ کد ملی (national ID) ↔ phone ↔ face via one Iranian KYC vendor: national-ID validity/name match + photo/video <strong>liveness</strong> against the national-card / civil-registry (ثبت احوال) photo. Binds the profile to a real identity and a liveness selfie to defeat the stolen-identity / alias fraud pattern.</li>
|
||||
<li><strong>Shahkar phone↔national-id binding — automated.</strong> Confirm the login SIM is registered to the nurse's own کد ملی. The binding result (when, which vendor, the reference) is recorded, and <strong>re-verification is triggered on phone change</strong>. The shared-SIM failure mode (a SIM owned by a family member) is an explicit, handled state, not an undefined edge case.</li>
|
||||
<li><strong>MoH پروانه صلاحیت حرفهای (professional-competency license) — the single most important credential.</strong> It is the MoH-mandated license for in-home nursing and <strong>already bundles the criminal-record (سوء پیشینه) screen</strong> plus scientific/ethical/health vetting. Verified against the MoH source (Rn.behdasht.gov.ir). No public B2B API exists, so the realistic method at launch is <strong>nurse-uploaded document + manual admin verification against the official record</strong>.</li>
|
||||
<li><strong>نظام پرستاری (Iranian Nursing Organization / INO) membership — cross-check.</strong> The INO membership number is captured and cross-checked (ino.ir) as a second source. Manual at launch.</li>
|
||||
<li><strong>عدم سوء پیشینه (criminal-record certificate).</strong> Consent-gated to the individual (obtained by the nurse via adliran.ir / their own ثنا password); <strong>no company/employer API exists</strong>. The nurse uploads it; it is <strong>time-limited</strong> — on expiry the step reverts to pending and a support alert is raised. Partly covered already by credential #3.</li>
|
||||
<li><strong>IBAN ownership verification.</strong> The payout IBAN (Sheba) must be proven to belong to the verified nurse — the account-holder national ID must equal the verified nurse national ID. Done via automated IBAN-ownership inquiry (استعلام شبا) where available, gating the <strong>first payout</strong>, not merely an admin eyeballing the number. Prevents paying a nurse's earnings into a third party's account (money-mule risk).</li>
|
||||
</ol>
|
||||
<p><strong>Structured credential registry.</strong> Beyond opaque uploaded files, the actual license <strong>numbers</strong>, issuing authority, holder-name-as-printed, and issue/expiry dates are stored as typed, queryable rows in <code>nurse_credentials</code>. This powers renewal/expiry alerts, the public "verified" trust badge, cross-checking against official portals, and audit defensibility — and survives the future arrival of an MoH/INO API.</p>
|
||||
<p><strong>Continuous monitoring</strong>, not one-and-done: license validity and the criminal-record certificate are periodically re-verified; Shahkar is re-run on phone change. Expiring credentials raise <code>support_alerts</code>.</p>
|
||||
<h2 id="b-iran-specific-considerations">(b) Iran-specific considerations <a class="anchor" href="#b-iran-specific-considerations" aria-hidden="true">#</a></h2>
|
||||
<ul>
|
||||
<li>The license layer is <strong>fragmented across regulators</strong> (MoH vs INO) and has <strong>no public B2B API</strong> — manual verification against the official portal is the realistic MVP method; the structured registry makes that defensible and renewable.</li>
|
||||
<li>The criminal-record check is <strong>consent-gated to the person</strong> and cannot be pulled by a company — hence nurse-uploaded + re-requested periodically, leaning on the MoH license which already embeds it.</li>
|
||||
<li>Identity (Shahkar, liveness, national-ID match) is the <strong>easy</strong> layer because a competitive market of Iranian e-KYC vendors (Finnotech, U-ID, Jibbit, Farashensa, Verify, Kavoshak) already holds the regulator-gated upstream agreements. <strong>Buy this, don't build it.</strong></li>
|
||||
<li>Document forgery is the documented attack (the "imposter nurse" pattern): verify at source, bind to national ID + liveness, never trust an uploaded PDF alone.</li>
|
||||
</ul>
|
||||
<h2 id="c-mvp-vs-deferred">(c) MVP vs DEFERRED <a class="anchor" href="#c-mvp-vs-deferred" aria-hidden="true">#</a></h2>
|
||||
<ul>
|
||||
<li><strong>MVP:</strong> all six steps; data-driven <code>verification_step_types</code>; structured <code>nurse_credentials</code> registry; manual MoH/INO verification; nurse-uploaded عدم سوء پیشینه with expiry; automated identity + Shahkar + IBAN-ownership via one KYC vendor; expiry-driven re-verification alerts; transactional <code>is_verified</code>.</li>
|
||||
<li><strong>DEFERRED:</strong> automated MoH/INO license lookup (pending a B2B API); ML-driven fraud scoring (<code>fraud_flags</code> is modeled but inactive); professional-liability-insurance step (addable as a row when required).</li>
|
||||
</ul>
|
||||
<h2 id="d-supporting-database-entities">(d) Supporting database entities <a class="anchor" href="#d-supporting-database-entities" aria-hidden="true">#</a></h2>
|
||||
<p><code>nurse_verifications</code>, <code>verification_step_types</code>, <code>verification_steps</code>, <code>verification_documents</code>, <strong><code>nurse_credentials</code></strong> (structured license registry), <code>nurse_bank_accounts</code> (IBAN ownership), <code>support_alerts</code> (expiry/renewal), <code>audit_logs</code>.</p>
|
||||
<blockquote><p><strong>Related:</strong> Data model — <a href="../data-model/04-verification-and-credentials.html">Verification & Credentials</a>; Research — <a href="../research/verification.html">Verification</a>.</p>
|
||||
</blockquote>
|
||||
<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>
|
||||
@@ -0,0 +1,36 @@
|
||||
# 2. Nurse Verification & Credentials
|
||||
|
||||
[← Business Requirements](index.md)
|
||||
|
||||
## (a) Business requirements
|
||||
Verified trust is the **entire brand**. Vetting is **platform-owned, non-optional, and performed at the authoritative source** — never delegated to families, and never marketed as a check the platform does not actually perform. A nurse is bookable only after all *required* verification steps pass.
|
||||
|
||||
The pipeline is **data-driven**: the set of steps lives as rows in `verification_step_types` (not a code enum), so a new regulatory requirement (e.g., professional liability insurance) is one INSERT, not a migration. Each step can be **automated** (a KYC vendor API call) or **manual** (admin reviews an uploaded document). The aggregate `nurse_verifications` record rolls the step outcomes into a single status; `nurse_profiles.is_verified` flips to true **only inside the same transaction** that confirms every required step is `passed`.
|
||||
|
||||
The verification steps:
|
||||
|
||||
1. **Identity (KYC) — automated.** Match person ↔ کد ملی (national ID) ↔ phone ↔ face via one Iranian KYC vendor: national-ID validity/name match + photo/video **liveness** against the national-card / civil-registry (ثبت احوال) photo. Binds the profile to a real identity and a liveness selfie to defeat the stolen-identity / alias fraud pattern.
|
||||
2. **Shahkar phone↔national-id binding — automated.** Confirm the login SIM is registered to the nurse's own کد ملی. The binding result (when, which vendor, the reference) is recorded, and **re-verification is triggered on phone change**. The shared-SIM failure mode (a SIM owned by a family member) is an explicit, handled state, not an undefined edge case.
|
||||
3. **MoH پروانه صلاحیت حرفهای (professional-competency license) — the single most important credential.** It is the MoH-mandated license for in-home nursing and **already bundles the criminal-record (سوء پیشینه) screen** plus scientific/ethical/health vetting. Verified against the MoH source (Rn.behdasht.gov.ir). No public B2B API exists, so the realistic method at launch is **nurse-uploaded document + manual admin verification against the official record**.
|
||||
4. **نظام پرستاری (Iranian Nursing Organization / INO) membership — cross-check.** The INO membership number is captured and cross-checked (ino.ir) as a second source. Manual at launch.
|
||||
5. **عدم سوء پیشینه (criminal-record certificate).** Consent-gated to the individual (obtained by the nurse via adliran.ir / their own ثنا password); **no company/employer API exists**. The nurse uploads it; it is **time-limited** — on expiry the step reverts to pending and a support alert is raised. Partly covered already by credential #3.
|
||||
6. **IBAN ownership verification.** The payout IBAN (Sheba) must be proven to belong to the verified nurse — the account-holder national ID must equal the verified nurse national ID. Done via automated IBAN-ownership inquiry (استعلام شبا) where available, gating the **first payout**, not merely an admin eyeballing the number. Prevents paying a nurse's earnings into a third party's account (money-mule risk).
|
||||
|
||||
**Structured credential registry.** Beyond opaque uploaded files, the actual license **numbers**, issuing authority, holder-name-as-printed, and issue/expiry dates are stored as typed, queryable rows in `nurse_credentials`. This powers renewal/expiry alerts, the public "verified" trust badge, cross-checking against official portals, and audit defensibility — and survives the future arrival of an MoH/INO API.
|
||||
|
||||
**Continuous monitoring**, not one-and-done: license validity and the criminal-record certificate are periodically re-verified; Shahkar is re-run on phone change. Expiring credentials raise `support_alerts`.
|
||||
|
||||
## (b) Iran-specific considerations
|
||||
- The license layer is **fragmented across regulators** (MoH vs INO) and has **no public B2B API** — manual verification against the official portal is the realistic MVP method; the structured registry makes that defensible and renewable.
|
||||
- The criminal-record check is **consent-gated to the person** and cannot be pulled by a company — hence nurse-uploaded + re-requested periodically, leaning on the MoH license which already embeds it.
|
||||
- Identity (Shahkar, liveness, national-ID match) is the **easy** layer because a competitive market of Iranian e-KYC vendors (Finnotech, U-ID, Jibbit, Farashensa, Verify, Kavoshak) already holds the regulator-gated upstream agreements. **Buy this, don't build it.**
|
||||
- Document forgery is the documented attack (the "imposter nurse" pattern): verify at source, bind to national ID + liveness, never trust an uploaded PDF alone.
|
||||
|
||||
## (c) MVP vs DEFERRED
|
||||
- **MVP:** all six steps; data-driven `verification_step_types`; structured `nurse_credentials` registry; manual MoH/INO verification; nurse-uploaded عدم سوء پیشینه with expiry; automated identity + Shahkar + IBAN-ownership via one KYC vendor; expiry-driven re-verification alerts; transactional `is_verified`.
|
||||
- **DEFERRED:** automated MoH/INO license lookup (pending a B2B API); ML-driven fraud scoring (`fraud_flags` is modeled but inactive); professional-liability-insurance step (addable as a row when required).
|
||||
|
||||
## (d) Supporting database entities
|
||||
`nurse_verifications`, `verification_step_types`, `verification_steps`, `verification_documents`, **`nurse_credentials`** (structured license registry), `nurse_bank_accounts` (IBAN ownership), `support_alerts` (expiry/renewal), `audit_logs`.
|
||||
|
||||
> **Related:** Data model — [Verification & Credentials](../data-model/04-verification-and-credentials.md); Research — [Verification](../research/verification.md).
|
||||
@@ -0,0 +1,55 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<title>3. Service Catalog & Pricing — 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 & ground truths</a></li></ul></div><div class="group"><div class="label">Business requirements</div><ul><li><a href="index.html">Overview & MVP scope</a></li><li><a href="01-actors-and-onboarding.html">1. Actors & onboarding</a></li><li><a href="02-nurse-verification.html">2. Nurse verification</a></li><li><a class="active" href="03-service-catalog-and-pricing.html">3. Service catalog & pricing</a></li><li><a href="04-search-and-matching.html">4. Search & matching</a></li><li><a href="05-booking-and-scheduling.html">5. Booking & 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 & refunds</a></li><li><a href="08-payments-and-escrow.html">8. Payments & 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 & safety</a></li><li><a href="12-messaging-and-emergencies.html">12. Messaging & emergencies</a></li><li><a href="13-tax-invoicing-and-legal.html">13. Tax, invoicing & legal</a></li><li><a href="14-notifications-and-admin.html">14. Notifications & admin</a></li></ul></div><div class="group"><div class="label">Database model</div><ul><li><a href="../data-model/index.html">Overview & 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 & 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 & pricing</a></li><li><a href="../data-model/04-verification-and-credentials.html">4. Verification & credentials</a></li><li><a href="../data-model/05-booking-and-scheduling.html">5. Booking & scheduling</a></li><li><a href="../data-model/06-payments-ledger-and-refunds.html">6. Payments, ledger & 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 & 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 & reference</a></li><li><a href="../data-model/13-partner-centers-and-future.html">13. Partner centers & future</a></li></ul></div><div class="group"><div class="label">Payments deep-dive</div><ul><li><a href="../payments/index.html">Overview & 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 & finding</a></li><li><a href="../payments/cancellation-and-payout.html">Cancellation & nurse payout</a></li><li><a href="../payments/integration-notes.html">Integration & schema touchpoints</a></li><li><a href="../payments/sources.html">Recommendations & sources</a></li></ul></div><div class="group"><div class="label">Research & strategy</div><ul><li><a href="../research/index.html">Overview & exec summary</a></li><li><a href="../research/market-and-competitors.html">Market & competitors</a></li><li><a href="../research/problems-and-risks.html">Problems & 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 & sources</a></li></ul></div><div class="group"><div class="label">Notes & 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="3-service-catalog-pricing">3. Service Catalog & Pricing</h1>
|
||||
<p><a href="index.html">← Business Requirements</a></p>
|
||||
<h2 id="a-business-requirements">(a) Business requirements <a class="anchor" href="#a-business-requirements" aria-hidden="true">#</a></h2>
|
||||
<ul>
|
||||
<li><strong>Admin defines the catalog skeleton:</strong> top-level <strong>service categories</strong> (e.g., مراقبت از سالمند / Elderly Care, مراقبت پس از جراحی / Post-Surgery Recovery, مراقبت از نوزاد / Infant Care, مدیریت بیماری مزمن / Chronic Illness Management) and <strong>configurable option dimensions</strong> as admin-managed <strong>option groups</strong> (e.g., تعداد بیمار / patient count, نوع شیفت / shift type) each with concrete <strong>option values</strong> (e.g., ۱ نفر, ۲ نفر, شبانهروزی). Admin can add new dimensions without a schema change.</li>
|
||||
<li><strong>Each nurse defines their own offerings as variants.</strong> A <strong>variant</strong> is the atomic bookable unit: a category + a chosen combination of option values + the nurse's <strong>own price</strong> and <strong>price unit</strong>. A nurse may have many variants per category, one per combination they choose to offer and price independently.</li>
|
||||
<li><strong>Price units</strong> must support the real shapes of home nursing: <code>per_hour</code>, <code>per_session</code>, <code>per_half_day</code>, <code>per_day</code>, and <code>per_24h</code> (شبانهروزی / live-in). For hourly variants an estimated duration helps the customer estimate total cost.</li>
|
||||
<li>The variant <code>display_name</code> auto-generates from option labels but is nurse-editable. Nurses can deactivate (not delete) a variant; deactivated variants cannot be booked.</li>
|
||||
<li>Catalog and prices are <strong>snapshotted onto the booking</strong> at booking time (<code>variant_snapshot_json</code>) so historical records survive later edits.</li>
|
||||
</ul>
|
||||
<h2 id="b-iran-specific-considerations">(b) Iran-specific considerations <a class="anchor" href="#b-iran-specific-considerations" aria-hidden="true">#</a></h2>
|
||||
<ul>
|
||||
<li>Iranian competitors sell exactly these shapes — hourly / daily / 24-hour (شبانهروزی) shifts and multi-day packages — so <code>per_24h</code> and <code>per_day</code> are first-class, not edge cases.</li>
|
||||
<li>Competitor pricing is opaque and "توافقی" (negotiable); <strong>transparent, upfront, nurse-set pricing is a deliberate differentiator</strong> families value.</li>
|
||||
<li>All catalog tables carry <code>name_fa</code> / <code>name_en</code> pairs (Persian primary).</li>
|
||||
</ul>
|
||||
<h2 id="c-mvp-vs-deferred">(c) MVP vs DEFERRED <a class="anchor" href="#c-mvp-vs-deferred" aria-hidden="true">#</a></h2>
|
||||
<ul>
|
||||
<li><strong>MVP:</strong> admin categories + option groups/values; nurse variants with own price + price unit across all five units; activate/deactivate; snapshotting.</li>
|
||||
<li><strong>DEFERRED:</strong> holiday/surge pricing rules; a lighter "companionship / daily-living" tier (modeled as a future category); dynamic/tiered commission per category.</li>
|
||||
</ul>
|
||||
<h2 id="d-supporting-database-entities">(d) Supporting database entities <a class="anchor" href="#d-supporting-database-entities" aria-hidden="true">#</a></h2>
|
||||
<p><code>service_categories</code>, <code>service_option_groups</code>, <code>service_option_values</code>, <code>nurse_service_variants</code> (carries <code>price</code>, <code>price_unit</code>), <code>nurse_service_variant_options</code>.</p>
|
||||
<blockquote><p><strong>Related:</strong> Data model — <a href="../data-model/03-services-and-pricing.html">Services & Pricing</a>.</p>
|
||||
</blockquote>
|
||||
<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>
|
||||
@@ -0,0 +1,24 @@
|
||||
# 3. Service Catalog & Pricing
|
||||
|
||||
[← Business Requirements](index.md)
|
||||
|
||||
## (a) Business requirements
|
||||
- **Admin defines the catalog skeleton:** top-level **service categories** (e.g., مراقبت از سالمند / Elderly Care, مراقبت پس از جراحی / Post-Surgery Recovery, مراقبت از نوزاد / Infant Care, مدیریت بیماری مزمن / Chronic Illness Management) and **configurable option dimensions** as admin-managed **option groups** (e.g., تعداد بیمار / patient count, نوع شیفت / shift type) each with concrete **option values** (e.g., ۱ نفر, ۲ نفر, شبانهروزی). Admin can add new dimensions without a schema change.
|
||||
- **Each nurse defines their own offerings as variants.** A **variant** is the atomic bookable unit: a category + a chosen combination of option values + the nurse's **own price** and **price unit**. A nurse may have many variants per category, one per combination they choose to offer and price independently.
|
||||
- **Price units** must support the real shapes of home nursing: `per_hour`, `per_session`, `per_half_day`, `per_day`, and `per_24h` (شبانهروزی / live-in). For hourly variants an estimated duration helps the customer estimate total cost.
|
||||
- The variant `display_name` auto-generates from option labels but is nurse-editable. Nurses can deactivate (not delete) a variant; deactivated variants cannot be booked.
|
||||
- Catalog and prices are **snapshotted onto the booking** at booking time (`variant_snapshot_json`) so historical records survive later edits.
|
||||
|
||||
## (b) Iran-specific considerations
|
||||
- Iranian competitors sell exactly these shapes — hourly / daily / 24-hour (شبانهروزی) shifts and multi-day packages — so `per_24h` and `per_day` are first-class, not edge cases.
|
||||
- Competitor pricing is opaque and "توافقی" (negotiable); **transparent, upfront, nurse-set pricing is a deliberate differentiator** families value.
|
||||
- All catalog tables carry `name_fa` / `name_en` pairs (Persian primary).
|
||||
|
||||
## (c) MVP vs DEFERRED
|
||||
- **MVP:** admin categories + option groups/values; nurse variants with own price + price unit across all five units; activate/deactivate; snapshotting.
|
||||
- **DEFERRED:** holiday/surge pricing rules; a lighter "companionship / daily-living" tier (modeled as a future category); dynamic/tiered commission per category.
|
||||
|
||||
## (d) Supporting database entities
|
||||
`service_categories`, `service_option_groups`, `service_option_values`, `nurse_service_variants` (carries `price`, `price_unit`), `nurse_service_variant_options`.
|
||||
|
||||
> **Related:** Data model — [Services & Pricing](../data-model/03-services-and-pricing.md).
|
||||
@@ -0,0 +1,54 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<title>4. Search & Matching — 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 & ground truths</a></li></ul></div><div class="group"><div class="label">Business requirements</div><ul><li><a href="index.html">Overview & MVP scope</a></li><li><a href="01-actors-and-onboarding.html">1. Actors & 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 & pricing</a></li><li><a class="active" href="04-search-and-matching.html">4. Search & matching</a></li><li><a href="05-booking-and-scheduling.html">5. Booking & 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 & refunds</a></li><li><a href="08-payments-and-escrow.html">8. Payments & 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 & safety</a></li><li><a href="12-messaging-and-emergencies.html">12. Messaging & emergencies</a></li><li><a href="13-tax-invoicing-and-legal.html">13. Tax, invoicing & legal</a></li><li><a href="14-notifications-and-admin.html">14. Notifications & admin</a></li></ul></div><div class="group"><div class="label">Database model</div><ul><li><a href="../data-model/index.html">Overview & 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 & 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 & pricing</a></li><li><a href="../data-model/04-verification-and-credentials.html">4. Verification & credentials</a></li><li><a href="../data-model/05-booking-and-scheduling.html">5. Booking & scheduling</a></li><li><a href="../data-model/06-payments-ledger-and-refunds.html">6. Payments, ledger & 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 & 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 & reference</a></li><li><a href="../data-model/13-partner-centers-and-future.html">13. Partner centers & future</a></li></ul></div><div class="group"><div class="label">Payments deep-dive</div><ul><li><a href="../payments/index.html">Overview & 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 & finding</a></li><li><a href="../payments/cancellation-and-payout.html">Cancellation & nurse payout</a></li><li><a href="../payments/integration-notes.html">Integration & schema touchpoints</a></li><li><a href="../payments/sources.html">Recommendations & sources</a></li></ul></div><div class="group"><div class="label">Research & strategy</div><ul><li><a href="../research/index.html">Overview & exec summary</a></li><li><a href="../research/market-and-competitors.html">Market & competitors</a></li><li><a href="../research/problems-and-risks.html">Problems & 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 & sources</a></li></ul></div><div class="group"><div class="label">Notes & 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="4-search-matching">4. Search & Matching</h1>
|
||||
<p><a href="index.html">← Business Requirements</a></p>
|
||||
<h2 id="a-business-requirements">(a) Business requirements <a class="anchor" href="#a-business-requirements" aria-hidden="true">#</a></h2>
|
||||
<ul>
|
||||
<li>Families search by <strong>service category</strong>, <strong>geography</strong> (city, and optionally district), price, and availability, with results sortable by rating.</li>
|
||||
<li><strong>Geography</strong> is driven by nurse-declared <strong>service areas</strong>: a nurse covers one or more cities, optionally specific districts; a city-level row (no district) means the whole city.</li>
|
||||
<li><strong>Search must be cheap from day one.</strong> The naive query joins nurse profile (verified + accepting) → variants (category/price) → variant options → service areas → rating across 4+ tables. Instead a <strong>denormalized <code>nurse_search_index</code></strong> holds one flat row per active, bookable variant with all search-relevant fields, maintained on write. A row exists <strong>only</strong> when the nurse is <code>is_verified</code> and not suspended and the variant <code>is_active</code>. This is far cheaper than introducing Elasticsearch at MVP stage.</li>
|
||||
<li><strong>Same-gender caregiver matching</strong> is a first-class filter and a near-hard requirement: in Iranian bodily-care (bathing, toileting, intimate post-surgical care) same-gender caregiving is culturally decisive, not optional. The customer specifies a required caregiver gender on the booking request (<code>required_caregiver_gender</code>), and nurse gender is an exposed search filter so families can narrow to same-gender caregivers up front. The patient's gender (<code>patients.gender</code>) and the nurse's gender support this matching.</li>
|
||||
</ul>
|
||||
<h2 id="b-iran-specific-considerations">(b) Iran-specific considerations <a class="anchor" href="#b-iran-specific-considerations" aria-hidden="true">#</a></h2>
|
||||
<ul>
|
||||
<li>District granularity varies: in Tehran, districts map to the 22 official municipal مناطق; in smaller cities they are major neighborhoods. Districts are optional.</li>
|
||||
<li><strong>Same-gender matching is the single most Iran-specific matching constraint</strong> — every real elder/post-surgical bodily-care request implies it. It must be surfaced before booking, not discovered after.</li>
|
||||
<li>White-space opportunity: incumbents concentrate ~99% in Tehran/Karaj; the search/area model must work for under-served second-tier cities (Mashhad, Isfahan, Shiraz, Tabriz, Ahvaz, Qom).</li>
|
||||
</ul>
|
||||
<h2 id="c-mvp-vs-deferred">(c) MVP vs DEFERRED <a class="anchor" href="#c-mvp-vs-deferred" aria-hidden="true">#</a></h2>
|
||||
<ul>
|
||||
<li><strong>MVP:</strong> category + city/district geo search; <code>nurse_search_index</code> denormalization; same-gender filter via <code>required_caregiver_gender</code>; rating sort.</li>
|
||||
<li><strong>DEFERRED:</strong> map-based discovery; availability-window filtering as a hard constraint (availability slots are soft guidance at launch); algorithmic ranking beyond rating; continuity-of-carer "preferred nurse" suggestions.</li>
|
||||
</ul>
|
||||
<h2 id="d-supporting-database-entities">(d) Supporting database entities <a class="anchor" href="#d-supporting-database-entities" aria-hidden="true">#</a></h2>
|
||||
<p><code>nurse_service_areas</code>, <code>cities</code>, <code>districts</code>, <strong><code>nurse_search_index</code></strong>, <code>nurse_service_variants</code>, <code>nurse_profiles</code> (rating, gender via <code>users</code>), <code>patients.gender</code>; <code>booking_requests.required_caregiver_gender</code> (the requested constraint).</p>
|
||||
<blockquote><p><strong>Related:</strong> Data model — <a href="../data-model/03-services-and-pricing.html">Services & Pricing</a>.</p>
|
||||
</blockquote>
|
||||
<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>
|
||||
@@ -0,0 +1,23 @@
|
||||
# 4. Search & Matching
|
||||
|
||||
[← Business Requirements](index.md)
|
||||
|
||||
## (a) Business requirements
|
||||
- Families search by **service category**, **geography** (city, and optionally district), price, and availability, with results sortable by rating.
|
||||
- **Geography** is driven by nurse-declared **service areas**: a nurse covers one or more cities, optionally specific districts; a city-level row (no district) means the whole city.
|
||||
- **Search must be cheap from day one.** The naive query joins nurse profile (verified + accepting) → variants (category/price) → variant options → service areas → rating across 4+ tables. Instead a **denormalized `nurse_search_index`** holds one flat row per active, bookable variant with all search-relevant fields, maintained on write. A row exists **only** when the nurse is `is_verified` and not suspended and the variant `is_active`. This is far cheaper than introducing Elasticsearch at MVP stage.
|
||||
- **Same-gender caregiver matching** is a first-class filter and a near-hard requirement: in Iranian bodily-care (bathing, toileting, intimate post-surgical care) same-gender caregiving is culturally decisive, not optional. The customer specifies a required caregiver gender on the booking request (`required_caregiver_gender`), and nurse gender is an exposed search filter so families can narrow to same-gender caregivers up front. The patient's gender (`patients.gender`) and the nurse's gender support this matching.
|
||||
|
||||
## (b) Iran-specific considerations
|
||||
- District granularity varies: in Tehran, districts map to the 22 official municipal مناطق; in smaller cities they are major neighborhoods. Districts are optional.
|
||||
- **Same-gender matching is the single most Iran-specific matching constraint** — every real elder/post-surgical bodily-care request implies it. It must be surfaced before booking, not discovered after.
|
||||
- White-space opportunity: incumbents concentrate ~99% in Tehran/Karaj; the search/area model must work for under-served second-tier cities (Mashhad, Isfahan, Shiraz, Tabriz, Ahvaz, Qom).
|
||||
|
||||
## (c) MVP vs DEFERRED
|
||||
- **MVP:** category + city/district geo search; `nurse_search_index` denormalization; same-gender filter via `required_caregiver_gender`; rating sort.
|
||||
- **DEFERRED:** map-based discovery; availability-window filtering as a hard constraint (availability slots are soft guidance at launch); algorithmic ranking beyond rating; continuity-of-carer "preferred nurse" suggestions.
|
||||
|
||||
## (d) Supporting database entities
|
||||
`nurse_service_areas`, `cities`, `districts`, **`nurse_search_index`**, `nurse_service_variants`, `nurse_profiles` (rating, gender via `users`), `patients.gender`; `booking_requests.required_caregiver_gender` (the requested constraint).
|
||||
|
||||
> **Related:** Data model — [Services & Pricing](../data-model/03-services-and-pricing.md).
|
||||
@@ -0,0 +1,58 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<title>5. Booking & Scheduling — 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 & ground truths</a></li></ul></div><div class="group"><div class="label">Business requirements</div><ul><li><a href="index.html">Overview & MVP scope</a></li><li><a href="01-actors-and-onboarding.html">1. Actors & 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 & pricing</a></li><li><a href="04-search-and-matching.html">4. Search & matching</a></li><li><a class="active" href="05-booking-and-scheduling.html">5. Booking & 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 & refunds</a></li><li><a href="08-payments-and-escrow.html">8. Payments & 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 & safety</a></li><li><a href="12-messaging-and-emergencies.html">12. Messaging & emergencies</a></li><li><a href="13-tax-invoicing-and-legal.html">13. Tax, invoicing & legal</a></li><li><a href="14-notifications-and-admin.html">14. Notifications & admin</a></li></ul></div><div class="group"><div class="label">Database model</div><ul><li><a href="../data-model/index.html">Overview & 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 & 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 & pricing</a></li><li><a href="../data-model/04-verification-and-credentials.html">4. Verification & credentials</a></li><li><a href="../data-model/05-booking-and-scheduling.html">5. Booking & scheduling</a></li><li><a href="../data-model/06-payments-ledger-and-refunds.html">6. Payments, ledger & 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 & 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 & reference</a></li><li><a href="../data-model/13-partner-centers-and-future.html">13. Partner centers & future</a></li></ul></div><div class="group"><div class="label">Payments deep-dive</div><ul><li><a href="../payments/index.html">Overview & 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 & finding</a></li><li><a href="../payments/cancellation-and-payout.html">Cancellation & nurse payout</a></li><li><a href="../payments/integration-notes.html">Integration & schema touchpoints</a></li><li><a href="../payments/sources.html">Recommendations & sources</a></li></ul></div><div class="group"><div class="label">Research & strategy</div><ul><li><a href="../research/index.html">Overview & exec summary</a></li><li><a href="../research/market-and-competitors.html">Market & competitors</a></li><li><a href="../research/problems-and-risks.html">Problems & 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 & sources</a></li></ul></div><div class="group"><div class="label">Notes & 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="5-booking-scheduling">5. Booking & Scheduling</h1>
|
||||
<p><a href="index.html">← Business Requirements</a></p>
|
||||
<h2 id="a-business-requirements">(a) Business requirements <a class="anchor" href="#a-business-requirements" aria-hidden="true">#</a></h2>
|
||||
<p>The lifecycle has two phases separated into two tables so each table's invariants stay clean: a <strong>request phase</strong> (no money) and a <strong>booking phase</strong> (always implies captured payment).</p>
|
||||
<p><strong>Request → accept → pay → confirm lifecycle:</strong></p>
|
||||
<ol>
|
||||
<li>Customer submits a <strong>booking request</strong> (nurse, patient, variant, address, date/time, requested caregiver gender, customer notes). Status <code>pending_nurse_response</code>.</li>
|
||||
<li>The nurse must respond before a <strong>response deadline</strong> (<code>nurse_response_deadline_at</code>, computed from config and frozen on the request). The nurse <strong>accepts</strong> → <code>accepted_awaiting_payment</code>, or <strong>rejects</strong> → <code>rejected_by_nurse</code>, or the deadline passes → <code>expired_no_response</code>.</li>
|
||||
<li>On accept, a <strong>30-minute payment window</strong> opens (<code>payment_deadline_at</code>). The customer pays within it → a <code>bookings</code> row is created (<code>confirmed</code>). If the window lapses → <code>payment_deadline_expired</code>.</li>
|
||||
</ol>
|
||||
<p><strong>Single-visit AND multi-session / long-duration engagements must both be representable.</strong> Home nursing is frequently multi-visit: post-surgery daily visits for ten days, month-long nightly or شبانهروزی (24h live-in) care. A booking therefore carries a <code>session_count</code> and owns <strong>N <code>booking_sessions</code></strong> (one row per scheduled visit), each with its own schedule, its own EVV check-in/out, and its own payout eligibility. A single EVV per booking cannot represent a multi-day engagement, so the engagement-to-session split is the core scheduling model.</p>
|
||||
<p><strong>Booking lifecycle:</strong> <code>pending_payment</code> → <code>confirmed</code> (payment captured) → <code>in_progress</code> (first/relevant session check-in) → <code>completed</code> (sessions checked out) → optionally <code>disputed</code> → <code>closed</code>; or <code>cancelled</code> before service. Allowed transitions are guarded explicitly so the booking and EVV state machines cannot silently contradict.</p>
|
||||
<p><strong>Snapshots:</strong> <code>variant_snapshot_json</code> and <code>address_snapshot_json</code> freeze the service and address at booking time.</p>
|
||||
<h2 id="b-iran-specific-considerations">(b) Iran-specific considerations <a class="anchor" href="#b-iran-specific-considerations" aria-hidden="true">#</a></h2>
|
||||
<ul>
|
||||
<li>Multi-session and شبانهروزی live-in care is the <strong>dominant</strong> elder-care shape in Iran, not a niche — modeling only single visits would fail to represent demand.</li>
|
||||
<li>Heavy platform control over multi-visit scheduling <strong>strengthens a worker-misclassification argument</strong> under labor law; this is flagged for counsel, and the platform deliberately keeps the nurse's accept/reject autonomy per request.</li>
|
||||
<li>Availability slots/exceptions are <strong>soft guidance only</strong> (informing search), not hard blocks — the nurse still individually accepts or rejects each request, which also fits the Shamsi week and holiday rhythm.</li>
|
||||
</ul>
|
||||
<h2 id="c-mvp-vs-deferred">(c) MVP vs DEFERRED <a class="anchor" href="#c-mvp-vs-deferred" aria-hidden="true">#</a></h2>
|
||||
<ul>
|
||||
<li><strong>MVP:</strong> request→accept→pay→confirm lifecycle with response deadline + 30-min payment window; single-visit bookings; <code>booking_sessions</code> for multi-session/long-duration engagements with per-session EVV and payout; explicit status-transition guards; snapshots; soft availability slots/exceptions.</li>
|
||||
<li><strong>DEFERRED:</strong> open-ended recurring schedules (<code>recurring_booking_schedules</code> modeled, inactive — launch is all finite engagements); milestone/progress-payment UX beyond per-session accrual; hard availability-based booking blocks.</li>
|
||||
</ul>
|
||||
<h2 id="d-supporting-database-entities">(d) Supporting database entities <a class="anchor" href="#d-supporting-database-entities" aria-hidden="true">#</a></h2>
|
||||
<p><code>booking_requests</code> (carries <code>nurse_response_deadline_at</code>, <code>payment_deadline_at</code>, <code>required_caregiver_gender</code>), <code>bookings</code> (carries <code>session_count</code>, <code>dispute_window_ends_at</code>, fee split), <strong><code>booking_sessions</code></strong>, <code>booking_care_instructions</code>, <code>nurse_availability_slots</code>, <code>nurse_availability_exceptions</code>, <code>nurse_service_variants</code>, <code>patients</code>, <code>customer_addresses</code>.</p>
|
||||
<blockquote><p><strong>Related:</strong> Data model — <a href="../data-model/05-booking-and-scheduling.html">Booking & Scheduling</a>.</p>
|
||||
</blockquote>
|
||||
<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>
|
||||
@@ -0,0 +1,31 @@
|
||||
# 5. Booking & Scheduling
|
||||
|
||||
[← Business Requirements](index.md)
|
||||
|
||||
## (a) Business requirements
|
||||
The lifecycle has two phases separated into two tables so each table's invariants stay clean: a **request phase** (no money) and a **booking phase** (always implies captured payment).
|
||||
|
||||
**Request → accept → pay → confirm lifecycle:**
|
||||
1. Customer submits a **booking request** (nurse, patient, variant, address, date/time, requested caregiver gender, customer notes). Status `pending_nurse_response`.
|
||||
2. The nurse must respond before a **response deadline** (`nurse_response_deadline_at`, computed from config and frozen on the request). The nurse **accepts** → `accepted_awaiting_payment`, or **rejects** → `rejected_by_nurse`, or the deadline passes → `expired_no_response`.
|
||||
3. On accept, a **30-minute payment window** opens (`payment_deadline_at`). The customer pays within it → a `bookings` row is created (`confirmed`). If the window lapses → `payment_deadline_expired`.
|
||||
|
||||
**Single-visit AND multi-session / long-duration engagements must both be representable.** Home nursing is frequently multi-visit: post-surgery daily visits for ten days, month-long nightly or شبانهروزی (24h live-in) care. A booking therefore carries a `session_count` and owns **N `booking_sessions`** (one row per scheduled visit), each with its own schedule, its own EVV check-in/out, and its own payout eligibility. A single EVV per booking cannot represent a multi-day engagement, so the engagement-to-session split is the core scheduling model.
|
||||
|
||||
**Booking lifecycle:** `pending_payment` → `confirmed` (payment captured) → `in_progress` (first/relevant session check-in) → `completed` (sessions checked out) → optionally `disputed` → `closed`; or `cancelled` before service. Allowed transitions are guarded explicitly so the booking and EVV state machines cannot silently contradict.
|
||||
|
||||
**Snapshots:** `variant_snapshot_json` and `address_snapshot_json` freeze the service and address at booking time.
|
||||
|
||||
## (b) Iran-specific considerations
|
||||
- Multi-session and شبانهروزی live-in care is the **dominant** elder-care shape in Iran, not a niche — modeling only single visits would fail to represent demand.
|
||||
- Heavy platform control over multi-visit scheduling **strengthens a worker-misclassification argument** under labor law; this is flagged for counsel, and the platform deliberately keeps the nurse's accept/reject autonomy per request.
|
||||
- Availability slots/exceptions are **soft guidance only** (informing search), not hard blocks — the nurse still individually accepts or rejects each request, which also fits the Shamsi week and holiday rhythm.
|
||||
|
||||
## (c) MVP vs DEFERRED
|
||||
- **MVP:** request→accept→pay→confirm lifecycle with response deadline + 30-min payment window; single-visit bookings; `booking_sessions` for multi-session/long-duration engagements with per-session EVV and payout; explicit status-transition guards; snapshots; soft availability slots/exceptions.
|
||||
- **DEFERRED:** open-ended recurring schedules (`recurring_booking_schedules` modeled, inactive — launch is all finite engagements); milestone/progress-payment UX beyond per-session accrual; hard availability-based booking blocks.
|
||||
|
||||
## (d) Supporting database entities
|
||||
`booking_requests` (carries `nurse_response_deadline_at`, `payment_deadline_at`, `required_caregiver_gender`), `bookings` (carries `session_count`, `dispute_window_ends_at`, fee split), **`booking_sessions`**, `booking_care_instructions`, `nurse_availability_slots`, `nurse_availability_exceptions`, `nurse_service_variants`, `patients`, `customer_addresses`.
|
||||
|
||||
> **Related:** Data model — [Booking & Scheduling](../data-model/05-booking-and-scheduling.md).
|
||||
@@ -0,0 +1,53 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<title>6. EVV / Service Delivery — 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 & ground truths</a></li></ul></div><div class="group"><div class="label">Business requirements</div><ul><li><a href="index.html">Overview & MVP scope</a></li><li><a href="01-actors-and-onboarding.html">1. Actors & 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 & pricing</a></li><li><a href="04-search-and-matching.html">4. Search & matching</a></li><li><a href="05-booking-and-scheduling.html">5. Booking & scheduling</a></li><li><a class="active" href="06-evv-and-service-delivery.html">6. EVV / service delivery</a></li><li><a href="07-cancellation-and-refunds.html">7. Cancellation & refunds</a></li><li><a href="08-payments-and-escrow.html">8. Payments & 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 & safety</a></li><li><a href="12-messaging-and-emergencies.html">12. Messaging & emergencies</a></li><li><a href="13-tax-invoicing-and-legal.html">13. Tax, invoicing & legal</a></li><li><a href="14-notifications-and-admin.html">14. Notifications & admin</a></li></ul></div><div class="group"><div class="label">Database model</div><ul><li><a href="../data-model/index.html">Overview & 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 & 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 & pricing</a></li><li><a href="../data-model/04-verification-and-credentials.html">4. Verification & credentials</a></li><li><a href="../data-model/05-booking-and-scheduling.html">5. Booking & scheduling</a></li><li><a href="../data-model/06-payments-ledger-and-refunds.html">6. Payments, ledger & 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 & 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 & reference</a></li><li><a href="../data-model/13-partner-centers-and-future.html">13. Partner centers & future</a></li></ul></div><div class="group"><div class="label">Payments deep-dive</div><ul><li><a href="../payments/index.html">Overview & 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 & finding</a></li><li><a href="../payments/cancellation-and-payout.html">Cancellation & nurse payout</a></li><li><a href="../payments/integration-notes.html">Integration & schema touchpoints</a></li><li><a href="../payments/sources.html">Recommendations & sources</a></li></ul></div><div class="group"><div class="label">Research & strategy</div><ul><li><a href="../research/index.html">Overview & exec summary</a></li><li><a href="../research/market-and-competitors.html">Market & competitors</a></li><li><a href="../research/problems-and-risks.html">Problems & 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 & sources</a></li></ul></div><div class="group"><div class="label">Notes & 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="6-evv-service-delivery">6. EVV / Service Delivery</h1>
|
||||
<p><a href="index.html">← Business Requirements</a></p>
|
||||
<h2 id="a-business-requirements">(a) Business requirements <a class="anchor" href="#a-business-requirements" aria-hidden="true">#</a></h2>
|
||||
<ul>
|
||||
<li><strong>Electronic Visit Verification (EVV)</strong> is the authoritative record that a visit actually happened, for how long, and where. The nurse <strong>clocks in and out via the app per session</strong>, capturing GPS coordinates and timestamps.</li>
|
||||
<li>An <strong>address-match tolerance</strong> check computes whether the nurse's GPS at check-in falls within an acceptable radius of the booking address (<code>evv_location_tolerance_meters</code>). A mismatch is <strong>advisory</strong> — it raises a support alert / review flag but does <strong>not</strong> auto-cancel; it does not silently block the visit.</li>
|
||||
<li>If the nurse has not checked in by a configurable threshold after the scheduled start, a <strong>no-show / late support alert</strong> is created and the family is notified.</li>
|
||||
<li><strong>Payout is gated on EVV completion.</strong> A session/booking becomes payout-eligible only after EVV check-out <strong>and</strong> the dispute window has closed (Section 10). EVV completion is the trigger that lets the booking enter the next weekly payout batch; for a multi-session engagement, payout accrues per completed session.</li>
|
||||
</ul>
|
||||
<h2 id="b-iran-specific-considerations">(b) Iran-specific considerations <a class="anchor" href="#b-iran-specific-considerations" aria-hidden="true">#</a></h2>
|
||||
<ul>
|
||||
<li>EVV is the core operational-trust mitigation for <strong>unobserved in-home care</strong> of vulnerable patients who often cannot reliably report what happened (infants, dementia, post-anesthesia) — the platform compensates for unobservability with structured proof of service.</li>
|
||||
<li>Releasing escrow against proof of service is also a financial-correctness requirement under the Iranian "hold then pay weekly" model — the platform must not pay a nurse for a visit that has no EVV evidence.</li>
|
||||
</ul>
|
||||
<h2 id="c-mvp-vs-deferred">(c) MVP vs DEFERRED <a class="anchor" href="#c-mvp-vs-deferred" aria-hidden="true">#</a></h2>
|
||||
<ul>
|
||||
<li><strong>MVP:</strong> per-session GPS check-in/out, timestamps, address-match tolerance flag, no-show alerting, payout gated on EVV completion + closed dispute window.</li>
|
||||
<li><strong>DEFERRED:</strong> continuous geofencing during a live-in shift; supervisory tele-check-ins; family-visible live care logs; consented in-home cameras.</li>
|
||||
</ul>
|
||||
<h2 id="d-supporting-database-entities">(d) Supporting database entities <a class="anchor" href="#d-supporting-database-entities" aria-hidden="true">#</a></h2>
|
||||
<p><code>visit_verifications</code> (per session, with check-in/out GPS, timestamps, <code>check_in_address_match</code>, status), <code>booking_sessions</code>, <code>support_alerts</code> (no-show / location-mismatch), <code>platform_configs</code> (<code>evv_location_tolerance_meters</code>).</p>
|
||||
<blockquote><p><strong>Related:</strong> Data model — <a href="../data-model/05-booking-and-scheduling.html">Booking & Scheduling</a>.</p>
|
||||
</blockquote>
|
||||
<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>
|
||||
@@ -0,0 +1,22 @@
|
||||
# 6. EVV / Service Delivery
|
||||
|
||||
[← Business Requirements](index.md)
|
||||
|
||||
## (a) Business requirements
|
||||
- **Electronic Visit Verification (EVV)** is the authoritative record that a visit actually happened, for how long, and where. The nurse **clocks in and out via the app per session**, capturing GPS coordinates and timestamps.
|
||||
- An **address-match tolerance** check computes whether the nurse's GPS at check-in falls within an acceptable radius of the booking address (`evv_location_tolerance_meters`). A mismatch is **advisory** — it raises a support alert / review flag but does **not** auto-cancel; it does not silently block the visit.
|
||||
- If the nurse has not checked in by a configurable threshold after the scheduled start, a **no-show / late support alert** is created and the family is notified.
|
||||
- **Payout is gated on EVV completion.** A session/booking becomes payout-eligible only after EVV check-out **and** the dispute window has closed (Section 10). EVV completion is the trigger that lets the booking enter the next weekly payout batch; for a multi-session engagement, payout accrues per completed session.
|
||||
|
||||
## (b) Iran-specific considerations
|
||||
- EVV is the core operational-trust mitigation for **unobserved in-home care** of vulnerable patients who often cannot reliably report what happened (infants, dementia, post-anesthesia) — the platform compensates for unobservability with structured proof of service.
|
||||
- Releasing escrow against proof of service is also a financial-correctness requirement under the Iranian "hold then pay weekly" model — the platform must not pay a nurse for a visit that has no EVV evidence.
|
||||
|
||||
## (c) MVP vs DEFERRED
|
||||
- **MVP:** per-session GPS check-in/out, timestamps, address-match tolerance flag, no-show alerting, payout gated on EVV completion + closed dispute window.
|
||||
- **DEFERRED:** continuous geofencing during a live-in shift; supervisory tele-check-ins; family-visible live care logs; consented in-home cameras.
|
||||
|
||||
## (d) Supporting database entities
|
||||
`visit_verifications` (per session, with check-in/out GPS, timestamps, `check_in_address_match`, status), `booking_sessions`, `support_alerts` (no-show / location-mismatch), `platform_configs` (`evv_location_tolerance_meters`).
|
||||
|
||||
> **Related:** Data model — [Booking & Scheduling](../data-model/05-booking-and-scheduling.md).
|
||||
@@ -0,0 +1,61 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<title>7. Cancellation & Refunds — 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 & ground truths</a></li></ul></div><div class="group"><div class="label">Business requirements</div><ul><li><a href="index.html">Overview & MVP scope</a></li><li><a href="01-actors-and-onboarding.html">1. Actors & 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 & pricing</a></li><li><a href="04-search-and-matching.html">4. Search & matching</a></li><li><a href="05-booking-and-scheduling.html">5. Booking & scheduling</a></li><li><a href="06-evv-and-service-delivery.html">6. EVV / service delivery</a></li><li><a class="active" href="07-cancellation-and-refunds.html">7. Cancellation & refunds</a></li><li><a href="08-payments-and-escrow.html">8. Payments & 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 & safety</a></li><li><a href="12-messaging-and-emergencies.html">12. Messaging & emergencies</a></li><li><a href="13-tax-invoicing-and-legal.html">13. Tax, invoicing & legal</a></li><li><a href="14-notifications-and-admin.html">14. Notifications & admin</a></li></ul></div><div class="group"><div class="label">Database model</div><ul><li><a href="../data-model/index.html">Overview & 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 & 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 & pricing</a></li><li><a href="../data-model/04-verification-and-credentials.html">4. Verification & credentials</a></li><li><a href="../data-model/05-booking-and-scheduling.html">5. Booking & scheduling</a></li><li><a href="../data-model/06-payments-ledger-and-refunds.html">6. Payments, ledger & 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 & 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 & reference</a></li><li><a href="../data-model/13-partner-centers-and-future.html">13. Partner centers & future</a></li></ul></div><div class="group"><div class="label">Payments deep-dive</div><ul><li><a href="../payments/index.html">Overview & 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 & finding</a></li><li><a href="../payments/cancellation-and-payout.html">Cancellation & nurse payout</a></li><li><a href="../payments/integration-notes.html">Integration & schema touchpoints</a></li><li><a href="../payments/sources.html">Recommendations & sources</a></li></ul></div><div class="group"><div class="label">Research & strategy</div><ul><li><a href="../research/index.html">Overview & exec summary</a></li><li><a href="../research/market-and-competitors.html">Market & competitors</a></li><li><a href="../research/problems-and-risks.html">Problems & 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 & sources</a></li></ul></div><div class="group"><div class="label">Notes & 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="7-cancellation-refunds">7. Cancellation & Refunds</h1>
|
||||
<p><a href="index.html">← Business Requirements</a></p>
|
||||
<h2 id="a-business-requirements">(a) Business requirements <a class="anchor" href="#a-business-requirements" aria-hidden="true">#</a></h2>
|
||||
<ul>
|
||||
<li>Cancellation/refund rules are <strong>tiered and structured</strong>, not a single blunt "default 100%". The platform defines <code>cancellation_policies</code> tiers by <strong>lead time</strong> and <strong>initiating actor</strong>:<ul>
|
||||
<li><strong>Free</strong> cancellation more than 24h before start.</li>
|
||||
<li><strong>Partial</strong> refund (e.g., 50%) under 24h.</li>
|
||||
<li><strong>Customer no-show:</strong> up to 100% charge.</li>
|
||||
<li><strong>Nurse no-show:</strong> full refund to the customer <strong>and</strong> a penalty/forfeiture for the nurse.</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>The <strong>applicable policy is snapshotted onto the booking</strong> at booking time (mirroring the per-booking fee-rate snapshot), so later policy edits never rewrite history. The <strong>resolved</strong> cancellation fee / refund percentage is recorded on the refund event.</li>
|
||||
<li>For multi-session engagements, <strong>cancellation is per remaining session:</strong> cancelling mid-engagement refunds only the un-started sessions, while completed-and-verified sessions remain payout-eligible.</li>
|
||||
<li><strong>Refunds are admin-only</strong> — there is no customer self-service refund. A refund is initiated by an admin and <strong>must be linked to a support ticket</strong> (<code>tickets</code>) that holds the conversation and dispute evidence.</li>
|
||||
<li>A refund <strong>decomposes across the two fee legs</strong> — how much of the platform commission and how much of the nurse payout is being reversed — because the booking gross is <code>platform commission + nurse payout</code>.</li>
|
||||
</ul>
|
||||
<h2 id="b-iran-specific-considerations">(b) Iran-specific considerations <a class="anchor" href="#b-iran-specific-considerations" aria-hidden="true">#</a></h2>
|
||||
<ul>
|
||||
<li>A flat percentage is too blunt for شبانهروزی live-in engagements and Iranian holiday-period bookings; tiered, snapshotted policy reduces dispute load.</li>
|
||||
<li><strong>The refund money path depends on whether the nurse has already been paid</strong> (Section 8/10): pre-payout it is a clean reversal; post-payout it becomes a platform-funded refund plus a nurse clawback, because an Iranian bank transfer to a nurse's IBAN is effectively irreversible.</li>
|
||||
<li>For BNPL bookings, the refund <strong>never</strong> goes nurse→customer or Balinyaar→customer directly — it is initiated through the BNPL provider's revert/cancel API (Section 8/9).</li>
|
||||
</ul>
|
||||
<h2 id="c-mvp-vs-deferred">(c) MVP vs DEFERRED <a class="anchor" href="#c-mvp-vs-deferred" aria-hidden="true">#</a></h2>
|
||||
<ul>
|
||||
<li><strong>MVP:</strong> tiered <code>cancellation_policies</code>; per-booking policy snapshot; admin-only, ticket-linked refunds; per-session cancellation for engagements; nurse-no-show vs customer-no-show handling; fee-leg decomposition on refunds.</li>
|
||||
<li><strong>DEFERRED:</strong> automated nurse no-show penalty (manual admin action at launch); self-service partial-refund UI; holiday-specific cancellation overrides.</li>
|
||||
</ul>
|
||||
<h2 id="d-supporting-database-entities">(d) Supporting database entities <a class="anchor" href="#d-supporting-database-entities" aria-hidden="true">#</a></h2>
|
||||
<p><strong><code>cancellation_policies</code></strong>, <code>bookings</code> (policy snapshot, <code>dispute_window_ends_at</code>), <code>refunds</code> (admin-only, <code>ticket_id</code>, fee-leg decomposition, <code>refund_channel</code>), <code>tickets</code>, <code>nurse_clawbacks</code> (post-payout case), <code>ledger_entries</code>.</p>
|
||||
<blockquote><p><strong>Related:</strong> Data model — <a href="../data-model/06-payments-ledger-and-refunds.html">Payments Ledger & Refunds</a>.</p>
|
||||
</blockquote>
|
||||
<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>
|
||||
@@ -0,0 +1,28 @@
|
||||
# 7. Cancellation & Refunds
|
||||
|
||||
[← Business Requirements](index.md)
|
||||
|
||||
## (a) Business requirements
|
||||
- Cancellation/refund rules are **tiered and structured**, not a single blunt "default 100%". The platform defines `cancellation_policies` tiers by **lead time** and **initiating actor**:
|
||||
- **Free** cancellation more than 24h before start.
|
||||
- **Partial** refund (e.g., 50%) under 24h.
|
||||
- **Customer no-show:** up to 100% charge.
|
||||
- **Nurse no-show:** full refund to the customer **and** a penalty/forfeiture for the nurse.
|
||||
- The **applicable policy is snapshotted onto the booking** at booking time (mirroring the per-booking fee-rate snapshot), so later policy edits never rewrite history. The **resolved** cancellation fee / refund percentage is recorded on the refund event.
|
||||
- For multi-session engagements, **cancellation is per remaining session:** cancelling mid-engagement refunds only the un-started sessions, while completed-and-verified sessions remain payout-eligible.
|
||||
- **Refunds are admin-only** — there is no customer self-service refund. A refund is initiated by an admin and **must be linked to a support ticket** (`tickets`) that holds the conversation and dispute evidence.
|
||||
- A refund **decomposes across the two fee legs** — how much of the platform commission and how much of the nurse payout is being reversed — because the booking gross is `platform commission + nurse payout`.
|
||||
|
||||
## (b) Iran-specific considerations
|
||||
- A flat percentage is too blunt for شبانهروزی live-in engagements and Iranian holiday-period bookings; tiered, snapshotted policy reduces dispute load.
|
||||
- **The refund money path depends on whether the nurse has already been paid** (Section 8/10): pre-payout it is a clean reversal; post-payout it becomes a platform-funded refund plus a nurse clawback, because an Iranian bank transfer to a nurse's IBAN is effectively irreversible.
|
||||
- For BNPL bookings, the refund **never** goes nurse→customer or Balinyaar→customer directly — it is initiated through the BNPL provider's revert/cancel API (Section 8/9).
|
||||
|
||||
## (c) MVP vs DEFERRED
|
||||
- **MVP:** tiered `cancellation_policies`; per-booking policy snapshot; admin-only, ticket-linked refunds; per-session cancellation for engagements; nurse-no-show vs customer-no-show handling; fee-leg decomposition on refunds.
|
||||
- **DEFERRED:** automated nurse no-show penalty (manual admin action at launch); self-service partial-refund UI; holiday-specific cancellation overrides.
|
||||
|
||||
## (d) Supporting database entities
|
||||
**`cancellation_policies`**, `bookings` (policy snapshot, `dispute_window_ends_at`), `refunds` (admin-only, `ticket_id`, fee-leg decomposition, `refund_channel`), `tickets`, `nurse_clawbacks` (post-payout case), `ledger_entries`.
|
||||
|
||||
> **Related:** Data model — [Payments Ledger & Refunds](../data-model/06-payments-ledger-and-refunds.md).
|
||||
@@ -0,0 +1,60 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<title>8. Payments & Escrow — 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 & ground truths</a></li></ul></div><div class="group"><div class="label">Business requirements</div><ul><li><a href="index.html">Overview & MVP scope</a></li><li><a href="01-actors-and-onboarding.html">1. Actors & 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 & pricing</a></li><li><a href="04-search-and-matching.html">4. Search & matching</a></li><li><a href="05-booking-and-scheduling.html">5. Booking & 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 & refunds</a></li><li><a class="active" href="08-payments-and-escrow.html">8. Payments & 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 & safety</a></li><li><a href="12-messaging-and-emergencies.html">12. Messaging & emergencies</a></li><li><a href="13-tax-invoicing-and-legal.html">13. Tax, invoicing & legal</a></li><li><a href="14-notifications-and-admin.html">14. Notifications & admin</a></li></ul></div><div class="group"><div class="label">Database model</div><ul><li><a href="../data-model/index.html">Overview & 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 & 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 & pricing</a></li><li><a href="../data-model/04-verification-and-credentials.html">4. Verification & credentials</a></li><li><a href="../data-model/05-booking-and-scheduling.html">5. Booking & scheduling</a></li><li><a href="../data-model/06-payments-ledger-and-refunds.html">6. Payments, ledger & 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 & 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 & reference</a></li><li><a href="../data-model/13-partner-centers-and-future.html">13. Partner centers & future</a></li></ul></div><div class="group"><div class="label">Payments deep-dive</div><ul><li><a href="../payments/index.html">Overview & 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 & finding</a></li><li><a href="../payments/cancellation-and-payout.html">Cancellation & nurse payout</a></li><li><a href="../payments/integration-notes.html">Integration & schema touchpoints</a></li><li><a href="../payments/sources.html">Recommendations & sources</a></li></ul></div><div class="group"><div class="label">Research & strategy</div><ul><li><a href="../research/index.html">Overview & exec summary</a></li><li><a href="../research/market-and-competitors.html">Market & competitors</a></li><li><a href="../research/problems-and-risks.html">Problems & 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 & sources</a></li></ul></div><div class="group"><div class="label">Notes & 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="8-payments-escrow">8. Payments & Escrow</h1>
|
||||
<p><a href="index.html">← Business Requirements</a></p>
|
||||
<h2 id="a-business-requirements">(a) Business requirements <a class="anchor" href="#a-business-requirements" aria-hidden="true">#</a></h2>
|
||||
<ul>
|
||||
<li>The family pays the <strong>gross</strong> booking price <strong>through the platform</strong> by card via a licensed PSP's IPG. The platform is the <strong>merchant-of-record</strong>; the payment lands net of provider/Shaparak fees.</li>
|
||||
<li><strong>Escrow is an internal ledger state, not platform-held cash.</strong> The platform models money state with a minimal <strong>double-entry <code>ledger_entries</code></strong> ledger: each money event posts <strong>balanced</strong> legs grouped by a transaction group. Account types: <code>escrow_held</code>, <code>platform_revenue</code>, <code>nurse_payable</code>, <code>refund_payable</code>, <code>bnpl_fee_expense</code>, <code>nurse_clawback_receivable</code>. The ledger is the <strong>single source of truth</strong> for "how much is held," "how much do we owe nurses now," and "what is our commission income" — replacing fragile inference from scattered status booleans.<ul>
|
||||
<li>On a successful card payment: debit <code>escrow_held</code> (gross), credit <code>platform_revenue</code> (Balinyaar commission), credit <code>nurse_payable</code> (nurse payout).</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><strong>Settlement-sharing (تسهیم).</strong> The compliant marketplace primitive is splitting one incoming card payment across multiple <strong>registered IBANs</strong> (the nurse's share and the platform's commission) at settlement, performed by Shaparak/the provider — the platform never touches the actual split. The internal ledger mirrors this split; the per-booking fee snapshot freezes it.</li>
|
||||
<li><strong>Per-booking the three amounts are stored separately and never conflated:</strong> <code>gross_price_irr</code> (what the customer is charged), <code>balinyaar_commission_irr</code> (platform's cut — drives the nurse payout), and (for BNPL) <code>bnpl_commission_irr</code> (the provider's merchant discount — a platform expense). <code>nurse_payout_amount = gross_price_irr − balinyaar_commission_irr</code>.</li>
|
||||
<li><strong>Webhook idempotency is mandatory before money moves.</strong> Every PSP/BNPL callback is stored raw and <strong>deduplicated by a unique external event id</strong> in <code>payment_webhook_events</code> before any money state mutates — preventing double-confirmed bookings and double-settlements from at-least-once, retried callbacks.</li>
|
||||
<li><strong>Payment uniqueness:</strong> at most one <code>succeeded</code> payment transaction per booking, and the Shaparak reference is unique — enforced so a retried success webhook cannot double-confirm.</li>
|
||||
<li><strong>Multi-provider failover.</strong> Provider settlement cut-offs are a real continuity risk (the Toman/Jibit Nov-2024 suspensions cut businesses off mid-cycle). The payment layer abstracts the provider behind configuration so a blocked provider can be swapped, and the reconciliation ledger survives a provider being cut off.</li>
|
||||
</ul>
|
||||
<h2 id="b-iran-specific-considerations">(b) Iran-specific considerations <a class="anchor" href="#b-iran-specific-considerations" aria-hidden="true">#</a></h2>
|
||||
<ul>
|
||||
<li><strong>The load-bearing legal constraint:</strong> a پرداختیار may <strong>not</strong> hold customer deposits, run wallets, or move money between merchants; the Shaparak ban on inter-merchant/inter-facilitator transfers means the "delay the تسهیم and redistribute later from a platform pool" pattern is regulatory grey-to-prohibited. The compliant posture is: collect via the provider, model escrow as an <strong>internal ledger over funds custodied at the licensed provider/partner bank</strong>, and pay out by provider-side settlement to <strong>verified, registered nurse IBANs</strong>. A bank-grade escrow product (e.g., Vandar میندو / معاملات امن) is the only true hold/release/refund mechanism, and its EVV-triggered hold is unverified — so the platform never assumes it can lawfully custody the cash itself.</li>
|
||||
<li><strong>PSP received ≠ cash in bank.</strong> Iranian PAYA settlement is cyclic (T+0/T+1, holiday-deferred), so the ledger separates a clearing/receivable state from settled cash, making bank reconciliation possible.</li>
|
||||
<li>Toman/PSP units differ from internal Rials; convert only at the API boundary. Amounts are BIGINT IRR internally to avoid float/rounding bugs.</li>
|
||||
</ul>
|
||||
<h2 id="c-mvp-vs-deferred">(c) MVP vs DEFERRED <a class="anchor" href="#c-mvp-vs-deferred" aria-hidden="true">#</a></h2>
|
||||
<ul>
|
||||
<li><strong>MVP:</strong> card payment via one licensed PSP; internal double-entry <code>ledger_entries</code> escrow; per-booking three-way amount split; تسهیم-style commission/nurse-share modeling; <code>payment_webhook_events</code> idempotency; single-succeeded-transaction-per-booking guard; provider abstraction for failover.</li>
|
||||
<li><strong>DEFERRED:</strong> a nurse-facing wallet with on-demand withdrawal (facilitator wallet prohibition risk); multiple simultaneous live PSPs at launch (abstraction is built, second provider added later); bank-grade EVV-triggered escrow product integration.</li>
|
||||
</ul>
|
||||
<h2 id="d-supporting-database-entities">(d) Supporting database entities <a class="anchor" href="#d-supporting-database-entities" aria-hidden="true">#</a></h2>
|
||||
<p><code>payment_gateways</code>, <code>payment_transactions</code> (unique Shaparak ref, single-succeeded-per-booking), <strong><code>payment_webhook_events</code></strong>, <strong><code>ledger_entries</code></strong>, <code>bookings</code> (<code>gross_price_irr</code>, <code>balinyaar_commission_irr</code>, <code>platform_fee_rate</code>, <code>nurse_payout_amount</code>), <code>refunds</code>, <code>nurse_bank_accounts</code> (verified registered IBANs).</p>
|
||||
<blockquote><p><strong>Related:</strong> Deep fintech detail — <a href="../payments/escrow-ledger.html">Escrow Ledger</a>. Data model — <a href="../data-model/06-payments-ledger-and-refunds.html">Payments Ledger & Refunds</a>.</p>
|
||||
</blockquote>
|
||||
<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>
|
||||
@@ -0,0 +1,27 @@
|
||||
# 8. Payments & Escrow
|
||||
|
||||
[← Business Requirements](index.md)
|
||||
|
||||
## (a) Business requirements
|
||||
- The family pays the **gross** booking price **through the platform** by card via a licensed PSP's IPG. The platform is the **merchant-of-record**; the payment lands net of provider/Shaparak fees.
|
||||
- **Escrow is an internal ledger state, not platform-held cash.** The platform models money state with a minimal **double-entry `ledger_entries`** ledger: each money event posts **balanced** legs grouped by a transaction group. Account types: `escrow_held`, `platform_revenue`, `nurse_payable`, `refund_payable`, `bnpl_fee_expense`, `nurse_clawback_receivable`. The ledger is the **single source of truth** for "how much is held," "how much do we owe nurses now," and "what is our commission income" — replacing fragile inference from scattered status booleans.
|
||||
- On a successful card payment: debit `escrow_held` (gross), credit `platform_revenue` (Balinyaar commission), credit `nurse_payable` (nurse payout).
|
||||
- **Settlement-sharing (تسهیم).** The compliant marketplace primitive is splitting one incoming card payment across multiple **registered IBANs** (the nurse's share and the platform's commission) at settlement, performed by Shaparak/the provider — the platform never touches the actual split. The internal ledger mirrors this split; the per-booking fee snapshot freezes it.
|
||||
- **Per-booking the three amounts are stored separately and never conflated:** `gross_price_irr` (what the customer is charged), `balinyaar_commission_irr` (platform's cut — drives the nurse payout), and (for BNPL) `bnpl_commission_irr` (the provider's merchant discount — a platform expense). `nurse_payout_amount = gross_price_irr − balinyaar_commission_irr`.
|
||||
- **Webhook idempotency is mandatory before money moves.** Every PSP/BNPL callback is stored raw and **deduplicated by a unique external event id** in `payment_webhook_events` before any money state mutates — preventing double-confirmed bookings and double-settlements from at-least-once, retried callbacks.
|
||||
- **Payment uniqueness:** at most one `succeeded` payment transaction per booking, and the Shaparak reference is unique — enforced so a retried success webhook cannot double-confirm.
|
||||
- **Multi-provider failover.** Provider settlement cut-offs are a real continuity risk (the Toman/Jibit Nov-2024 suspensions cut businesses off mid-cycle). The payment layer abstracts the provider behind configuration so a blocked provider can be swapped, and the reconciliation ledger survives a provider being cut off.
|
||||
|
||||
## (b) Iran-specific considerations
|
||||
- **The load-bearing legal constraint:** a پرداختیار may **not** hold customer deposits, run wallets, or move money between merchants; the Shaparak ban on inter-merchant/inter-facilitator transfers means the "delay the تسهیم and redistribute later from a platform pool" pattern is regulatory grey-to-prohibited. The compliant posture is: collect via the provider, model escrow as an **internal ledger over funds custodied at the licensed provider/partner bank**, and pay out by provider-side settlement to **verified, registered nurse IBANs**. A bank-grade escrow product (e.g., Vandar میندو / معاملات امن) is the only true hold/release/refund mechanism, and its EVV-triggered hold is unverified — so the platform never assumes it can lawfully custody the cash itself.
|
||||
- **PSP received ≠ cash in bank.** Iranian PAYA settlement is cyclic (T+0/T+1, holiday-deferred), so the ledger separates a clearing/receivable state from settled cash, making bank reconciliation possible.
|
||||
- Toman/PSP units differ from internal Rials; convert only at the API boundary. Amounts are BIGINT IRR internally to avoid float/rounding bugs.
|
||||
|
||||
## (c) MVP vs DEFERRED
|
||||
- **MVP:** card payment via one licensed PSP; internal double-entry `ledger_entries` escrow; per-booking three-way amount split; تسهیم-style commission/nurse-share modeling; `payment_webhook_events` idempotency; single-succeeded-transaction-per-booking guard; provider abstraction for failover.
|
||||
- **DEFERRED:** a nurse-facing wallet with on-demand withdrawal (facilitator wallet prohibition risk); multiple simultaneous live PSPs at launch (abstraction is built, second provider added later); bank-grade EVV-triggered escrow product integration.
|
||||
|
||||
## (d) Supporting database entities
|
||||
`payment_gateways`, `payment_transactions` (unique Shaparak ref, single-succeeded-per-booking), **`payment_webhook_events`**, **`ledger_entries`**, `bookings` (`gross_price_irr`, `balinyaar_commission_irr`, `platform_fee_rate`, `nurse_payout_amount`), `refunds`, `nurse_bank_accounts` (verified registered IBANs).
|
||||
|
||||
> **Related:** Deep fintech detail — [Escrow Ledger](../payments/escrow-ledger.md). Data model — [Payments Ledger & Refunds](../data-model/06-payments-ledger-and-refunds.md).
|
||||
@@ -0,0 +1,58 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<title>9. Installments / BNPL — 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 & ground truths</a></li></ul></div><div class="group"><div class="label">Business requirements</div><ul><li><a href="index.html">Overview & MVP scope</a></li><li><a href="01-actors-and-onboarding.html">1. Actors & 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 & pricing</a></li><li><a href="04-search-and-matching.html">4. Search & matching</a></li><li><a href="05-booking-and-scheduling.html">5. Booking & 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 & refunds</a></li><li><a href="08-payments-and-escrow.html">8. Payments & escrow</a></li><li><a class="active" 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 & safety</a></li><li><a href="12-messaging-and-emergencies.html">12. Messaging & emergencies</a></li><li><a href="13-tax-invoicing-and-legal.html">13. Tax, invoicing & legal</a></li><li><a href="14-notifications-and-admin.html">14. Notifications & admin</a></li></ul></div><div class="group"><div class="label">Database model</div><ul><li><a href="../data-model/index.html">Overview & 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 & 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 & pricing</a></li><li><a href="../data-model/04-verification-and-credentials.html">4. Verification & credentials</a></li><li><a href="../data-model/05-booking-and-scheduling.html">5. Booking & scheduling</a></li><li><a href="../data-model/06-payments-ledger-and-refunds.html">6. Payments, ledger & 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 & 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 & reference</a></li><li><a href="../data-model/13-partner-centers-and-future.html">13. Partner centers & future</a></li></ul></div><div class="group"><div class="label">Payments deep-dive</div><ul><li><a href="../payments/index.html">Overview & 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 & finding</a></li><li><a href="../payments/cancellation-and-payout.html">Cancellation & nurse payout</a></li><li><a href="../payments/integration-notes.html">Integration & schema touchpoints</a></li><li><a href="../payments/sources.html">Recommendations & sources</a></li></ul></div><div class="group"><div class="label">Research & strategy</div><ul><li><a href="../research/index.html">Overview & exec summary</a></li><li><a href="../research/market-and-competitors.html">Market & competitors</a></li><li><a href="../research/problems-and-risks.html">Problems & 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 & sources</a></li></ul></div><div class="group"><div class="label">Notes & 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="9-installments-bnpl">9. Installments / BNPL</h1>
|
||||
<p><a href="index.html">← Business Requirements</a></p>
|
||||
<h2 id="a-business-requirements">(a) Business requirements <a class="anchor" href="#a-business-requirements" aria-hidden="true">#</a></h2>
|
||||
<ul>
|
||||
<li>BNPL is offered as an alternative checkout. The decisive, verified model is <strong>full-upfront settlement</strong>: on approval the BNPL provider pays Balinyaar the <strong>full booking amount in one lump, net of the provider's merchant commission</strong>, and <strong>bears 100% of customer-default risk</strong>. The customer's interest-free installment repayment (typically a 4-installment plan) is <strong>owned entirely by the provider</strong> and is <strong>decoupled</strong> from Balinyaar's escrow/EVV/payout cycle.</li>
|
||||
<li><strong>Therefore a BNPL order is, in Balinyaar's books, identical to a card payment that lands net-of-fee in one inbound settlement.</strong> Balinyaar <strong>does NOT track customer installments, per-installment webhooks, or default propagation</strong> — that fragile subsystem is intentionally not built.</li>
|
||||
<li>A BNPL order is recorded once as a single inbound settlement in <code>bnpl_transactions</code> (1:1 with a payment transaction), capturing the provider, the merchant-of-record (Balinyaar), the external payment token / transaction id, <code>order_amount_irr</code>, <code>settled_amount_irr</code> (net of provider commission), <code>bnpl_commission_irr</code>, currency (converted at the boundary), an idempotent status state-machine (<code>eligible</code>/<code>token_issued</code>/<code>verified</code>/<code>settled</code>/<code>reverted</code>/<code>cancelled</code>/<code>failed</code>), <code>installment_count</code> (informational, default 4), <code>settled_at</code>, and the revert fields.</li>
|
||||
<li><strong>BNPL refunds flow only customer ↔ provider ↔ Balinyaar</strong> — never nurse→customer or Balinyaar→customer directly. Balinyaar initiates the reversal via the provider's revert (full) / cancel/update (partial, new amount strictly lower) API using the stored token; the provider cancels the customer's unpaid installments, restores their credit, and refunds any already-paid installment to the customer's bank in ~7–10 business days (asynchronous, owned by the provider). The refund still decomposes across the platform-fee and nurse-payout legs in Balinyaar's ledger.</li>
|
||||
<li><strong>The nurse's payout is unchanged by BNPL:</strong> computed from <code>gross_price_irr − balinyaar_commission_irr</code>, paid weekly after EVV + dispute window — the provider's commission is a <strong>platform cost of accepting BNPL</strong> and is <strong>never</strong> passed through to the nurse.</li>
|
||||
</ul>
|
||||
<blockquote><p><strong>This is a summary. Deep BNPL provider mechanics, the exact revert/cancel/settle API flows, commission-as-config, settlement-timing nuances, and provider-specific behavior are specified in the payments docs — cross-reference the <a href="../payments/bnpl-landscape.html">BNPL landscape</a> and <a href="../payments/cancellation-and-payout.html">cancellation & payout</a> for implementation detail.</strong></p>
|
||||
</blockquote>
|
||||
<h2 id="b-iran-specific-considerations">(b) Iran-specific considerations <a class="anchor" href="#b-iran-specific-considerations" aria-hidden="true">#</a></h2>
|
||||
<ul>
|
||||
<li>Provider-financed Iranian BNPLs (SnappPay, Digipay, Tara, Torob Pay) are uniformly <strong>full-upfront, provider-bears-risk, interest-free-to-customer</strong>; only bank-financed POS loans (Lendo) charge the customer interest and are a poor fit for short, cancellable nursing visits.</li>
|
||||
<li><strong>Settlement timing is contract-defined and may be gated on the customer's first installment</strong> (daily / T+1-3 / weekly / 15-day) — "full amount" does not mean "instant cash." Timing is config + a per-transaction <code>settled_at</code>; weekly nurse payout may key off settlement actually received, never an assumption.</li>
|
||||
<li><strong>Commission rate is per-contract and not public</strong> (anecdotal 7–15% for SnappPay; Torob Pay's published 6.6%) — always a config field read from the actual settlement, never hardcoded.</li>
|
||||
<li>Onboarding requires جواز کسب <strong>and</strong> اینماد for the Balinyaar/partner entity, and whether a multi-vendor re-disbursing marketplace qualifies as a single BNPL merchant is publicly undocumented — an ops/contracting task, not a schema dependency.</li>
|
||||
</ul>
|
||||
<h2 id="c-mvp-vs-deferred">(c) MVP vs DEFERRED <a class="anchor" href="#c-mvp-vs-deferred" aria-hidden="true">#</a></h2>
|
||||
<ul>
|
||||
<li><strong>MVP:</strong> full-upfront BNPL via one provider modeled as a single inbound settlement (<code>bnpl_transactions</code>); provider-mediated revert/cancel refunds; nurse payout decoupled from BNPL; commission + settlement timing as config.</li>
|
||||
<li><strong>DEFERRED:</strong> customer installment tracking (<code>installment_entries</code> — <strong>cut</strong>, owned by the provider); tranched settlement (<code>bnpl_settlement_entries</code> modeled-only, added if a future provider tranches); multiple BNPL providers.</li>
|
||||
</ul>
|
||||
<h2 id="d-supporting-database-entities">(d) Supporting database entities <a class="anchor" href="#d-supporting-database-entities" aria-hidden="true">#</a></h2>
|
||||
<p><strong><code>bnpl_transactions</code></strong> (replaces the old <code>installment_plans</code>; the old <code>installment_entries</code> is cut), <code>payment_transactions</code>, <code>payment_webhook_events</code>, <code>refunds</code> (<code>refund_channel = 'bnpl_revert'</code>, <code>external_revert_reference</code>, <code>expected_customer_refund_eta</code>), <code>ledger_entries</code>. See the <a href="../payments/bnpl-landscape.html">BNPL landscape</a> and <a href="../payments/cancellation-and-payout.html">cancellation & payout</a> payments docs.</p>
|
||||
<blockquote><p><strong>Related:</strong> Data model — <a href="../data-model/08-bnpl.html">BNPL</a>.</p>
|
||||
</blockquote>
|
||||
<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>
|
||||
@@ -0,0 +1,27 @@
|
||||
# 9. Installments / BNPL
|
||||
|
||||
[← Business Requirements](index.md)
|
||||
|
||||
## (a) Business requirements
|
||||
- BNPL is offered as an alternative checkout. The decisive, verified model is **full-upfront settlement**: on approval the BNPL provider pays Balinyaar the **full booking amount in one lump, net of the provider's merchant commission**, and **bears 100% of customer-default risk**. The customer's interest-free installment repayment (typically a 4-installment plan) is **owned entirely by the provider** and is **decoupled** from Balinyaar's escrow/EVV/payout cycle.
|
||||
- **Therefore a BNPL order is, in Balinyaar's books, identical to a card payment that lands net-of-fee in one inbound settlement.** Balinyaar **does NOT track customer installments, per-installment webhooks, or default propagation** — that fragile subsystem is intentionally not built.
|
||||
- A BNPL order is recorded once as a single inbound settlement in `bnpl_transactions` (1:1 with a payment transaction), capturing the provider, the merchant-of-record (Balinyaar), the external payment token / transaction id, `order_amount_irr`, `settled_amount_irr` (net of provider commission), `bnpl_commission_irr`, currency (converted at the boundary), an idempotent status state-machine (`eligible`/`token_issued`/`verified`/`settled`/`reverted`/`cancelled`/`failed`), `installment_count` (informational, default 4), `settled_at`, and the revert fields.
|
||||
- **BNPL refunds flow only customer ↔ provider ↔ Balinyaar** — never nurse→customer or Balinyaar→customer directly. Balinyaar initiates the reversal via the provider's revert (full) / cancel/update (partial, new amount strictly lower) API using the stored token; the provider cancels the customer's unpaid installments, restores their credit, and refunds any already-paid installment to the customer's bank in ~7–10 business days (asynchronous, owned by the provider). The refund still decomposes across the platform-fee and nurse-payout legs in Balinyaar's ledger.
|
||||
- **The nurse's payout is unchanged by BNPL:** computed from `gross_price_irr − balinyaar_commission_irr`, paid weekly after EVV + dispute window — the provider's commission is a **platform cost of accepting BNPL** and is **never** passed through to the nurse.
|
||||
|
||||
> **This is a summary. Deep BNPL provider mechanics, the exact revert/cancel/settle API flows, commission-as-config, settlement-timing nuances, and provider-specific behavior are specified in the payments docs — cross-reference the [BNPL landscape](../payments/bnpl-landscape.md) and [cancellation & payout](../payments/cancellation-and-payout.md) for implementation detail.**
|
||||
|
||||
## (b) Iran-specific considerations
|
||||
- Provider-financed Iranian BNPLs (SnappPay, Digipay, Tara, Torob Pay) are uniformly **full-upfront, provider-bears-risk, interest-free-to-customer**; only bank-financed POS loans (Lendo) charge the customer interest and are a poor fit for short, cancellable nursing visits.
|
||||
- **Settlement timing is contract-defined and may be gated on the customer's first installment** (daily / T+1-3 / weekly / 15-day) — "full amount" does not mean "instant cash." Timing is config + a per-transaction `settled_at`; weekly nurse payout may key off settlement actually received, never an assumption.
|
||||
- **Commission rate is per-contract and not public** (anecdotal 7–15% for SnappPay; Torob Pay's published 6.6%) — always a config field read from the actual settlement, never hardcoded.
|
||||
- Onboarding requires جواز کسب **and** اینماد for the Balinyaar/partner entity, and whether a multi-vendor re-disbursing marketplace qualifies as a single BNPL merchant is publicly undocumented — an ops/contracting task, not a schema dependency.
|
||||
|
||||
## (c) MVP vs DEFERRED
|
||||
- **MVP:** full-upfront BNPL via one provider modeled as a single inbound settlement (`bnpl_transactions`); provider-mediated revert/cancel refunds; nurse payout decoupled from BNPL; commission + settlement timing as config.
|
||||
- **DEFERRED:** customer installment tracking (`installment_entries` — **cut**, owned by the provider); tranched settlement (`bnpl_settlement_entries` modeled-only, added if a future provider tranches); multiple BNPL providers.
|
||||
|
||||
## (d) Supporting database entities
|
||||
**`bnpl_transactions`** (replaces the old `installment_plans`; the old `installment_entries` is cut), `payment_transactions`, `payment_webhook_events`, `refunds` (`refund_channel = 'bnpl_revert'`, `external_revert_reference`, `expected_customer_refund_eta`), `ledger_entries`. See the [BNPL landscape](../payments/bnpl-landscape.md) and [cancellation & payout](../payments/cancellation-and-payout.md) payments docs.
|
||||
|
||||
> **Related:** Data model — [BNPL](../data-model/08-bnpl.md).
|
||||
@@ -0,0 +1,57 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<title>10. Payouts to Nurses — 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 & ground truths</a></li></ul></div><div class="group"><div class="label">Business requirements</div><ul><li><a href="index.html">Overview & MVP scope</a></li><li><a href="01-actors-and-onboarding.html">1. Actors & 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 & pricing</a></li><li><a href="04-search-and-matching.html">4. Search & matching</a></li><li><a href="05-booking-and-scheduling.html">5. Booking & 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 & refunds</a></li><li><a href="08-payments-and-escrow.html">8. Payments & escrow</a></li><li><a href="09-installments-bnpl.html">9. Installments / BNPL</a></li><li><a class="active" href="10-payouts.html">10. Payouts to nurses</a></li><li><a href="11-reviews-trust-and-safety.html">11. Reviews, trust & safety</a></li><li><a href="12-messaging-and-emergencies.html">12. Messaging & emergencies</a></li><li><a href="13-tax-invoicing-and-legal.html">13. Tax, invoicing & legal</a></li><li><a href="14-notifications-and-admin.html">14. Notifications & admin</a></li></ul></div><div class="group"><div class="label">Database model</div><ul><li><a href="../data-model/index.html">Overview & 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 & 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 & pricing</a></li><li><a href="../data-model/04-verification-and-credentials.html">4. Verification & credentials</a></li><li><a href="../data-model/05-booking-and-scheduling.html">5. Booking & scheduling</a></li><li><a href="../data-model/06-payments-ledger-and-refunds.html">6. Payments, ledger & 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 & 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 & reference</a></li><li><a href="../data-model/13-partner-centers-and-future.html">13. Partner centers & future</a></li></ul></div><div class="group"><div class="label">Payments deep-dive</div><ul><li><a href="../payments/index.html">Overview & 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 & finding</a></li><li><a href="../payments/cancellation-and-payout.html">Cancellation & nurse payout</a></li><li><a href="../payments/integration-notes.html">Integration & schema touchpoints</a></li><li><a href="../payments/sources.html">Recommendations & sources</a></li></ul></div><div class="group"><div class="label">Research & strategy</div><ul><li><a href="../research/index.html">Overview & exec summary</a></li><li><a href="../research/market-and-competitors.html">Market & competitors</a></li><li><a href="../research/problems-and-risks.html">Problems & 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 & sources</a></li></ul></div><div class="group"><div class="label">Notes & 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="10-payouts-to-nurses">10. Payouts to Nurses</h1>
|
||||
<p><a href="index.html">← Business Requirements</a></p>
|
||||
<h2 id="a-business-requirements">(a) Business requirements <a class="anchor" href="#a-business-requirements" aria-hidden="true">#</a></h2>
|
||||
<ul>
|
||||
<li>Nurses are paid in <strong>weekly batches</strong>. A batch aggregates the amounts owed for completed, payout-eligible bookings/sessions and produces one payout per nurse with earnings in that window.</li>
|
||||
<li><strong>Payout eligibility is gated on EVV completion AND a closed dispute window.</strong> A booking/session enters a batch only when <code>status = 'completed'</code> AND <code>dispute_window_ends_at < now()</code> (the dispute window is config-driven, default 72h post-completion). This deliberately prevents paying a nurse before a dispute can surface, shrinking clawback frequency — important because an Iranian bank transfer, once sent, is effectively irreversible.</li>
|
||||
<li>The nurse payout amount derives from <code>gross_price_irr − balinyaar_commission_irr</code> (never from a BNPL provider's net settlement).</li>
|
||||
<li><strong>Clawbacks</strong> (<code>nurse_clawbacks</code>) handle the refund-after-payout case: if a booking is refunded/disputed <strong>after</strong> the nurse was already paid, a clawback receivable is recorded (negative ledger entry against the nurse) and recovered by <strong>netting against the nurse's next weekly batch</strong>, or written off if uncollectable. The nurse's payable balance is <strong>derived from the ledger</strong> (it may go negative), and a batch can net prior clawbacks (<code>gross_earnings</code>, <code>clawback_applied</code>, <code>net_amount</code>).</li>
|
||||
<li><strong>Each booking is paid at most once</strong> (the payout↔booking link is unique), preventing double-pay across batches.</li>
|
||||
<li><strong>Bank-holiday-aware scheduling.</strong> Payout period-end and processing dates are shifted off bank-closed days using a shared <code>iranian_holidays</code> calendar — a weekly payout landing on a multi-day Nowruz closure would otherwise fail, since PAYA/SATNA transfers do not settle on closed days.</li>
|
||||
<li>Payouts go to the nurse's <strong>verified, registered primary IBAN</strong>, with the IBAN snapshotted and a transfer reference stored for reconciliation. Each payout item carries a unique track id + (for batches) a batch id.</li>
|
||||
</ul>
|
||||
<h2 id="b-iran-specific-considerations">(b) Iran-specific considerations <a class="anchor" href="#b-iran-specific-considerations" aria-hidden="true">#</a></h2>
|
||||
<ul>
|
||||
<li>Payouts are <strong>real bank transfers to registered IBANs</strong> (PAYA/SATNA cycles, next-business-day on holidays) — there is no chargeback-style reversal, which is <em>why</em> the dispute window must close before payout and why clawback is a netting/receivable mechanism rather than an automatic reversal.</li>
|
||||
<li>Provider settlement cut-offs (Toman/Jibit) mean payout must tolerate a provider being unavailable mid-cycle; the batch + reconciliation references survive a swap.</li>
|
||||
<li>Each nurse must have a Shahkar/KYC-verified, IBAN-ownership-checked account registered as a beneficiary before any payout targets it.</li>
|
||||
</ul>
|
||||
<h2 id="c-mvp-vs-deferred">(c) MVP vs DEFERRED <a class="anchor" href="#c-mvp-vs-deferred" aria-hidden="true">#</a></h2>
|
||||
<ul>
|
||||
<li><strong>MVP:</strong> weekly batches; EVV + dispute-window gating; per-session accrual for engagements; <code>nurse_clawbacks</code> with next-batch netting and write-off; unique booking↔payout link; <code>iranian_holidays</code>-aware scheduling; verified-IBAN payouts with reconciliation references.</li>
|
||||
<li><strong>DEFERRED:</strong> on-demand / instant nurse withdrawal; per-nurse configurable payout frequency; automated clawback recovery beyond netting.</li>
|
||||
</ul>
|
||||
<h2 id="d-supporting-database-entities">(d) Supporting database entities <a class="anchor" href="#d-supporting-database-entities" aria-hidden="true">#</a></h2>
|
||||
<p><code>nurse_payout_batches</code>, <code>nurse_payouts</code> (with <code>gross_earnings_irr</code>, <code>clawback_applied_irr</code>, <code>net_amount_irr</code>, <code>iban_snapshot</code>), <code>nurse_payout_booking_links</code> (unique per booking), <strong><code>nurse_clawbacks</code></strong>, <code>ledger_entries</code>, <strong><code>iranian_holidays</code></strong>, <code>bookings.dispute_window_ends_at</code>, <code>nurse_bank_accounts</code>.</p>
|
||||
<blockquote><p><strong>Related:</strong> Data model — <a href="../data-model/07-payouts.html">Payouts</a>.</p>
|
||||
</blockquote>
|
||||
<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>
|
||||
@@ -0,0 +1,26 @@
|
||||
# 10. Payouts to Nurses
|
||||
|
||||
[← Business Requirements](index.md)
|
||||
|
||||
## (a) Business requirements
|
||||
- Nurses are paid in **weekly batches**. A batch aggregates the amounts owed for completed, payout-eligible bookings/sessions and produces one payout per nurse with earnings in that window.
|
||||
- **Payout eligibility is gated on EVV completion AND a closed dispute window.** A booking/session enters a batch only when `status = 'completed'` AND `dispute_window_ends_at < now()` (the dispute window is config-driven, default 72h post-completion). This deliberately prevents paying a nurse before a dispute can surface, shrinking clawback frequency — important because an Iranian bank transfer, once sent, is effectively irreversible.
|
||||
- The nurse payout amount derives from `gross_price_irr − balinyaar_commission_irr` (never from a BNPL provider's net settlement).
|
||||
- **Clawbacks** (`nurse_clawbacks`) handle the refund-after-payout case: if a booking is refunded/disputed **after** the nurse was already paid, a clawback receivable is recorded (negative ledger entry against the nurse) and recovered by **netting against the nurse's next weekly batch**, or written off if uncollectable. The nurse's payable balance is **derived from the ledger** (it may go negative), and a batch can net prior clawbacks (`gross_earnings`, `clawback_applied`, `net_amount`).
|
||||
- **Each booking is paid at most once** (the payout↔booking link is unique), preventing double-pay across batches.
|
||||
- **Bank-holiday-aware scheduling.** Payout period-end and processing dates are shifted off bank-closed days using a shared `iranian_holidays` calendar — a weekly payout landing on a multi-day Nowruz closure would otherwise fail, since PAYA/SATNA transfers do not settle on closed days.
|
||||
- Payouts go to the nurse's **verified, registered primary IBAN**, with the IBAN snapshotted and a transfer reference stored for reconciliation. Each payout item carries a unique track id + (for batches) a batch id.
|
||||
|
||||
## (b) Iran-specific considerations
|
||||
- Payouts are **real bank transfers to registered IBANs** (PAYA/SATNA cycles, next-business-day on holidays) — there is no chargeback-style reversal, which is *why* the dispute window must close before payout and why clawback is a netting/receivable mechanism rather than an automatic reversal.
|
||||
- Provider settlement cut-offs (Toman/Jibit) mean payout must tolerate a provider being unavailable mid-cycle; the batch + reconciliation references survive a swap.
|
||||
- Each nurse must have a Shahkar/KYC-verified, IBAN-ownership-checked account registered as a beneficiary before any payout targets it.
|
||||
|
||||
## (c) MVP vs DEFERRED
|
||||
- **MVP:** weekly batches; EVV + dispute-window gating; per-session accrual for engagements; `nurse_clawbacks` with next-batch netting and write-off; unique booking↔payout link; `iranian_holidays`-aware scheduling; verified-IBAN payouts with reconciliation references.
|
||||
- **DEFERRED:** on-demand / instant nurse withdrawal; per-nurse configurable payout frequency; automated clawback recovery beyond netting.
|
||||
|
||||
## (d) Supporting database entities
|
||||
`nurse_payout_batches`, `nurse_payouts` (with `gross_earnings_irr`, `clawback_applied_irr`, `net_amount_irr`, `iban_snapshot`), `nurse_payout_booking_links` (unique per booking), **`nurse_clawbacks`**, `ledger_entries`, **`iranian_holidays`**, `bookings.dispute_window_ends_at`, `nurse_bank_accounts`.
|
||||
|
||||
> **Related:** Data model — [Payouts](../data-model/07-payouts.md).
|
||||
@@ -0,0 +1,53 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<title>11. Reviews, Trust & Safety — 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 & ground truths</a></li></ul></div><div class="group"><div class="label">Business requirements</div><ul><li><a href="index.html">Overview & MVP scope</a></li><li><a href="01-actors-and-onboarding.html">1. Actors & 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 & pricing</a></li><li><a href="04-search-and-matching.html">4. Search & matching</a></li><li><a href="05-booking-and-scheduling.html">5. Booking & 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 & refunds</a></li><li><a href="08-payments-and-escrow.html">8. Payments & 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 class="active" href="11-reviews-trust-and-safety.html">11. Reviews, trust & safety</a></li><li><a href="12-messaging-and-emergencies.html">12. Messaging & emergencies</a></li><li><a href="13-tax-invoicing-and-legal.html">13. Tax, invoicing & legal</a></li><li><a href="14-notifications-and-admin.html">14. Notifications & admin</a></li></ul></div><div class="group"><div class="label">Database model</div><ul><li><a href="../data-model/index.html">Overview & 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 & 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 & pricing</a></li><li><a href="../data-model/04-verification-and-credentials.html">4. Verification & credentials</a></li><li><a href="../data-model/05-booking-and-scheduling.html">5. Booking & scheduling</a></li><li><a href="../data-model/06-payments-ledger-and-refunds.html">6. Payments, ledger & 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 & 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 & reference</a></li><li><a href="../data-model/13-partner-centers-and-future.html">13. Partner centers & future</a></li></ul></div><div class="group"><div class="label">Payments deep-dive</div><ul><li><a href="../payments/index.html">Overview & 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 & finding</a></li><li><a href="../payments/cancellation-and-payout.html">Cancellation & nurse payout</a></li><li><a href="../payments/integration-notes.html">Integration & schema touchpoints</a></li><li><a href="../payments/sources.html">Recommendations & sources</a></li></ul></div><div class="group"><div class="label">Research & strategy</div><ul><li><a href="../research/index.html">Overview & exec summary</a></li><li><a href="../research/market-and-competitors.html">Market & competitors</a></li><li><a href="../research/problems-and-risks.html">Problems & 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 & sources</a></li></ul></div><div class="group"><div class="label">Notes & 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="11-reviews-trust-safety">11. Reviews, Trust & Safety</h1>
|
||||
<p><a href="index.html">← Business Requirements</a></p>
|
||||
<h2 id="a-business-requirements">(a) Business requirements <a class="anchor" href="#a-business-requirements" aria-hidden="true">#</a></h2>
|
||||
<ul>
|
||||
<li>A customer can leave <strong>one review per completed booking</strong> (rating 1–5 + free text), tied to a verified, completed, on-platform booking.</li>
|
||||
<li><strong>Moderation:</strong> reviews enter <code>pending_moderation</code> and are not public until approved by an admin (or an AI moderator). Aggregate nurse rating/counts are recomputed on <strong>every</strong> review status transition — publish, <strong>hide</strong>, reject, unpublish — so hiding a 1-star review never leaves a stale, inflated average.</li>
|
||||
<li><strong>Low-rating alerting:</strong> a rating at or below a configurable threshold (default ≤ 2) with negative content automatically raises a <code>support_alerts</code> row for the support team to investigate.</li>
|
||||
<li><strong>Incident handling:</strong> rapid-response protocols with immediate suspension on credible complaints; structured family check-ins and easy in-app concern flagging (the patient is not the sole information source); high-acuity cases routed only to appropriately verified nurses.</li>
|
||||
</ul>
|
||||
<h2 id="b-iran-specific-considerations">(b) Iran-specific considerations <a class="anchor" href="#b-iran-specific-considerations" aria-hidden="true">#</a></h2>
|
||||
<ul>
|
||||
<li>The buyers are <strong>vulnerable people</strong> cared for <strong>unobserved at home</strong>; a single incident can destroy a fragile, trust-first brand — so moderation, low-rating alerting, and immediate suspension are core, not optional.</li>
|
||||
<li>Verified-trust is the brand; reviews must be bound to real completed bookings to resist fake-review fraud (gig-marketplace fraud is ~2× elsewhere, mostly impersonation).</li>
|
||||
</ul>
|
||||
<h2 id="c-mvp-vs-deferred">(c) MVP vs DEFERRED <a class="anchor" href="#c-mvp-vs-deferred" aria-hidden="true">#</a></h2>
|
||||
<ul>
|
||||
<li><strong>MVP:</strong> one-per-completed-booking customer reviews; moderation with full recompute-on-every-transition; low-rating <code>support_alerts</code>; manual incident suspension.</li>
|
||||
<li><strong>DEFERRED:</strong> two-way (nurse-reviews-customer) double-blind reviews with timed reveal; structured review-tag aggregation (<code>review_tags_master</code> / <code>review_tag_links</code> modeled but a phase-2 nicety); a dedicated <code>incidents</code> entity; ML fraud scoring.</li>
|
||||
</ul>
|
||||
<h2 id="d-supporting-database-entities">(d) Supporting database entities <a class="anchor" href="#d-supporting-database-entities" aria-hidden="true">#</a></h2>
|
||||
<p><code>reviews</code> (moderation status, recompute triggers), <code>review_tags_master</code>, <code>review_tag_links</code>, <code>support_alerts</code> (low-rating, fraud-signal), <code>nurse_profiles</code> (denormalized aggregates), <code>audit_logs</code>.</p>
|
||||
<blockquote><p><strong>Related:</strong> Data model — <a href="../data-model/10-reviews-and-records.html">Reviews & Records</a>.</p>
|
||||
</blockquote>
|
||||
<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>
|
||||
@@ -0,0 +1,22 @@
|
||||
# 11. Reviews, Trust & Safety
|
||||
|
||||
[← Business Requirements](index.md)
|
||||
|
||||
## (a) Business requirements
|
||||
- A customer can leave **one review per completed booking** (rating 1–5 + free text), tied to a verified, completed, on-platform booking.
|
||||
- **Moderation:** reviews enter `pending_moderation` and are not public until approved by an admin (or an AI moderator). Aggregate nurse rating/counts are recomputed on **every** review status transition — publish, **hide**, reject, unpublish — so hiding a 1-star review never leaves a stale, inflated average.
|
||||
- **Low-rating alerting:** a rating at or below a configurable threshold (default ≤ 2) with negative content automatically raises a `support_alerts` row for the support team to investigate.
|
||||
- **Incident handling:** rapid-response protocols with immediate suspension on credible complaints; structured family check-ins and easy in-app concern flagging (the patient is not the sole information source); high-acuity cases routed only to appropriately verified nurses.
|
||||
|
||||
## (b) Iran-specific considerations
|
||||
- The buyers are **vulnerable people** cared for **unobserved at home**; a single incident can destroy a fragile, trust-first brand — so moderation, low-rating alerting, and immediate suspension are core, not optional.
|
||||
- Verified-trust is the brand; reviews must be bound to real completed bookings to resist fake-review fraud (gig-marketplace fraud is ~2× elsewhere, mostly impersonation).
|
||||
|
||||
## (c) MVP vs DEFERRED
|
||||
- **MVP:** one-per-completed-booking customer reviews; moderation with full recompute-on-every-transition; low-rating `support_alerts`; manual incident suspension.
|
||||
- **DEFERRED:** two-way (nurse-reviews-customer) double-blind reviews with timed reveal; structured review-tag aggregation (`review_tags_master` / `review_tag_links` modeled but a phase-2 nicety); a dedicated `incidents` entity; ML fraud scoring.
|
||||
|
||||
## (d) Supporting database entities
|
||||
`reviews` (moderation status, recompute triggers), `review_tags_master`, `review_tag_links`, `support_alerts` (low-rating, fraud-signal), `nurse_profiles` (denormalized aggregates), `audit_logs`.
|
||||
|
||||
> **Related:** Data model — [Reviews & Records](../data-model/10-reviews-and-records.md).
|
||||
@@ -0,0 +1,53 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<title>12. Messaging & On-Site Emergencies — 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 & ground truths</a></li></ul></div><div class="group"><div class="label">Business requirements</div><ul><li><a href="index.html">Overview & MVP scope</a></li><li><a href="01-actors-and-onboarding.html">1. Actors & 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 & pricing</a></li><li><a href="04-search-and-matching.html">4. Search & matching</a></li><li><a href="05-booking-and-scheduling.html">5. Booking & 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 & refunds</a></li><li><a href="08-payments-and-escrow.html">8. Payments & 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 & safety</a></li><li><a class="active" href="12-messaging-and-emergencies.html">12. Messaging & emergencies</a></li><li><a href="13-tax-invoicing-and-legal.html">13. Tax, invoicing & legal</a></li><li><a href="14-notifications-and-admin.html">14. Notifications & admin</a></li></ul></div><div class="group"><div class="label">Database model</div><ul><li><a href="../data-model/index.html">Overview & 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 & 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 & pricing</a></li><li><a href="../data-model/04-verification-and-credentials.html">4. Verification & credentials</a></li><li><a href="../data-model/05-booking-and-scheduling.html">5. Booking & scheduling</a></li><li><a href="../data-model/06-payments-ledger-and-refunds.html">6. Payments, ledger & 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 & 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 & reference</a></li><li><a href="../data-model/13-partner-centers-and-future.html">13. Partner centers & future</a></li></ul></div><div class="group"><div class="label">Payments deep-dive</div><ul><li><a href="../payments/index.html">Overview & 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 & finding</a></li><li><a href="../payments/cancellation-and-payout.html">Cancellation & nurse payout</a></li><li><a href="../payments/integration-notes.html">Integration & schema touchpoints</a></li><li><a href="../payments/sources.html">Recommendations & sources</a></li></ul></div><div class="group"><div class="label">Research & strategy</div><ul><li><a href="../research/index.html">Overview & exec summary</a></li><li><a href="../research/market-and-competitors.html">Market & competitors</a></li><li><a href="../research/problems-and-risks.html">Problems & 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 & sources</a></li></ul></div><div class="group"><div class="label">Notes & 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="12-messaging-on-site-emergencies">12. Messaging & On-Site Emergencies</h1>
|
||||
<p><a href="index.html">← Business Requirements</a></p>
|
||||
<h2 id="a-business-requirements">(a) Business requirements <a class="anchor" href="#a-business-requirements" aria-hidden="true">#</a></h2>
|
||||
<ul>
|
||||
<li><strong>There is no live chat and no direct nurse↔customer messaging.</strong> All post-booking communication runs through a structured <strong>ticket</strong> system that admin can read in full. This is a deliberate <strong>anti-disintermediation</strong> and <strong>patient-safety</strong> design: it protects vulnerable patients, creates a dispute paper trail, and prevents families and nurses pairing off-platform.</li>
|
||||
<li>A <strong>booking-scoped coordination ticket</strong> is auto-created so the nurse and customer can coordinate logistics (arrival time, room location) under admin visibility. Internal admin-only notes are supported and never shown to users.</li>
|
||||
<li>Tickets also carry refund conversations and any support request, and are the mandatory anchor for admin refunds (Section 7).</li>
|
||||
<li><strong>On-site emergency playbook.</strong> The ticket system is async and has no real-time channel, so the operational playbook is explicit: <strong>in an emergency (no answer at the door, a medical emergency), the nurse calls the emergency-contact number surfaced in the app, then opens a ticket.</strong> The emergency contact number is surfaced prominently in the booking UI (drawn from encrypted care instructions), so a nurse never needs to find the family's number by other means (which would break the platform's communication control).</li>
|
||||
</ul>
|
||||
<h2 id="b-iran-specific-considerations">(b) Iran-specific considerations <a class="anchor" href="#b-iran-specific-considerations" aria-hidden="true">#</a></h2>
|
||||
<ul>
|
||||
<li>Disintermediation is the predictable failure mode of recurring, relationship-based care; the ticket-only model retains value (escrow, dispute protection, backup coverage, insurance that only applies on-platform) instead of relying on punitive lock-in.</li>
|
||||
<li>For unobserved in-home care of patients who cannot self-report, the controlled-but-auditable communication channel plus a clear emergency escalation path is a safety requirement.</li>
|
||||
</ul>
|
||||
<h2 id="c-mvp-vs-deferred">(c) MVP vs DEFERRED <a class="anchor" href="#c-mvp-vs-deferred" aria-hidden="true">#</a></h2>
|
||||
<ul>
|
||||
<li><strong>MVP:</strong> ticket-only messaging (admin-readable); auto-created booking-coordination ticket; internal notes; prominent in-app emergency contact + documented playbook.</li>
|
||||
<li><strong>DEFERRED:</strong> real-time chat; a first-class <code>incidents</code>/emergency-event entity with SLA; push/real-time alerting.</li>
|
||||
</ul>
|
||||
<h2 id="d-supporting-database-entities">(d) Supporting database entities <a class="anchor" href="#d-supporting-database-entities" aria-hidden="true">#</a></h2>
|
||||
<p><code>tickets</code>, <code>ticket_participants</code>, <code>ticket_messages</code>, <code>booking_care_instructions</code> (encrypted emergency contact), <code>support_alerts</code>.</p>
|
||||
<blockquote><p><strong>Related:</strong> Data model — <a href="../data-model/09-messaging.html">Messaging</a>.</p>
|
||||
</blockquote>
|
||||
<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>
|
||||
@@ -0,0 +1,22 @@
|
||||
# 12. Messaging & On-Site Emergencies
|
||||
|
||||
[← Business Requirements](index.md)
|
||||
|
||||
## (a) Business requirements
|
||||
- **There is no live chat and no direct nurse↔customer messaging.** All post-booking communication runs through a structured **ticket** system that admin can read in full. This is a deliberate **anti-disintermediation** and **patient-safety** design: it protects vulnerable patients, creates a dispute paper trail, and prevents families and nurses pairing off-platform.
|
||||
- A **booking-scoped coordination ticket** is auto-created so the nurse and customer can coordinate logistics (arrival time, room location) under admin visibility. Internal admin-only notes are supported and never shown to users.
|
||||
- Tickets also carry refund conversations and any support request, and are the mandatory anchor for admin refunds (Section 7).
|
||||
- **On-site emergency playbook.** The ticket system is async and has no real-time channel, so the operational playbook is explicit: **in an emergency (no answer at the door, a medical emergency), the nurse calls the emergency-contact number surfaced in the app, then opens a ticket.** The emergency contact number is surfaced prominently in the booking UI (drawn from encrypted care instructions), so a nurse never needs to find the family's number by other means (which would break the platform's communication control).
|
||||
|
||||
## (b) Iran-specific considerations
|
||||
- Disintermediation is the predictable failure mode of recurring, relationship-based care; the ticket-only model retains value (escrow, dispute protection, backup coverage, insurance that only applies on-platform) instead of relying on punitive lock-in.
|
||||
- For unobserved in-home care of patients who cannot self-report, the controlled-but-auditable communication channel plus a clear emergency escalation path is a safety requirement.
|
||||
|
||||
## (c) MVP vs DEFERRED
|
||||
- **MVP:** ticket-only messaging (admin-readable); auto-created booking-coordination ticket; internal notes; prominent in-app emergency contact + documented playbook.
|
||||
- **DEFERRED:** real-time chat; a first-class `incidents`/emergency-event entity with SLA; push/real-time alerting.
|
||||
|
||||
## (d) Supporting database entities
|
||||
`tickets`, `ticket_participants`, `ticket_messages`, `booking_care_instructions` (encrypted emergency contact), `support_alerts`.
|
||||
|
||||
> **Related:** Data model — [Messaging](../data-model/09-messaging.md).
|
||||
@@ -0,0 +1,55 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<title>13. Tax, Invoicing & Legal — 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 & ground truths</a></li></ul></div><div class="group"><div class="label">Business requirements</div><ul><li><a href="index.html">Overview & MVP scope</a></li><li><a href="01-actors-and-onboarding.html">1. Actors & 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 & pricing</a></li><li><a href="04-search-and-matching.html">4. Search & matching</a></li><li><a href="05-booking-and-scheduling.html">5. Booking & 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 & refunds</a></li><li><a href="08-payments-and-escrow.html">8. Payments & 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 & safety</a></li><li><a href="12-messaging-and-emergencies.html">12. Messaging & emergencies</a></li><li><a class="active" href="13-tax-invoicing-and-legal.html">13. Tax, invoicing & legal</a></li><li><a href="14-notifications-and-admin.html">14. Notifications & admin</a></li></ul></div><div class="group"><div class="label">Database model</div><ul><li><a href="../data-model/index.html">Overview & 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 & 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 & pricing</a></li><li><a href="../data-model/04-verification-and-credentials.html">4. Verification & credentials</a></li><li><a href="../data-model/05-booking-and-scheduling.html">5. Booking & scheduling</a></li><li><a href="../data-model/06-payments-ledger-and-refunds.html">6. Payments, ledger & 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 & 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 & reference</a></li><li><a href="../data-model/13-partner-centers-and-future.html">13. Partner centers & future</a></li></ul></div><div class="group"><div class="label">Payments deep-dive</div><ul><li><a href="../payments/index.html">Overview & 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 & finding</a></li><li><a href="../payments/cancellation-and-payout.html">Cancellation & nurse payout</a></li><li><a href="../payments/integration-notes.html">Integration & schema touchpoints</a></li><li><a href="../payments/sources.html">Recommendations & sources</a></li></ul></div><div class="group"><div class="label">Research & strategy</div><ul><li><a href="../research/index.html">Overview & exec summary</a></li><li><a href="../research/market-and-competitors.html">Market & competitors</a></li><li><a href="../research/problems-and-risks.html">Problems & 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 & sources</a></li></ul></div><div class="group"><div class="label">Notes & 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="13-tax-invoicing-legal">13. Tax, Invoicing & Legal</h1>
|
||||
<p><a href="index.html">← Business Requirements</a></p>
|
||||
<h2 id="a-business-requirements">(a) Business requirements <a class="anchor" href="#a-business-requirements" aria-hidden="true">#</a></h2>
|
||||
<ul>
|
||||
<li><strong>The nurse is the taxable seller of the nursing service; Balinyaar is the taxable seller only of its commission.</strong> This mirrors the Snapp/Tapsi sharing-economy precedent: the nurse's fee is the nurse's income (the nurse files their own income tax — out of Balinyaar's scope), and Balinyaar's commission is the company's VAT-relevant revenue.</li>
|
||||
<li><strong>VAT is 10%</strong> (configurable), applied to Balinyaar's commission line. The home-nursing <strong>service's</strong> own VAT treatment is <strong>unconfirmed</strong> (medical services are commonly exempt) — so the VAT field is config-driven and can be 0/exempt, keeping the model correct whichever way the ruling lands. Confirm with an Iranian tax advisor before launch.</li>
|
||||
<li><strong>سامانه مودیان (taxpayer system) readiness, minimal footprint.</strong> The platform produces a minimal <code>invoices</code> record per booking capturing the gross, the platform commission, any BNPL commission, VAT, and a place for the مودیان reference fields (22-digit fiscal number, memory tax id, status) and PDF. The seller issues the invoice (the buyer cannot), so Balinyaar issues only its own <strong>commission</strong> invoice; it does not issue the nurse's service invoice.</li>
|
||||
<li><strong>e-namad (نماد اعتماد الکترونیکی)</strong> is de-facto mandatory: a monetized Iranian site needs e-namad to obtain an online payment gateway from PSP/Shaparak. It is held by the legal launch entity.</li>
|
||||
<li><strong>Partner licensed-center (Asanism-style) as the launch legal vehicle.</strong> Home nursing is a <strong>licensed healthcare activity</strong> (MoH establishment permit پروانه تأسیس + technical-director license پروانه مسئول فنی via the Article-20 commission), in the <strong>home-nursing-services-center</strong> track (a nurse with BSc + ≥5 yrs experience can found/direct it). The fast, legal go-to-market is to <strong>partner with already-licensed centers</strong> while Balinyaar's own permit is pending. A <code>partner_centers</code> entity represents the licensed center that holds the جواز کسب + اینماد + MoH license, sponsors nurses, and <strong>may be the merchant-of-record / invoice issuer</strong> for payments — making BNPL and online payment legally feasible without each nurse holding a license.</li>
|
||||
</ul>
|
||||
<h2 id="b-iran-specific-considerations">(b) Iran-specific considerations <a class="anchor" href="#b-iran-specific-considerations" aria-hidden="true">#</a></h2>
|
||||
<ul>
|
||||
<li>Operating <strong>without</strong> a permit is the real legal risk (penalty ladder up to permanent revocation + judicial referral). The partner-center vehicle is the launch-critical mechanism that makes the whole money flow legal.</li>
|
||||
<li>مودیان obligation phases in by revenue thresholds; most individual nurses fall below mandatory thresholds early, but the <strong>platform's commission line is VAT/e-invoice-relevant</strong> — so per-nurse مودیان obligation is a configurable flag and the platform's own commission invoicing is the in-scope obligation.</li>
|
||||
<li>The licensed center (not Balinyaar-the-tech-company, initially) is plausibly the IPG merchant-of-record and the invoice issuer — the data model represents this explicitly.</li>
|
||||
</ul>
|
||||
<h2 id="c-mvp-vs-deferred">(c) MVP vs DEFERRED <a class="anchor" href="#c-mvp-vs-deferred" aria-hidden="true">#</a></h2>
|
||||
<ul>
|
||||
<li><strong>MVP:</strong> <code>partner_centers</code> as the launch legal vehicle with merchant-of-record flag and nurse sponsorship; minimal per-booking <code>invoices</code> with 10% configurable VAT on commission and مودیان reference fields; e-namad held by the launch entity; nurse-as-taxable-seller / platform-as-commission-seller split.</li>
|
||||
<li><strong>DEFERRED:</strong> full مودیان e-invoice automation / digital-signature pipeline; nurse-side service-invoice issuance on the nurse's behalf; insurer/B2B-payor invoicing; the future employer-style <code>organizations</code> model.</li>
|
||||
</ul>
|
||||
<h2 id="d-supporting-database-entities">(d) Supporting database entities <a class="anchor" href="#d-supporting-database-entities" aria-hidden="true">#</a></h2>
|
||||
<p><strong><code>invoices</code></strong> (minimal, commission-focused, مودیان fields, VAT), <strong><code>partner_centers</code></strong> (MoH license, اینماد, merchant-of-record), <code>nurse_profiles.partner_center_id</code>, <code>payment_transactions</code> (Shaparak reference for reconciliation), <code>platform_configs</code> (VAT rate, merchant-of-record).</p>
|
||||
<blockquote><p><strong>Related:</strong> Data model — <a href="../data-model/13-partner-centers-and-future.html">Partner Centers & Future</a>; Research — <a href="../research/legal-landscape.html">Legal Landscape</a>.</p>
|
||||
</blockquote>
|
||||
<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>
|
||||
@@ -0,0 +1,24 @@
|
||||
# 13. Tax, Invoicing & Legal
|
||||
|
||||
[← Business Requirements](index.md)
|
||||
|
||||
## (a) Business requirements
|
||||
- **The nurse is the taxable seller of the nursing service; Balinyaar is the taxable seller only of its commission.** This mirrors the Snapp/Tapsi sharing-economy precedent: the nurse's fee is the nurse's income (the nurse files their own income tax — out of Balinyaar's scope), and Balinyaar's commission is the company's VAT-relevant revenue.
|
||||
- **VAT is 10%** (configurable), applied to Balinyaar's commission line. The home-nursing **service's** own VAT treatment is **unconfirmed** (medical services are commonly exempt) — so the VAT field is config-driven and can be 0/exempt, keeping the model correct whichever way the ruling lands. Confirm with an Iranian tax advisor before launch.
|
||||
- **سامانه مودیان (taxpayer system) readiness, minimal footprint.** The platform produces a minimal `invoices` record per booking capturing the gross, the platform commission, any BNPL commission, VAT, and a place for the مودیان reference fields (22-digit fiscal number, memory tax id, status) and PDF. The seller issues the invoice (the buyer cannot), so Balinyaar issues only its own **commission** invoice; it does not issue the nurse's service invoice.
|
||||
- **e-namad (نماد اعتماد الکترونیکی)** is de-facto mandatory: a monetized Iranian site needs e-namad to obtain an online payment gateway from PSP/Shaparak. It is held by the legal launch entity.
|
||||
- **Partner licensed-center (Asanism-style) as the launch legal vehicle.** Home nursing is a **licensed healthcare activity** (MoH establishment permit پروانه تأسیس + technical-director license پروانه مسئول فنی via the Article-20 commission), in the **home-nursing-services-center** track (a nurse with BSc + ≥5 yrs experience can found/direct it). The fast, legal go-to-market is to **partner with already-licensed centers** while Balinyaar's own permit is pending. A `partner_centers` entity represents the licensed center that holds the جواز کسب + اینماد + MoH license, sponsors nurses, and **may be the merchant-of-record / invoice issuer** for payments — making BNPL and online payment legally feasible without each nurse holding a license.
|
||||
|
||||
## (b) Iran-specific considerations
|
||||
- Operating **without** a permit is the real legal risk (penalty ladder up to permanent revocation + judicial referral). The partner-center vehicle is the launch-critical mechanism that makes the whole money flow legal.
|
||||
- مودیان obligation phases in by revenue thresholds; most individual nurses fall below mandatory thresholds early, but the **platform's commission line is VAT/e-invoice-relevant** — so per-nurse مودیان obligation is a configurable flag and the platform's own commission invoicing is the in-scope obligation.
|
||||
- The licensed center (not Balinyaar-the-tech-company, initially) is plausibly the IPG merchant-of-record and the invoice issuer — the data model represents this explicitly.
|
||||
|
||||
## (c) MVP vs DEFERRED
|
||||
- **MVP:** `partner_centers` as the launch legal vehicle with merchant-of-record flag and nurse sponsorship; minimal per-booking `invoices` with 10% configurable VAT on commission and مودیان reference fields; e-namad held by the launch entity; nurse-as-taxable-seller / platform-as-commission-seller split.
|
||||
- **DEFERRED:** full مودیان e-invoice automation / digital-signature pipeline; nurse-side service-invoice issuance on the nurse's behalf; insurer/B2B-payor invoicing; the future employer-style `organizations` model.
|
||||
|
||||
## (d) Supporting database entities
|
||||
**`invoices`** (minimal, commission-focused, مودیان fields, VAT), **`partner_centers`** (MoH license, اینماد, merchant-of-record), `nurse_profiles.partner_center_id`, `payment_transactions` (Shaparak reference for reconciliation), `platform_configs` (VAT rate, merchant-of-record).
|
||||
|
||||
> **Related:** Data model — [Partner Centers & Future](../data-model/13-partner-centers-and-future.md); Research — [Legal Landscape](../research/legal-landscape.md).
|
||||
@@ -0,0 +1,61 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<title>14. Notifications & Admin / Backoffice — 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 & ground truths</a></li></ul></div><div class="group"><div class="label">Business requirements</div><ul><li><a href="index.html">Overview & MVP scope</a></li><li><a href="01-actors-and-onboarding.html">1. Actors & 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 & pricing</a></li><li><a href="04-search-and-matching.html">4. Search & matching</a></li><li><a href="05-booking-and-scheduling.html">5. Booking & 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 & refunds</a></li><li><a href="08-payments-and-escrow.html">8. Payments & 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 & safety</a></li><li><a href="12-messaging-and-emergencies.html">12. Messaging & emergencies</a></li><li><a href="13-tax-invoicing-and-legal.html">13. Tax, invoicing & legal</a></li><li><a class="active" href="14-notifications-and-admin.html">14. Notifications & admin</a></li></ul></div><div class="group"><div class="label">Database model</div><ul><li><a href="../data-model/index.html">Overview & 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 & 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 & pricing</a></li><li><a href="../data-model/04-verification-and-credentials.html">4. Verification & credentials</a></li><li><a href="../data-model/05-booking-and-scheduling.html">5. Booking & scheduling</a></li><li><a href="../data-model/06-payments-ledger-and-refunds.html">6. Payments, ledger & 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 & 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 & reference</a></li><li><a href="../data-model/13-partner-centers-and-future.html">13. Partner centers & future</a></li></ul></div><div class="group"><div class="label">Payments deep-dive</div><ul><li><a href="../payments/index.html">Overview & 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 & finding</a></li><li><a href="../payments/cancellation-and-payout.html">Cancellation & nurse payout</a></li><li><a href="../payments/integration-notes.html">Integration & schema touchpoints</a></li><li><a href="../payments/sources.html">Recommendations & sources</a></li></ul></div><div class="group"><div class="label">Research & strategy</div><ul><li><a href="../research/index.html">Overview & exec summary</a></li><li><a href="../research/market-and-competitors.html">Market & competitors</a></li><li><a href="../research/problems-and-risks.html">Problems & 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 & sources</a></li></ul></div><div class="group"><div class="label">Notes & 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="14-notifications-admin-backoffice">14. Notifications & Admin / Backoffice</h1>
|
||||
<p><a href="index.html">← Business Requirements</a></p>
|
||||
<h2 id="a-business-requirements">(a) Business requirements <a class="anchor" href="#a-business-requirements" aria-hidden="true">#</a></h2>
|
||||
<ul>
|
||||
<li><strong>In-app notifications</strong> to all user types for booking, payment, payout, review, verification, and alert events. Carried as typed in-app records the front-end fetches on load and uses to deep-link to the relevant entity. <strong>No push notifications at launch.</strong></li>
|
||||
<li>A retention job hard-deletes read notifications older than 90 days to keep the table bounded.</li>
|
||||
<li><strong>Admin / backoffice tooling</strong> must cover the operational spine:<ul>
|
||||
<li><strong>Verification queue</strong> — review uploaded MoH/INO/criminal-record documents, record structured credential numbers/expiries, pass/fail steps, and flip <code>is_verified</code> transactionally.</li>
|
||||
<li><strong>Refund tooling</strong> — initiate admin-only, ticket-linked refunds with tiered policy application and fee-leg decomposition; for BNPL, trigger the provider revert/cancel.</li>
|
||||
<li><strong>Payout tooling</strong> — initiate/inspect weekly batches, see eligibility (EVV + closed dispute window), apply clawback netting, schedule around bank holidays, and reconcile transfer references.</li>
|
||||
<li><strong>Support-alert console</strong> — triage low-rating, no-show, location-mismatch, expiry, and fraud-signal alerts.</li>
|
||||
<li><strong>RBAC</strong> — admin roles (super_admin / admin / support / finance / moderator) scope who can verify, refund, pay out, and moderate.</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>An <strong>append-only audit trail</strong> records every state-changing operation on sensitive entities (bookings, payments, refunds, verifications, reviews, users), and config changes (e.g., the platform fee rate) are auditable.</li>
|
||||
</ul>
|
||||
<h2 id="b-iran-specific-considerations">(b) Iran-specific considerations <a class="anchor" href="#b-iran-specific-considerations" aria-hidden="true">#</a></h2>
|
||||
<ul>
|
||||
<li>No push at launch reflects a pragmatic MVP and the in-app polling norm; SMS-OTP already covers the critical auth path.</li>
|
||||
<li>Back-office must reason over the Shamsi calendar and <code>iranian_holidays</code> for payout scheduling and deadline computation, and over the verification realities (manual MoH/INO checks, expiry-driven re-verification).</li>
|
||||
<li>High-volume logs (<code>audit_logs</code>, <code>system_events</code>, <code>notifications</code>) need partitioning/retention planned before launch to avoid unbounded growth.</li>
|
||||
</ul>
|
||||
<h2 id="c-mvp-vs-deferred">(c) MVP vs DEFERRED <a class="anchor" href="#c-mvp-vs-deferred" aria-hidden="true">#</a></h2>
|
||||
<ul>
|
||||
<li><strong>MVP:</strong> in-app notifications with 90-day retention; admin verification/refund/payout/alert tooling; RBAC; append-only <code>audit_logs</code>; config-change auditing.</li>
|
||||
<li><strong>DEFERRED:</strong> push notifications; SMS/email notification channels beyond OTP; a full analytics warehouse (<code>system_events</code> piped out rather than queried in the transactional DB); ML fraud console.</li>
|
||||
</ul>
|
||||
<h2 id="d-supporting-database-entities">(d) Supporting database entities <a class="anchor" href="#d-supporting-database-entities" aria-hidden="true">#</a></h2>
|
||||
<p><code>notifications</code>, <code>support_alerts</code>, <code>roles</code>, <code>user_roles</code>, <code>audit_logs</code>, <code>system_events</code>, <code>platform_configs</code>, plus the operational entities each tool acts on (<code>nurse_verifications</code> / <code>verification_steps</code> / <code>nurse_credentials</code>, <code>refunds</code>, <code>nurse_payout_batches</code> / <code>nurse_payouts</code> / <code>nurse_clawbacks</code>, <code>bookings</code>).</p>
|
||||
<blockquote><p><strong>Related:</strong> Data model — <a href="../data-model/12-audit-config-and-reference.html">Audit, Config & Reference</a>.</p>
|
||||
</blockquote>
|
||||
<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>
|
||||
@@ -0,0 +1,28 @@
|
||||
# 14. Notifications & Admin / Backoffice
|
||||
|
||||
[← Business Requirements](index.md)
|
||||
|
||||
## (a) Business requirements
|
||||
- **In-app notifications** to all user types for booking, payment, payout, review, verification, and alert events. Carried as typed in-app records the front-end fetches on load and uses to deep-link to the relevant entity. **No push notifications at launch.**
|
||||
- A retention job hard-deletes read notifications older than 90 days to keep the table bounded.
|
||||
- **Admin / backoffice tooling** must cover the operational spine:
|
||||
- **Verification queue** — review uploaded MoH/INO/criminal-record documents, record structured credential numbers/expiries, pass/fail steps, and flip `is_verified` transactionally.
|
||||
- **Refund tooling** — initiate admin-only, ticket-linked refunds with tiered policy application and fee-leg decomposition; for BNPL, trigger the provider revert/cancel.
|
||||
- **Payout tooling** — initiate/inspect weekly batches, see eligibility (EVV + closed dispute window), apply clawback netting, schedule around bank holidays, and reconcile transfer references.
|
||||
- **Support-alert console** — triage low-rating, no-show, location-mismatch, expiry, and fraud-signal alerts.
|
||||
- **RBAC** — admin roles (super_admin / admin / support / finance / moderator) scope who can verify, refund, pay out, and moderate.
|
||||
- An **append-only audit trail** records every state-changing operation on sensitive entities (bookings, payments, refunds, verifications, reviews, users), and config changes (e.g., the platform fee rate) are auditable.
|
||||
|
||||
## (b) Iran-specific considerations
|
||||
- No push at launch reflects a pragmatic MVP and the in-app polling norm; SMS-OTP already covers the critical auth path.
|
||||
- Back-office must reason over the Shamsi calendar and `iranian_holidays` for payout scheduling and deadline computation, and over the verification realities (manual MoH/INO checks, expiry-driven re-verification).
|
||||
- High-volume logs (`audit_logs`, `system_events`, `notifications`) need partitioning/retention planned before launch to avoid unbounded growth.
|
||||
|
||||
## (c) MVP vs DEFERRED
|
||||
- **MVP:** in-app notifications with 90-day retention; admin verification/refund/payout/alert tooling; RBAC; append-only `audit_logs`; config-change auditing.
|
||||
- **DEFERRED:** push notifications; SMS/email notification channels beyond OTP; a full analytics warehouse (`system_events` piped out rather than queried in the transactional DB); ML fraud console.
|
||||
|
||||
## (d) Supporting database entities
|
||||
`notifications`, `support_alerts`, `roles`, `user_roles`, `audit_logs`, `system_events`, `platform_configs`, plus the operational entities each tool acts on (`nurse_verifications` / `verification_steps` / `nurse_credentials`, `refunds`, `nurse_payout_batches` / `nurse_payouts` / `nurse_clawbacks`, `bookings`).
|
||||
|
||||
> **Related:** Data model — [Audit, Config & Reference](../data-model/12-audit-config-and-reference.md).
|
||||
@@ -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 & ground truths</a></li></ul></div><div class="group"><div class="label">Business requirements</div><ul><li><a class="active" href="index.html">Overview & MVP scope</a></li><li><a href="01-actors-and-onboarding.html">1. Actors & 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 & pricing</a></li><li><a href="04-search-and-matching.html">4. Search & matching</a></li><li><a href="05-booking-and-scheduling.html">5. Booking & 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 & refunds</a></li><li><a href="08-payments-and-escrow.html">8. Payments & 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 & safety</a></li><li><a href="12-messaging-and-emergencies.html">12. Messaging & emergencies</a></li><li><a href="13-tax-invoicing-and-legal.html">13. Tax, invoicing & legal</a></li><li><a href="14-notifications-and-admin.html">14. Notifications & admin</a></li></ul></div><div class="group"><div class="label">Database model</div><ul><li><a href="../data-model/index.html">Overview & 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 & 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 & pricing</a></li><li><a href="../data-model/04-verification-and-credentials.html">4. Verification & credentials</a></li><li><a href="../data-model/05-booking-and-scheduling.html">5. Booking & scheduling</a></li><li><a href="../data-model/06-payments-ledger-and-refunds.html">6. Payments, ledger & 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 & 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 & reference</a></li><li><a href="../data-model/13-partner-centers-and-future.html">13. Partner centers & future</a></li></ul></div><div class="group"><div class="label">Payments deep-dive</div><ul><li><a href="../payments/index.html">Overview & 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 & finding</a></li><li><a href="../payments/cancellation-and-payout.html">Cancellation & nurse payout</a></li><li><a href="../payments/integration-notes.html">Integration & schema touchpoints</a></li><li><a href="../payments/sources.html">Recommendations & sources</a></li></ul></div><div class="group"><div class="label">Research & strategy</div><ul><li><a href="../research/index.html">Overview & exec summary</a></li><li><a href="../research/market-and-competitors.html">Market & competitors</a></li><li><a href="../research/problems-and-risks.html">Problems & 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 & sources</a></li></ul></div><div class="group"><div class="label">Notes & 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 & 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 & 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 & Pricing</a> — admin-defined catalog skeleton, nurse-priced variants, and the five price units.</li>
|
||||
<li><a href="04-search-and-matching.html">Search & Matching</a> — geo/category search, the denormalized search index, and same-gender caregiver matching.</li>
|
||||
<li><a href="05-booking-and-scheduling.html">Booking & 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 & Refunds</a> — tiered, snapshotted policies and admin-only, ticket-linked refunds.</li>
|
||||
<li><a href="08-payments-and-escrow.html">Payments & 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 & Safety</a> — one-per-booking moderated reviews, low-rating alerting, and incident handling.</li>
|
||||
<li><a href="12-messaging-and-emergencies.html">Messaging & 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 & 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 & 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 & 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>
|
||||
@@ -0,0 +1,58 @@
|
||||
# Business Requirements
|
||||
|
||||
> **Purpose.** This document specifies the business requirements for **Balinyaar**, 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 *through* 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 **not naive** about Iranian payment law, tax, and the realities of caring for vulnerable people at home. All monetary values are in **IRR (Rials)**; Toman is a display concern only and is converted to/from Rials solely at an external provider's API boundary.
|
||||
|
||||
**Date:** 2026-06-20
|
||||
|
||||
These sections assume the four [cross-cutting ground truths](../overview/platform-summary.md).
|
||||
|
||||
---
|
||||
|
||||
## How to read this document
|
||||
|
||||
Each section covers one business area and states, in order:
|
||||
|
||||
- **(a) Business requirements** — what the platform must do.
|
||||
- **(b) Iran-specific considerations** — the local legal, fiscal, cultural, and infrastructural realities that shape the requirement.
|
||||
- **(c) MVP vs DEFERRED** — an explicit callout of what ships at launch and what is intentionally postponed.
|
||||
- **(d) Supporting database entities** — the entities (using the final names from the refined data model) that implement the requirement.
|
||||
|
||||
---
|
||||
|
||||
## Areas
|
||||
|
||||
1. [Actors & Onboarding](01-actors-and-onboarding.md) — three actor types, phone-OTP login, the customer/patient split, and role-staged KYC.
|
||||
2. [Nurse Verification & Credentials](02-nurse-verification.md) — the platform-owned, six-step verification pipeline and the structured credential registry.
|
||||
3. [Service Catalog & Pricing](03-service-catalog-and-pricing.md) — admin-defined catalog skeleton, nurse-priced variants, and the five price units.
|
||||
4. [Search & Matching](04-search-and-matching.md) — geo/category search, the denormalized search index, and same-gender caregiver matching.
|
||||
5. [Booking & Scheduling](05-booking-and-scheduling.md) — the request→accept→pay→confirm lifecycle and multi-session engagements.
|
||||
6. [EVV / Service Delivery](06-evv-and-service-delivery.md) — Electronic Visit Verification check-in/out and payout gating on proof of service.
|
||||
7. [Cancellation & Refunds](07-cancellation-and-refunds.md) — tiered, snapshotted policies and admin-only, ticket-linked refunds.
|
||||
8. [Payments & Escrow](08-payments-and-escrow.md) — merchant-of-record card flow, the internal double-entry ledger, and webhook idempotency.
|
||||
9. [Installments / BNPL](09-installments-bnpl.md) — full-upfront, provider-financed BNPL modeled as a single inbound settlement.
|
||||
10. [Payouts to Nurses](10-payouts.md) — weekly batches gated on EVV + dispute window, clawbacks, and holiday-aware scheduling.
|
||||
11. [Reviews, Trust & Safety](11-reviews-trust-and-safety.md) — one-per-booking moderated reviews, low-rating alerting, and incident handling.
|
||||
12. [Messaging & On-Site Emergencies](12-messaging-and-emergencies.md) — ticket-only communication and the on-site emergency playbook.
|
||||
13. [Tax, Invoicing & Legal](13-tax-invoicing-and-legal.md) — nurse-as-seller / platform-as-commission-seller split, VAT, and the partner-center launch vehicle.
|
||||
14. [Notifications & Admin / Backoffice](14-notifications-and-admin.md) — in-app notifications, the admin operational spine, RBAC, and the audit trail.
|
||||
|
||||
---
|
||||
|
||||
## Appendix — MVP vs Deferred at a glance
|
||||
|
||||
| Area | MVP | Deferred |
|
||||
|---|---|---|
|
||||
| Onboarding | phone-OTP; customer/nurse/admin; patient split | customer KYC; org self-onboarding; push |
|
||||
| Verification | 6-step data-driven pipeline; `nurse_credentials`; IBAN ownership | MoH/INO API; liability-insurance step; ML fraud |
|
||||
| Catalog | admin categories/options; nurse variants & price units | holiday/surge pricing; companionship tier |
|
||||
| Search | geo + category; `nurse_search_index`; same-gender filter | map discovery; availability hard-filter |
|
||||
| Booking | request→accept→pay→confirm; `booking_sessions` multi-visit | recurring schedules; milestone-payment UX |
|
||||
| EVV | per-session GPS check-in/out; payout gating | geofencing; tele-check-ins; cameras |
|
||||
| Cancellation | tiered policy + snapshot; admin/ticket refunds; per-session | auto no-show penalty; self-service refunds |
|
||||
| Payments/Escrow | ledger escrow; `payment_webhook_events`; provider abstraction | nurse wallet; multi-PSP live; bank escrow product |
|
||||
| BNPL | full-upfront `bnpl_transactions`; provider-revert refunds | installment tracking (cut); tranched settlement; multi-provider |
|
||||
| Payouts | weekly batches; clawbacks; holiday-aware; verified IBAN | instant withdrawal; per-nurse frequency |
|
||||
| Reviews | one-per-booking; moderation; low-rating alerts | two-way reviews; tag aggregation; `incidents` |
|
||||
| Messaging | ticket-only; coordination ticket; emergency playbook | live chat; emergency-event entity |
|
||||
| Tax/Legal | `partner_centers`; minimal `invoices`; 10% VAT on commission; e-namad | full مودیان automation; nurse-side invoicing; B2B |
|
||||
| Notifications/Admin | in-app + retention; verify/refund/payout tooling; RBAC | push; analytics warehouse; ML console |
|
||||
Reference in New Issue
Block a user