Features
One folder per product area. Each folder contains the same shape:
| File | Purpose |
|---|---|
README.md | What/why/who. Persona impact. Status. Open Linear issues. |
behavior.md | State machines, invariants, golden paths, edge cases, side effects, permissions. |
code-map.md | Where everything lives (API module, web components, DB tables, shared schemas, tests). |
data-model.md | Tables, columns, FKs, lifecycle, multi-org isolation, PII handling. |
qa-plan.md | Natural-language test scenarios sized for a contractor: pre-reqs, golden path, edges, negative cases, cross-persona, i18n. |
Small features may collapse some files (e.g., code-map.md and data-model.md merged). Large features may add files (e.g., forms/ may eventually grow signing-flow.md, pdf-generation.md).
When to add a new feature folder
When a coherent area of behavior earns its own home. Heuristics:
- One or more API modules dedicated to it.
- One or more dashboard routes / web components dedicated to it.
- One or more DB tables (or a tight cluster) it owns.
- A persona has a mental model of it (“the messages feature”, “forms”, “the agent”).
When in doubt, add a folder. Folder is cheap; missing docs cost more later.
When to update
Anytime you ship behavior that changes a state machine, an invariant, a code map, or a tested scenario. The doc updates land in the same PR as the code change — it’s part of “done.”
The qa-plan.md should be updated proactively when you ship a change a tester needs to validate. If the QA contractor reads a stale plan they’ll waste hours.
Cross-feature relationships
Features intentionally link to each other rather than duplicating content. If forms references uploads-r2, the forms doc links to ../uploads-r2/README.md and assumes that doc is correct. Keep your features narrow; let cross-references do the work.
What’s NOT here
- Architecture-wide concerns: how Clerk works, how the database is structured, how the request flow runs — those live in
../architecture/. - Decisions and tradeoffs — those live in
../decisions/. - Operational procedures — those live in
../runbooks/.
Status legend
The README of each feature carries a status line:
- Shipped — in production and used by real orgs.
- In review — PR open, awaiting review/merge.
- In progress — actively being built.
- Planned — in the backlog (FIT-XXX), no code yet.
- Deprecated — being removed; do not extend.