baya-monorepo/product/business-requirements.md

Balinyaar — 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

---

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.

Cross-cutting ground truths (true in every section):

1. Balinyaar cannot legally custody customer cash. Under Iranian rules a پرداخت‌یار (payment facilitator) is forbidden from holding deposits, running wallets, or moving money between merchants. Money always flows card → licensed PSP → Shaparak settlement → bank-registered IBANs. "Escrow" is therefore an internal ledger state over funds custodied at a licensed provider/partner bank — never a Balinyaar-owned cash balance. (ledger_entries)
2. VAT is 10%, not 9% — it rose from 9% to 10% in 1403 (7% government + 3% municipal) and is treated as a configurable rate.
3. BNPL is full-upfront. A BNPL provider settles one full-amount lump (net of its commission) to the merchant-of-record, bears 100% of customer-default risk, and owns the customer's installment repayment entirely. A BNPL order behaves in Balinyaar's books exactly like a card payment landing net-of-fee. (bnpl_transactions)
4. The nurse is paid by Balinyaar, weekly, on Balinyaar's own schedule — gated on EVV completion and a closed dispute window — regardless of how the family paid.

---

1. Actors & Onboarding

(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.

---

2. Nurse Verification & Credentials

(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.

---

3. Service Catalog & Pricing

(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.

---

4. Search & Matching

(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).

---

5. Booking & Scheduling

(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.

---

6. EVV / Service Delivery

(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).

---

7. Cancellation & Refunds

(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.

---

8. Payments & Escrow

(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).

---

9. Installments / BNPL

(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 payments-and-installments.md — cross-reference it 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 payments-and-installments.md.

---

10. Payouts to Nurses

(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.

---

11. Reviews, Trust & Safety

(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.

---

12. Messaging & On-Site Emergencies

(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.

---

13. Tax, Invoicing & Legal

(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).

---

14. Notifications & Admin / Backoffice

(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).

---

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