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

↑ Back to top