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,50 @@
+# `product/` — Balinyaar product & domain knowledge
+
+This folder is the **source of truth** for Balinyaar's business rules, data model, payments design,
+and market/legal research. The code is young; **these docs are the decisions**. Read the relevant
+doc before designing any schema, API, or feature — don't infer business rules from code.
+
+> **For humans:** open [`index.md`](index.md) (or the generated [`index.html`](index.html)) — it's
+> the hub that links everything.
+
+## Layout
+
+| Path | What's in it |
+| --- | --- |
+| [`overview/`](overview/platform-summary.md) | What Balinyaar is, the four cross-cutting ground truths, IRR/Toman rule, Persian glossary. **Read first.** |
+| [`business/`](business/index.md) | The 14 functional requirement areas (onboarding → admin), each with rules / Iran considerations / MVP-vs-deferred / supporting entities. |
+| [`data-model/`](data-model/index.md) | The ~54-table schema across 13 domains + [diagrams](data-model/diagrams.md), design principles, design decisions. |
+| [`payments/`](payments/index.md) | Fintech deep-dive with sources: payment reality, escrow ledger, BNPL, cancellation/payout, integrations. |
+| [`research/`](research/index.md) | Market, risks, verification, legal landscape, go-to-market — adversarially fact-checked, cited. |
+| [`notes/`](notes/open-questions.md) | Living notes: [open questions](notes/open-questions.md), [future ideas](notes/future-ideas.md). |
+| [`wireframes/`](wireframes/index.html) | Screen wireframes (HTML). |
+| [`fa/`](fa/index.html) | Farsi-language docs kept in parallel (research report + verification flow). |
+| `assets/` | Shared CSS for the generated HTML view. |
+
+## Markdown is canonical; HTML is generated
+
+Every `.md` file is the editable source. The matching `.html` files are a **generated**,
+brand-styled, cross-linked browsing view (sidebar nav, Mermaid diagrams, dark mode). **Never edit
+the `.html` by hand** — edit the Markdown and regenerate.
+
+### Regenerating the HTML view
+
+The generator is dependency-free — plain Node, no `npm install`:
+
+```bash
+cd product
+node build-docs.mjs
+```
+
+It walks every `.md` file, converts it to a styled `.html` at the same path,
+builds the sidebar from the manifest inside `build-docs.mjs`, and rewrites internal `…/foo.md` links
+to `…/foo.html`. If you add, remove, or rename a `.md` file, update the `NAV` manifest at the top of
+[`build-docs.mjs`](build-docs.mjs) so it appears in the sidebar.
+
+## Conventions
+
+- Each `.md` starts with a single `# H1` (the generator uses it as the page title).
+- Cross-doc links are **relative and use the `.md` extension** (the generator rewrites them to
+  `.html`); this keeps links working both in raw Markdown and in the rendered site.
+- Languages: **English is canonical.** Farsi versions live under `fa/` and are linked, not inlined.
+- Money is **IRR Rials**; see [the ground truths](overview/platform-summary.md).