clean and refine product docs structure
This commit is contained in:
hamid
@@ -0,0 +1,58 @@
|
||||
# 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 |
|
||||
Reference in New Issue
Block a user