Documenting modules

How to create and update documentation in this site. Three tabs, all generated from the codebase:

Tab	Source you control	Built by
Guides	any .md in the repo with publish: true frontmatter	scripts/sync-guides.ts
Models	a doc.md next to each entity (src/.../doc.md)	scripts/sync-models.ts
API Explorer	your controllers (automatic)	scripts/export-openapi.ts → Scalar at /explorer/

Never edit anything under docs-site/docs/ — it is generated. Edit the repo sources (doc.md, guide .md, controllers).

Quick start

npm run docs:install   # one-time: install the doc site's dependencies
npm run docs:serve     # regenerate + live preview at http://localhost:3000
npm run docs           # build a static site into docs-site/build/

Document a NEW module/model

1. Scaffold the doc (creates doc.md next to the entity, pre-filled from it):

   npm run docs:models -- Deal      # use the entity CLASS name
   npm run docs:models -- --list    # if unsure of the name

   → creates src/api/v1/deal/doc.md
2. Edit src/api/v1/<module>/doc.md — fill the TODO prose sections.
3. Preview: npm run docs:serve → Models tab → Deal. It appears automatically because its module now has a doc.md.

The model doc template

# Deal
## PRD   Business problem · User stories · Success criteria      (you write)
## FRD   per-field bullets                                       (auto)
## HLD   Frontend · API · Database changes                       (you write)
## LLD   Tables (auto) · Services · Validators · API endpoints   (mixed)
## API   endpoint list, deep-linked into the API Explorer        (auto)
## ERD   this table + related tables                             (auto)

Auto sections are wrapped in AUTO:<id> marker comments so --force can refresh only those. Everything outside the markers is yours.

Update an existing module

• Editing prose (PRD/HLD/Services/Validators): edit the module's doc.md, re-run npm run docs:serve. That file is the source of truth (tracked in git).
• Entity changed (columns/relations added or removed): refresh the auto sections without losing your prose:

  npm run docs:models -- Deal --force

  --force rewrites only the auto blocks (Fields/Tables/API/ERD); your PRD/HLD/Services/Validators prose is preserved.

Add a plain GUIDE (not a model)

Add frontmatter to the top of any .md in the repo:

---
publish: true
sidebar_label: My Guide
---

Run npm run docs:serve → it appears in the Guides tab. Remove it to hide.

Commands

Command	Does
npm run docs:serve	Regenerate everything + live preview
npm run docs	Build static site → docs-site/build/
npm run docs:models -- <Name>	Scaffold a module's doc.md (skips if it exists)
npm run docs:models -- <Name> --force	Refresh the auto blocks (keeps prose)
npm run docs:models -- --list	List all entity names
npm run docs:api	Regenerate the OpenAPI spec
npm run docs:guides	Re-sync the published guides