# Business Requirements

> **Purpose.** This document specifies the business requirements for **Balinyaar**, an MVP home-nursing marketplace in Iran where independent, individually-verified nurses list configurable services, families search and request a nurse, the nurse accepts, the family pays *through* the platform, the platform holds the money as an internal escrow ledger state, the nurse performs one or more visits with Electronic Visit Verification (EVV) check-in/out, and the platform pays the nurse weekly minus a commission. It is grounded in the verified payment/settlement research, the adversarial fact-checks, the database-model critiques, and the market/legal/verification research. It is written to be an MVP that is decisive but **not naive** about Iranian payment law, tax, and the realities of caring for vulnerable people at home. All monetary values are in **IRR (Rials)**; Toman is a display concern only and is converted to/from Rials solely at an external provider's API boundary.

**Date:** 2026-06-20

These sections assume the four [cross-cutting ground truths](../overview/platform-summary.md).

---

## How to read this document

Each section covers one business area and states, in order:

- **(a) Business requirements** — what the platform must do.
- **(b) Iran-specific considerations** — the local legal, fiscal, cultural, and infrastructural realities that shape the requirement.
- **(c) MVP vs DEFERRED** — an explicit callout of what ships at launch and what is intentionally postponed.
- **(d) Supporting database entities** — the entities (using the final names from the refined data model) that implement the requirement.

---

## Areas

1. [Actors & Onboarding](01-actors-and-onboarding.md) — three actor types, phone-OTP login, the customer/patient split, and role-staged KYC.
2. [Nurse Verification & Credentials](02-nurse-verification.md) — the platform-owned, six-step verification pipeline and the structured credential registry.
3. [Service Catalog & Pricing](03-service-catalog-and-pricing.md) — admin-defined catalog skeleton, nurse-priced variants, and the five price units.
4. [Search & Matching](04-search-and-matching.md) — geo/category search, the denormalized search index, and same-gender caregiver matching.
5. [Booking & Scheduling](05-booking-and-scheduling.md) — the request→accept→pay→confirm lifecycle and multi-session engagements.
6. [EVV / Service Delivery](06-evv-and-service-delivery.md) — Electronic Visit Verification check-in/out and payout gating on proof of service.
7. [Cancellation & Refunds](07-cancellation-and-refunds.md) — tiered, snapshotted policies and admin-only, ticket-linked refunds.
8. [Payments & Escrow](08-payments-and-escrow.md) — merchant-of-record card flow, the internal double-entry ledger, and webhook idempotency.
9. [Installments / BNPL](09-installments-bnpl.md) — full-upfront, provider-financed BNPL modeled as a single inbound settlement.
10. [Payouts to Nurses](10-payouts.md) — weekly batches gated on EVV + dispute window, clawbacks, and holiday-aware scheduling.
11. [Reviews, Trust & Safety](11-reviews-trust-and-safety.md) — one-per-booking moderated reviews, low-rating alerting, and incident handling.
12. [Messaging & On-Site Emergencies](12-messaging-and-emergencies.md) — ticket-only communication and the on-site emergency playbook.
13. [Tax, Invoicing & Legal](13-tax-invoicing-and-legal.md) — nurse-as-seller / platform-as-commission-seller split, VAT, and the partner-center launch vehicle.
14. [Notifications & Admin / Backoffice](14-notifications-and-admin.md) — in-app notifications, the admin operational spine, RBAC, and the audit trail.

---

## Appendix — MVP vs Deferred at a glance

| Area | MVP | Deferred |
|---|---|---|
| Onboarding | phone-OTP; customer/nurse/admin; patient split | customer KYC; org self-onboarding; push |
| Verification | 6-step data-driven pipeline; `nurse_credentials`; IBAN ownership | MoH/INO API; liability-insurance step; ML fraud |
| Catalog | admin categories/options; nurse variants & price units | holiday/surge pricing; companionship tier |
| Search | geo + category; `nurse_search_index`; same-gender filter | map discovery; availability hard-filter |
| Booking | request→accept→pay→confirm; `booking_sessions` multi-visit | recurring schedules; milestone-payment UX |
| EVV | per-session GPS check-in/out; payout gating | geofencing; tele-check-ins; cameras |
| Cancellation | tiered policy + snapshot; admin/ticket refunds; per-session | auto no-show penalty; self-service refunds |
| Payments/Escrow | ledger escrow; `payment_webhook_events`; provider abstraction | nurse wallet; multi-PSP live; bank escrow product |
| BNPL | full-upfront `bnpl_transactions`; provider-revert refunds | installment tracking (cut); tranched settlement; multi-provider |
| Payouts | weekly batches; clawbacks; holiday-aware; verified IBAN | instant withdrawal; per-nurse frequency |
| Reviews | one-per-booking; moderation; low-rating alerts | two-way reviews; tag aggregation; `incidents` |
| Messaging | ticket-only; coordination ticket; emergency playbook | live chat; emergency-event entity |
| Tax/Legal | `partner_centers`; minimal `invoices`; 10% VAT on commission; e-namad | full مودیان automation; nurse-side invoicing; B2B |
| Notifications/Admin | in-app + retention; verify/refund/payout tooling; RBAC | push; analytics warehouse; ML console |