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

## 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 — three actor types, phone-OTP login, the customer/patient split, and role-staged KYC.
2. Nurse Verification & Credentials — the platform-owned, six-step verification pipeline and the structured credential registry.
3. Service Catalog & Pricing — admin-defined catalog skeleton, nurse-priced variants, and the five price units.
4. Search & Matching — geo/category search, the denormalized search index, and same-gender caregiver matching.
5. Booking & Scheduling — the request→accept→pay→confirm lifecycle and multi-session engagements.
6. EVV / Service Delivery — Electronic Visit Verification check-in/out and payout gating on proof of service.
7. Cancellation & Refunds — tiered, snapshotted policies and admin-only, ticket-linked refunds.
8. Payments & Escrow — merchant-of-record card flow, the internal double-entry ledger, and webhook idempotency.
9. Installments / BNPL — full-upfront, provider-financed BNPL modeled as a single inbound settlement.
10. Payouts to Nurses — weekly batches gated on EVV + dispute window, clawbacks, and holiday-aware scheduling.
11. Reviews, Trust & Safety — one-per-booking moderated reviews, low-rating alerting, and incident handling.
12. Messaging & On-Site Emergencies — ticket-only communication and the on-site emergency playbook.
13. Tax, Invoicing & Legal — nurse-as-seller / platform-as-commission-seller split, VAT, and the partner-center launch vehicle.
14. Notifications & Admin / Backoffice — 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

↑ Back to top