# Balinyaar — Product Documentation

**Balinyaar** is a trust-first home-nursing marketplace in Iran: independent, individually-verified
nurses list configurable services; families search, book, pay, and review; the platform holds funds
in an escrow-style ledger and pays nurses out weekly after a confirmed check-out.

This is the product/domain knowledge base — the **source of truth** for business rules, the data
model, payments, and the market/legal research. Start with the
**[Platform Summary & cross-cutting ground truths](overview/platform-summary.md)**, then dive into
the area you need.

> The Markdown files here are canonical. The matching `.html` files are a generated, cross-linked
> browsing view — see [README](README.md#regenerating-the-html-view) to regenerate.

---

## Sections

### 🧭 [Overview](overview/platform-summary.md)
What Balinyaar is, the four cross-cutting ground truths (no cash custody, 10% VAT, full-upfront
BNPL, weekly nurse payout), the IRR/Toman rule, and a glossary of the Persian terms.

### 📋 [Business Requirements](business/index.md)
The 14 functional areas — onboarding, verification, catalog & pricing, search, booking, EVV,
cancellation, payments/escrow, BNPL, payouts, reviews, messaging, tax/legal, admin — each with
business rules, Iran-specific considerations, MVP-vs-deferred scope, and supporting entities.

### 🗄️ [Database Model](data-model/index.md)
The refined ~54-table SQL Server schema across 13 domains, plus
[ER & flow diagrams](data-model/diagrams.md), design principles, the two resolved BNPL questions,
and the key design decisions.

### 💳 [Payments, Escrow & BNPL](payments/index.md)
The fintech deep-dive (with sources): the Iranian payment reality, escrow as a double-entry ledger,
the BNPL landscape & full-upfront finding, cancellation/refund + who-pays-the-nurse, and SnappPay /
Digipay integration notes.

### 🔬 [Research & Strategy](research/index.md)
Market & competitors, problems & risks, nurse identity/credential verification, the Iranian legal
landscape, and go-to-market recommendations — adversarially fact-checked, with citations.

### 🗒️ [Notes](notes/open-questions.md)
Living product notes: [open questions](notes/open-questions.md) and
[future ideas / backlog](notes/future-ideas.md).

### 🖼️ [Wireframes](wireframes/index.html)
The Balinyaar screen wireframes (login/onboarding, nurse verification, booking, BNPL, patient
record).

### 🇮🇷 [Farsi documents](fa/index.html)
Persian-language versions kept in parallel: the platform research report and the nurse
verification-flow implementation guide.

---

## How the docs relate

```mermaid
flowchart LR
  OV["🧭 Overview<br/>ground truths + glossary"]
  RES["🔬 Research<br/>why: market, legal, risk"]
  BIZ["📋 Business Requirements<br/>what the platform must do"]
  DM["🗄️ Database Model<br/>how it's stored"]
  PAY["💳 Payments deep-dive<br/>the money mechanics"]

  OV --> BIZ
  RES --> BIZ
  BIZ --> DM
  BIZ <--> PAY
  PAY <--> DM
```

- **Research** explains *why* (market gap, legal track, trust risks). **Business Requirements**
  states *what* must ship. **Database Model** is *how* it's stored. **Payments** is the *money detail*
  shared by the other three. They cross-link rather than repeat each other.