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