Balinyaar — Business & Data Model

A single, comprehensive walkthrough of what Balinyaar does and how its data is shaped. It walks the platform end to end — from a family searching for a nurse to the weekly bank transfer that pays that nurse — and, at every step, names the database entities that make the step real. A final reference assembles the entire ~53-table model across 13 domains, with diagrams.

Sources: business-requirements.md (14 business domains), database-model.md (Revision 2 — 53 tables / 13 domains / 4 diagrams), payments-and-installments.md (escrow, settlement & BNPL deep-dive), and the market/legal/verification research report. Document date basis: 2026-06-20.

What Balinyaar is

Balinyaar is a trust-first home-nursing marketplace in Iran. Independent, individually-verified nurses (and, later, nursing-company employees) register, list configurable services at their own prices, and pass a multi-step verification pipeline anchored on the Ministry of Health پروانه صلاحیت حرفه‌ای (professional-competency license). Families search — filtered by city/district and same-gender caregiver preference — pick a nurse and a service variant, submit a booking request, and pay through the platform after the nurse accepts.

The platform records the money as an internal escrow ledger state (not platform-held cash), the nurse performs one or more EVV-verified visits, and the platform pays the nurse weekly, after a dispute window closes, minus a platform commission. All post-booking communication runs through an admin-readable ticket system — there is no direct nurse↔customer chat.

Cross-cutting ground truths

Four facts hold in every section below. They are the load-bearing constraints the whole design is built around.

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%, configurable

   It rose from 9% to 10% in 1403 (7% government + 3% municipal) and is treated as a configurable rate — it has moved two years running, so it is never hardcoded.

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. The nurse's payout is always gross_price_irr − balinyaar_commission_irr, never a BNPL provider's net settlement.

Data-model design principles

The schema (Revision 2) follows thirteen principles. They explain why the entity tables look the way they do, and recur in the data-model mappings.

The platform at a glance

Before the detail, here is the end-to-end path a single engagement travels. Sections 1–14 expand each stage.

1. Onboard — customer registers with phone-OTP and adds a patient + address; a nurse registers and enters verification. (§1)
2. Verify the nurse — six-step pipeline (identity, Shahkar, MoH license, INO, criminal record, IBAN ownership); only then do the nurse's variants become bookable. (§2)
3. List & price services — admin defines the catalog skeleton; each nurse creates priced variants. (§3)
4. Search & match — family filters by category, city/district, price, rating, and same-gender preference against a denormalized search index. (§4)
5. Request → accept → pay → confirm — request (no money) becomes a booking (payment captured), which owns N sessions. (§5)
6. Deliver with EVV — the nurse clocks in/out per session with GPS; payout is gated on EVV completion. (§6)
7. Handle cancellation/refund — tiered, snapshotted policy; admin-only refunds decomposed across fee legs. (§7)
8. Move the money — card or BNPL capture posts a balanced ledger entry; escrow is a ledger state. (§8–9)
9. Pay the nurse — weekly batch to the verified IBAN after the dispute window, with clawback as fallback. (§10)
10. Review, communicate, invoice — one moderated review per booking; ticket-only messaging; a minimal commission invoice with 10% VAT. (§11–14)

The four reference diagrams (domain map, booking spine, payments & payouts, financial lifecycle) plus an ER overview render this visually.

1Actors & Onboarding

Who can use the platform, how they prove who they are, and when. KYC is staged by role and risk — not collected up-front for everyone.

How onboarding works

• Three actor types: customer (the family member / payer), nurse (the independent caregiver / seller), and admin (Balinyaar back-office: support, finance, moderation, super-admin).
• Phone number is the primary login credential. Authentication is phone-OTP (one-time SMS code). 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 is frequently not the patient. A customer may register multiple patients.
• Each successful login creates a refresh-token session that can be revoked (logout, stolen-token detection).

KYC timing is role- and risk-staged

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

2Nurse Verification & Credentials

Verified trust is the entire brand. Vetting is platform-owned, non-optional, and performed at the authoritative source — never delegated to families, never marketed as a check the platform does not actually perform. A nurse is bookable only after all required steps pass.

A data-driven pipeline

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 is 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 six 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 stolen-identity / alias fraud.

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.

3. MoH پروانه صلاحیت حرفه‌ای — the single most important credential

   The MoH-mandated professional-competency license for in-home nursing. It 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 launch method is nurse-uploaded document + manual admin verification against the official record.

4. نظام پرستاری (INO) membership — cross-check

   The Iranian Nursing Organization 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 money-mule payout diversion.

3Service Catalog & Pricing

An admin-defined skeleton that each nurse fills with their own priced offerings. The model is deliberately configurable (EAV-style) so admins add new pricing dimensions without a migration.

Three admin layers, two nurse layers

• Admin defines the catalog skeleton: top-level service categories (e.g. مراقبت از سالمند / Elderly Care, مراقبت پس از جراحی / Post-Surgery Recovery, مراقبت از نوزاد / Infant Care, مدیریت بیماری مزمن / Chronic Illness Management) and configurable option groups (e.g. تعداد بیمار / patient count, نوع شیفت / shift type) each with concrete option values (e.g. ۱ نفر, ۲ نفر, شبانه‌روزی). New dimensions need no 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 price independently.

Price units that match real home nursing

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.

4Search & Matching

Families search by category, geography, price, and availability, sortable by rating — and the search must be cheap from day one. Same-gender matching is a near-hard requirement, surfaced before booking.

How search works

• Families search by service category, geography (city, 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.

5Booking & Scheduling

The lifecycle is split into two tables so each table's invariants stay clean: a request phase (no money) and a booking phase (always implies captured payment). Single-visit and long multi-session engagements must both be representable.

Request → accept → pay → confirm

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

Booking lifecycle (guarded transitions)

Allowed transitions are guarded explicitly (an allowed-transition table/CHECK) 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.

6EVV / Service Delivery

Electronic Visit Verification is the authoritative record that a visit actually happened, for how long, and where — and it is the trigger that releases escrow.

How EVV works

• 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 and 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 (§10). For a multi-session engagement, payout accrues per completed session.

7Cancellation & Refunds

Cancellation/refund rules are tiered and structured, not a single blunt "default 100%". The applicable policy is snapshotted onto the booking, and every refund decomposes across the two fee legs.

Tiered, snapshotted policy

The platform defines cancellation_policies tiers by lead time and initiating actor:

• 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 — no customer self-service. 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.

8Payments & Escrow

The family pays the gross booking price through the platform; the platform models the money as an internal double-entry ledger state, never as cash it holds. This is the most-changed domain — the ledger is the financial source of truth.

The money flow

• The family pays the gross booking price 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. A minimal double-entry ledger_entries ledger models money state: each money event posts balanced legs grouped by a transaction_group_id (Σ debit = Σ credit). 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.

Account types in the ledger

The canonical postings

Amounts are always positive; direction (debit/credit) carries the sign. Posted once, idempotently, keyed on the settling transaction.

DEBIT  escrow_held         gross_price_irr
  CREDIT platform_revenue    balinyaar_commission_irr
  CREDIT nurse_payable       nurse_payout_amount        (= gross − balinyaar_commission)

DEBIT  escrow_held         gross_price_irr
  CREDIT platform_revenue    balinyaar_commission_irr
  CREDIT nurse_payable       nurse_payout_amount
DEBIT  bnpl_fee_expense    bnpl_commission_irr
  CREDIT escrow_held         bnpl_commission_irr        (escrow reflects NET cash actually received)

DEBIT  platform_revenue    platform_fee_refunded_irr
DEBIT  nurse_payable       nurse_payout_refunded_irr
  CREDIT refund_payable      (sum)

DEBIT  nurse_clawback_receivable   amount_irr   (nurse_id set; nurse now owes the platform)
  CREDIT refund_payable               amount_irr

Clawback recovered: DEBIT nurse_payable (next batch) / CREDIT nurse_clawback_receivable. There are no installment-level postings — the customer's repayment schedule is the BNPL provider's ledger, not Balinyaar's.

The three amounts, never conflated

nurse_payout_amount = gross_price_irr − balinyaar_commission_irr, enforced by CHECK.

9Installments / BNPL

BNPL is an alternative checkout. The decisive, verified finding is full-upfront settlement: the provider pays Balinyaar the full booking amount in one lump (net of its commission) and bears 100% of customer-default risk. So a BNPL order is, in Balinyaar's books, identical to a card payment landing net-of-fee.

How BNPL is modeled

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

What bnpl_transactions captures

Provider, merchant-of-record (Balinyaar/partner center), 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.

10Payouts to Nurses

Nurses are paid in weekly batches, gated on EVV completion and a closed dispute window — because an Iranian bank transfer, once sent, is effectively irreversible. Clawbacks handle the refund-after-payout case.

How payouts work

• 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() (config-driven, default 72h post-completion). This prevents paying a nurse before a dispute can surface, shrinking clawback frequency.
• The nurse payout amount derives from gross_price_irr − balinyaar_commission_irr — never from a BNPL provider's net settlement.
• Each booking is paid at most once (the payout↔booking link is unique), preventing double-pay across batches.
• 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.

11Reviews, Trust & Safety

One review per completed booking, moderated before it goes public, with aggregates recomputed on every transition — because the buyers are vulnerable people cared for unobserved, and a single incident can destroy a fragile, trust-first brand.

How reviews & safety work

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

12Messaging & On-Site Emergencies

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 — a deliberate anti-disintermediation and patient-safety design.

How communication works

• All post-booking communication runs through tickets admin can read in full — 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 (§7).

13Tax, Invoicing & Legal

The nurse is the taxable seller of the nursing service; Balinyaar is the taxable seller only of its commission. A partner licensed center is the launch legal vehicle that makes the whole money flow legal.

The tax/invoice split

• 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. Held by the legal launch entity.

14Notifications & Admin / Backoffice

In-app notifications keep users informed; a back-office tooling spine lets admins verify nurses, refund, pay out, triage alerts, and audit everything — all scoped by RBAC.

Notifications

• 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 — the operational spine

Legal landscape (Iran)

You can legally build this in Iran — but it is a licensed healthcare activity, not a free-to-launch marketplace. Operating without a permit is what is illegal, and penalties escalate to permanent revocation and judicial referral.

The governing framework

Licensing flows through the MoH Treatment Deputy (معاونت درمان), after approval by the Article-20 medical-affairs commission (کمیسیون قانونی تشخیص امور پزشکی موضوع ماده ۲۰), under the Medical Affairs Law of 1334 (amended 1367) and the home-care bylaw approved 1378/7/17 (9 Oct 1999). Each center receives one establishment permit (پروانه تأسیس) and one technical-director license (پروانه مسئول فنی).

Two regulatory tracks — pick the nursing track

How the model must operate

• Care must be delivered in the patient's home; performing services at the center's HQ is prohibited. The licensed center is therefore a dispatch/coordination entity, not a walk-in clinic — which structurally fits a matchmaking/dispatch platform.
• After principal approval (موافقت اصولی), the founder has up to one year to ready the center for final inspection before operating.
• e-namad (نماد اعتماد الکترونیکی) is required for an Iranian site providing online services/sales and is de-facto mandatory for a monetized site, because PSP/Shaparak rules require e-namad to obtain an online payment gateway (IPG).

Verification pipeline (the operative detail)

"Is this nurse really who they say, and really licensed?" splits into two checks that are separate pipeline stages: a license check (are they a registered nurse?) and an identity + background check (are they who they claim, with no disqualifying record?). The cautionary tale is the "imposter nurse" who defeated agencies with stolen identities and forged documents — so verify at source, bind to national ID + liveness, and never trust an uploaded PDF alone.

These five stages map onto the data-driven verification_step_types rows of §2, with the structured numbers captured in nurse_credentials, the raw vendor responses in verification_steps.external_response_json, and the IBAN-ownership inquiry result on nurse_bank_accounts.

Escrow as a ledger, not held cash

Because Balinyaar cannot custody buyer funds, "escrow" must be a software construct: a double-entry ledger state over money that legally sits at a licensed provider/bank. The original model had no ledger — escrow was only inferable by joining status flags, with no single answer to "how much do we owe nurses right now?" Three critiques rated this a critical gap. The fix is one append-only table.

The rails & the custody prohibition

• Every card payment is acquired by a licensed PSP and cleared through Shaparak, which settles to bank-registered IBANs (شِبا). There is no native marketplace-escrow construct that holds buyer cash in trust.
• A پرداخت‌یار (payment facilitator) is explicitly forbidden from holding customer deposits, operating wallets, paying interest, granting credit/guarantees, or temporarily using merchant balances. Settlement goes only to merchant-registered accounts, and only Shaparak can withdraw from the special facilitator settlement account (حساب ویژه پرداخت‌یاری). This is the single load-bearing constraint of the whole design.
• تسهیم (settlement-sharing) is the compliant primitive: one incoming card payment is split across multiple registered IBANs and credited directly by Shaparak/the provider — the platform never touches the split.
• The banned move: "collect into a platform pool, hold until EVV, then redistribute" — Shaparak banned inter-facilitator/inter-merchant transfers and wallet-style holding. A bank-grade escrow product (Vandar میندو / معاملات امن) is the only true hold/release/refund mechanism, and even its EVV-trigger is unverified.

BNPL mechanics — the two hard questions

All mainstream Iranian provider-financed BNPLs (SnappPay, Digipay, Tara, Torob Pay, ZarinPlus) use full-upfront settlement: the provider pays the merchant the whole amount minus commission in one lump and bears default risk; the customer's installments are owned by the provider and decoupled from Balinyaar's escrow/payout. Lendo is the outlier (bank-financed, customer pays interest) — avoid for the MVP.

Provider comparison (the structurally important facts)

Q1 — Cancellation / refund of a BNPL booking mid-plan

Money always flows customer ↔ provider ↔ Balinyaar. Never refund the customer directly; never route a nurse→customer refund. Balinyaar initiates the reversal through the provider's API using the stored token:

• Full cancel/refund → revert (full amount).
• Partial / shortened-visit → update (new amount strictly lower) or cancel per the provider's partial semantics.

The provider then, on its own ledger and asynchronously: (1) cancels the customer's remaining unpaid installments and credits the equivalent back to their credit wallet (reusable BNPL credit), and (2) refunds any already-paid installment to the customer's bank in ~7–10 business days. The merchant's only role is to authorize/cancel; the provider owns the unwind.

Balinyaar's internal bookkeeping

1. Record a refunds row with refund_channel = 'bnpl_revert', external_revert_reference, expected_customer_refund_eta; refund_status stays processing until a reconciliation job confirms. Surface the 7–10-day window in UI/reconciliation.
2. Decompose across the two fee legs: platform_fee_refunded_irr and nurse_payout_refunded_irr.
3. Post balanced ledger entries and record the revert reference on the bnpl_transactions row (reverted_amount_irr, reverted_at).
4. If the nurse has NOT been paid: reverse the nurse_payable accrual — clean, nothing leaves Balinyaar (the common case if payout is gated on the dispute window).
5. If the nurse HAS been paid: the clawback path — a nurse_clawbacks row + a nurse_clawback_receivable leg, recovered from the next batch or written off.

Q2 — Under BNPL, who pays the nurse, and when?

Balinyaar pays the nurse, on its own normal weekly schedule, after EVV check-out and after the dispute window closes — exactly the same path as a card-funded booking. The provider never pays the nurse and is indifferent to the internal split. The nurse's payout is computed from gross_price_irr − balinyaar_commission_irr, NOT from the BNPL-net amount.

Integration notes

• SnappPay (primary) — API + IPG redirect; verified endpoint flow: OAuth token → eligible → payment token (redirect) → verify → settle → revert/cancel/update/status.
• Digipay (secondary) — unified UPG gateway; persist the gateway type per transaction (IPG=0, Wallet=11, Credit=5, BNPL=13, Credit-Card=24); deliver/refund calls must carry the matching code; gate deliver on the nurse's EVV check-out; each purchase supports either refund OR manual reverse, not both.
• Cross-cutting: webhook idempotency via payment_webhook_events keyed on external_event_id, written first; never trust the callback alone — always verify server-side and re-check amount + reference; amounts in IRR BIGINT, converting from Toman only at the boundary; a state-machine guard on BNPL status transitions.
• Recommendation: integrate SnappPay first, Digipay second, avoid Lendo.

Market & competitors

The market is real and already competitive — but incumbents are heavily concentrated in Tehran/Karaj and run mostly as direct-dispatch staffing, not trust-first marketplaces. That is the gap. The hardest problem is trust and safety, not technology.

Iranian players

What this tells you: the dominant model is direct/managed dispatch, not a true trust-first two-sided marketplace; geographic concentration is extreme (Tehran/Karaj dominate; second-tier cities thinly served — the clearest white space); pricing is opaque/negotiable (transparency is a differentiator); and "licensed" is a real, displayed trust signal. The closest international fit is the Homage model (curated marketplace + human matching), and India shows that where licensing infrastructure is weak, vetting and quality control are the product.

The risks that shape the build

The whole data model

The complete schema (Revision 2): ~53 tables across 13 domains. Each domain below lists its tables with key fields/columns and relationships (foreign keys). Net change vs the original 45: −2 cut (installment_plans replaced, installment_entries removed), +10 added, 1 replaced — the financial core is now a single ledger, BNPL is one settlement row, and the clawback / dispute-window / idempotency / license / multi-session gaps are closed.

Scope & change legend

Conventions: PII columns are (encrypted). Money is BIGINT IRR. Timestamps are DATETIME2(7) UTC. Most tables also carry created_at/updated_at (and deleted_at where soft-deleted); these are omitted from the key-field lists for brevity.

Domain 1 — Identity & Access

One identity table for every human actor avoids three near-duplicate user tables; role decides which profile sub-table is populated. Phone-as-primary matches Iranian OTP norms and is what Shahkar matches against.

Domain 2 — Geographic Data

A table (not a static list) so new cities/districts launch without a deploy; sort_order/is_active drive ordered, toggleable dropdowns. Districts are optional (a nurse can cover a whole city).

Domain 3 — Services & Pricing

Three admin layers (category → option group → option value) + two nurse layers (variant → variant option). This EAV-style configurability lets admins add a new pricing dimension without a migration; the only addition is a denormalized read model for search.

Domain 4 — Verification & Credentials

Data-driven (step types are rows) plus a structured credential registry, because the brand is "verified trust" and renewal tracking needs queryable license numbers, not opaque PDFs.

Domain 5 — Booking & Scheduling

Two distinct phases — the request phase (pre-payment intent) and the booking phase (post-payment commitment). The previous model's biggest gap — single-visit-only bookings — is fixed with booking_sessions.

Domain 6 — Payments, Ledger & Refunds

The most-changed domain. A double-entry ledger is the source of truth (replacing inference from scattered status flags), with the idempotency and clawback primitives any real-money platform needs before launch.

Domain 7 — Payouts to Nurses

Weekly aggregation matching the PAYA settlement cycle, holiday-aware, with a structural anti-double-pay guard.

Domain 8 — BNPL / Installments

Because verified research shows Iranian provider-financed BNPL settles the full amount to the merchant in one lump, a BNPL order is — in these books — a card payment that lands net-of-fee. The old installment_plans + installment_entries subsystem (which tried to track the customer's repayment and default) is deleted.

Domain 9 — Messaging (Ticket System)

All post-booking communication, admin-readable, with no direct nurse↔customer channel — it protects vulnerable patients, creates dispute evidence, and prevents disintermediation.

Domain 10 — Reviews & Patient Records

One review per completed booking with recompute-on-every-transition, plus a patient-scoped longitudinal clinical history that enables continuity of care.

Domain 11 — Notifications

Domain 12 — Audit, Config & Reference

Domain 13 — Partner Centers (launch) & Future

partner_centers is the single most launch-critical addition: the legal vehicle, plausibly the merchant-of-record, and the BNPL onboarding gate. The remaining tables are modeled-but-inactive so adding them later is a pure additive migration.

Relationship summary

The load-bearing relationships across the whole schema, at a glance.

Key design decisions (the reasoning, in one place)

1. Escrow as a ledger state, not platform cash — because an Iranian پرداخت‌یار legally cannot custody buyer funds. Everything else in the money domain follows from honestly representing "we don't hold the cash; we hold a claim/obligation tracked in the ledger over funds at a licensed provider." This is also why payouts are provider-side settlement to verified, ownership-checked IBANs.
2. A BNPL order is a net-of-fee inbound payment, full stop — the verified full-upfront settlement model means there is no customer receivable, no default risk, and no installment schedule to track. Deleting installment_entries removed an entire fragile subsystem and replaced it with one reconciliation row.
3. Three separate money amounts so the platform's two fee deductions (its own commission, and the BNPL provider's discount) are never conflated, and the nurse is paid identically regardless of payment method.
4. Double-entry over status flags — the previous model could not answer "how much do we owe nurses right now" without fragile joins, and had nowhere to record a refund-after-payout. One append-only ledger + a nurse_clawbacks receivable fixes both and makes bank/Shaparak reconciliation possible.
5. Dispute window gates payout — preferring a holding period over a clawback, because clawback against an already-paid nurse IBAN is largely unenforceable. The clawback path exists for the cases that slip through.
6. Idempotency before money — payment_webhook_events keyed on the provider event id, written first, is the cheapest insurance against the most damaging payments bug (double-confirm / double-settle on callback retries).
7. Multi-session engagements are the norm, not an edge case — booking_sessions makes long elder-care arrangements representable, lets escrow release per completed visit instead of holding a month of money, and makes mid-engagement cancellation accounting clean.
8. Partner center is launch-critical — the legal vehicle and likely merchant-of-record; without it the recommended go-to-market and the money flow are not representable.
9. Verified-trust must be queryable — nurse_credentials turns the brand promise into renewal alerts, a real badge, and audit defensibility, surviving the future arrival of an INO/MoH API.
10. Keep the configurable service EAV; cut the analytics scaffolding — the category/option model earns its complexity (admin-extensible pricing dimensions without migrations); response_rate/profile_completion_score/system_events-in-SQL do not, at launch.

Open items to confirm before building (not schema blockers)

Diagrams

Five views of the same system, rendered with Mermaid (brand-themed). The first four are reproduced from the data-model document; the fifth is an entity-relationship overview of the core spine.

1 — Domain map: how the clusters relate

flowchart LR
  PARTNER["Partner Centers (launch)
partner_centers"]
  IDENTITY["Identity & Access
users · nurse_profiles · customer_profiles
patients · customer_addresses · nurse_bank_accounts"]
  GEO["Geography
provinces · cities · districts · nurse_service_areas"]
  VERIFY["Verification
nurse_verifications · step_types · steps
documents · nurse_credentials"]
  SERVICES["Services & Pricing
service_categories · option_groups · option_values
variants · variant_options · search_index · availability"]
  BOOKING["Booking & Scheduling
booking_requests · bookings · booking_sessions
care_instructions · visit_verifications · cancellation_policies"]
  PAY["Payments & Ledger
payment_gateways · payment_transactions · webhook_events
refunds · ledger_entries · nurse_clawbacks · invoices"]
  BNPL["BNPL
bnpl_transactions"]
  PAYOUT["Payouts
payout_batches · payouts · booking_links"]
  REVIEW["Reviews & Records
reviews · review_tags · patient_care_records"]
  MSG["Messaging
tickets · participants · messages"]
  NOTIFY["Notifications
notifications · support_alerts"]
  AUDITCFG["Audit & Config
audit_logs · system_events
platform_configs · iranian_holidays"]

  PARTNER -. "sponsors / merchant-of-record" .-> VERIFY
  IDENTITY --> VERIFY
  VERIFY --> SERVICES
  SERVICES --> GEO
  IDENTITY --> BOOKING
  SERVICES --> BOOKING
  BOOKING --> PAY
  PAY --> BNPL
  PAY --> PAYOUT
  BOOKING --> REVIEW
  BOOKING --> MSG
  PAY --> NOTIFY
  PAY --> AUDITCFG
      

2 — Core booking spine (who books whom)

erDiagram
  users ||--o| nurse_profiles : "role=nurse"
  users ||--o| customer_profiles : "role=customer"
  partner_centers ||--o{ nurse_profiles : "sponsors"
  customer_profiles ||--o{ patients : "registers"
  customer_profiles ||--o{ customer_addresses : "saves"
  nurse_profiles ||--o{ nurse_service_variants : "offers"
  customer_profiles ||--o{ booking_requests : "submits"
  nurse_profiles ||--o{ booking_requests : "receives"
  patients ||--o{ booking_requests : "for patient"
  nurse_service_variants ||--o{ booking_requests : "selects variant"
  booking_requests ||--o| bookings : "converts on payment"
  bookings ||--o{ booking_sessions : "has visits"
  booking_sessions ||--o| visit_verifications : "EVV per visit"
  bookings ||--o| booking_care_instructions : "clinical (encrypted)"
  bookings ||--o| reviews : "one review"

  booking_requests {
    bigint id PK
    string status
    string required_caregiver_gender
    datetime nurse_response_deadline_at
    datetime payment_deadline_at
  }
  bookings {
    bigint id PK
    bigint gross_price_irr
    bigint balinyaar_commission_irr
    bigint nurse_payout_amount
    smallint session_count
    datetime dispute_window_ends_at
    string status
  }
  booking_sessions {
    bigint id PK
    int session_index
    date scheduled_date
    string status
    datetime payout_eligible_at
  }
      

3 — Payments, ledger & payouts

erDiagram
  bookings ||--o{ payment_transactions : "paid by (attempts)"
  payment_gateways ||--o{ payment_transactions : "via"
  payment_gateways ||--o{ payment_webhook_events : "emits"
  payment_transactions ||--o| bnpl_transactions : "if BNPL"
  payment_transactions ||--o{ refunds : "may be refunded"
  refunds ||--o| nurse_clawbacks : "if after payout"
  nurse_profiles ||--o{ nurse_clawbacks : "owes"
  bookings ||--o{ ledger_entries : "money postings"
  bookings ||--o| invoices : "billed"
  nurse_payout_batches ||--o{ nurse_payouts : "groups"
  nurse_profiles ||--o{ nurse_payouts : "receives"
  nurse_bank_accounts ||--o{ nurse_payouts : "to IBAN"
  nurse_payouts ||--o{ nurse_payout_booking_links : "covers"
  bookings ||--o| nurse_payout_booking_links : "settled in one"

  ledger_entries {
    bigint id PK
    uuid transaction_group_id
    string account_type
    string direction
    bigint amount_irr
  }
  refunds {
    bigint id PK
    bigint platform_fee_refunded_irr
    bigint nurse_payout_refunded_irr
    string refund_channel
  }
  bnpl_transactions {
    bigint id PK
    string provider_code
    bigint settled_amount_irr
    bigint bnpl_commission_irr
    string status
  }
      

4 — Financial lifecycle: escrow → payout → clawback

flowchart TD
  A["Family submits booking_request"] --> B{"Nurse responds in time?"}
  B -->|"reject / expire"| X["request closed — no money moved"]
  B -->|"accept"| C["30-min payment window"]
  C --> D{"Payment method"}
  D -->|"Card (IPG)"| E["payment_transactions = succeeded"]
  D -->|"BNPL (SnappPay)"| F["bnpl_transactions = settled
full amount minus provider commission"]
  E --> G["Ledger posting:
DR escrow_held / CR nurse_payable + platform_revenue"]
  F --> G
  G --> H["Booking confirmed (escrow held)"]
  H --> I["Nurse EVV check-in / check-out per session"]
  I --> J["Booking completed"]
  J --> K["dispute_window_ends_at = completed_at + 72h"]
  K --> L{"Window passed & no dispute?"}
  L -->|"yes"| M["payout_eligible"]
  M --> N["Weekly batch — PAYA to nurse IBAN
payout = gross − balinyaar_commission"]
  K -.->|"refund BEFORE payout"| O["Clean ledger reversal
PSP refund / bnpl_revert"]
  N --> P{"Refund AFTER payout?"}
  P -->|"yes"| Q["nurse_clawbacks receivable
netted next batch or written off"]
  P -->|"no"| Z["Settled and reconciled"]
      

5 — Entity-relationship overview (cross-domain)

A wider ER view tying the identity, verification, services, booking, payment, payout, BNPL, messaging, review, and partner clusters together — the relationships a reader needs to navigate the whole model.

erDiagram
  users ||--o| nurse_profiles : "1:1"
  users ||--o| customer_profiles : "1:1"
  users ||--o{ user_sessions : "sessions"
  users }o--o{ roles : "via user_roles"
  partner_centers ||--o{ nurse_profiles : "sponsors"
  partner_centers ||--o{ bookings : "covers"
  partner_centers ||--o{ invoices : "issues"

  nurse_profiles ||--|| nurse_verifications : "header"
  nurse_verifications ||--o{ verification_steps : "steps"
  verification_steps ||--o{ verification_documents : "evidence"
  nurse_profiles ||--o{ nurse_credentials : "licenses"
  nurse_profiles ||--o{ nurse_bank_accounts : "IBANs"
  nurse_profiles ||--o{ nurse_service_variants : "offers"
  nurse_profiles ||--o{ nurse_service_areas : "covers"
  nurse_service_variants ||--o{ nurse_service_variant_options : "options"
  nurse_service_variants ||--o{ nurse_search_index : "projected"

  customer_profiles ||--o{ patients : "registers"
  customer_profiles ||--o{ customer_addresses : "saves"
  patients ||--o{ patient_care_records : "history"

  customer_profiles ||--o{ booking_requests : "submits"
  nurse_service_variants ||--o{ booking_requests : "variant"
  booking_requests ||--o| bookings : "converts"
  bookings ||--o{ booking_sessions : "visits"
  booking_sessions ||--o| visit_verifications : "EVV"
  bookings ||--o| booking_care_instructions : "clinical"
  bookings ||--o| reviews : "one review"
  reviews ||--o{ review_tag_links : "tags"
  bookings ||--o| invoices : "billed"

  bookings ||--o{ payment_transactions : "attempts"
  payment_gateways ||--o{ payment_transactions : "via"
  payment_gateways ||--o{ payment_webhook_events : "idempotency"
  payment_transactions ||--o| bnpl_transactions : "if BNPL"
  payment_transactions ||--o{ refunds : "partials"
  refunds ||--o| nurse_clawbacks : "after payout"
  bookings ||--o{ ledger_entries : "postings"

  nurse_payout_batches ||--o{ nurse_payouts : "groups"
  nurse_profiles ||--o{ nurse_payouts : "receives"
  nurse_bank_accounts ||--o{ nurse_payouts : "to IBAN"
  nurse_payouts ||--o{ nurse_payout_booking_links : "covers"
  bookings ||--o| nurse_payout_booking_links : "one payout"

  bookings ||--o{ tickets : "coordination"
  tickets ||--o{ ticket_participants : "who"
  tickets ||--o{ ticket_messages : "thread"
  refunds ||--o{ tickets : "anchored"