Documenting Modules

How docs get built. The site is Fumadocs (docs-next/), and every page is generated from the codebase — you edit sources in the repo, never the output.

Never edit anything under docs-next/content/docs/ — it is generated (and git-ignored). Edit the repo sources instead:

• feature guides co-locate with the module — src/api/v1/<module>/docs/*.md
• cross-cutting pages (Quickstart, Data Model, Errors, Recipes, this page) live in docs-next/content-src/
• entity specs are the co-located doc.md files

Quick start

npm run docs:install   # one-time: install the doc site's dependencies
npm run docs:serve     # regenerate + live preview (Next dev)
npm run docs           # regenerate + production build (Next)

npm run docs:gen runs the three generators (docs:api, docs:guides, docs:models); docs:serve and docs run it first, so the output is always fresh from source.

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 → Engineering › Internal Specs › 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.

Add a plain GUIDE (not a model)

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

---
publish: true
doc_type: guide          # get-started | guide | implementation | recipe | engineering
feature: crm             # (guides only) crm | messaging | automation | ai | billing | integrations
section: overview        # (guides only) a template section
sidebar_label: My Guide  # optional
---

Run npm run docs:serve → it appears under the matching section. Feature guides follow the same 10-section template (Overview · Architecture · Frontend Integration · Backend Integration · REST API · Events · Webhooks · Examples · Troubleshooting · Best Practices), so once you learn one feature you know them all.

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.

Commands