baya-monorepo/product/README.md

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 (or the generated index.html) — it's the hub that links everything.

Layout

Path	What's in it
overview/	What Balinyaar is, the four cross-cutting ground truths, IRR/Toman rule, Persian glossary. Read first.
business/	The 14 functional requirement areas (onboarding → admin), each with rules / Iran considerations / MVP-vs-deferred / supporting entities.
data-model/	The ~54-table schema across 13 domains + diagrams, design principles, design decisions.
payments/	Fintech deep-dive with sources: payment reality, escrow ledger, BNPL, cancellation/payout, integrations.
research/	Market, risks, verification, legal landscape, go-to-market — adversarially fact-checked, cited.
notes/	Living notes: open questions, future ideas.
wireframes/	Screen wireframes (HTML).
fa/	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:

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 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.