clean and refine product docs structure

2026-06-24 01:32:46 +03:30
parent be07c703ec
commit 1df3cd9f64
113 changed files with 6078 additions and 4973 deletions
@@ -0,0 +1,75 @@
+# 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.