Module Docs Structure Convention

Single source of truth for how every product module's docs are structured. The mirror skeleton lives at content/{en,vi}/modules/_template/ (excluded from the published site - copy from source). Every module - core, extended, or industry - follows this exact shape.

This is the product/business counterpart to the engineer-facing Developer Docs Structure. Module docs describe what the product does for users; developer package docs describe how it is built.

The Feature Spine

The whole wiki has one spine, and the unit that ties it together is the Feature.

A Feature is a Functional Area - the existing <AREA> code (STK, PO, BOM…). We do not invent a new ID system: a feature's requirements (URD-<AREA>-NNN), increments (PRD-<AREA>-NNN), and tests (TC-<AREA>-NNN) are already keyed to it. We simply name the thing those codes point at and make it first-class.

A feature lives in two homes with two jobs, joined by one Feature ID (<module>/<AREA>):

Home	Job	Audience
Delivery (feature catalog)	The list - name · status, grouped by Phase → Epic. No business detail.	PM / managers
URD (urd.md)	The description - what each feature does for users, its requirements and acceptance. This is the business documentation.	PM / PO / BA / QE

Delivery   Phase → Epic → Feature            (list + status, link → URD)      [PM view - simple]
URD        Feature = one entry: business description + requirements + acceptance
PRD        a build increment of a Feature    (1 Feature → many PRDs over time)
Test Case  written FROM a PRD                 (this is when a TC becomes meaningful)
─────────────────────────────────────────────────────────────────────────────────
Module  ⇄  Package                            (horizontal mapping: business ⇄ engineering)

One-directional spine: Phase → Epic → Feature (URD) → PRD → Test Case. One horizontal axis: Module ⇄ Package (see the mapping table in §5). Every other rule below serves this spine.

1. Goals

Goal	Why it matters
Uniformity	A reader who knows one module's docs knows them all. No discovery cost.
Audience-fit	Written for PM / PO / BA / QE / sales - business language, not implementation detail.
Spec ↔ test traceability	Every requirement (URD) maps to a test case (TC) by ID. Nothing untested, nothing untraced.
End-to-end linkage	A reader can follow one feature from roadmap → module → PRD → ADR → dev → test → runbook in a few clicks.
Visual-first	Tables + mermaid (graph, stateDiagram-v2, sequenceDiagram, erDiagram) over prose.
Status-honest	Each module/feature declares Built / In-progress / Planned so readers never mistake a roadmap item for a shipped feature.
Code-as-truth	Built features describe actual behavior verified against the codebase, not aspirations.

2. Module Tiers

Tier	Folder	Meaning	Phase
Core	modules/core/	Essential, every merchant needs it	A
Extended	modules/extended/	Growth/engagement add-ons	B
Industry	modules/industry/	Vertical-specific solution bundles	C
Use Cases	modules/use-cases/	End-to-end scenarios that compose multiple modules	-

Industry solutions are compositions of core/extended modules, not new modules. Their pages reference the modules they bundle rather than re-specifying them.

3. Folder Layout

content/{en,vi}/modules/<tier>/<module>/
├── index.md          # ⓜ Identity card: purpose, scope, capabilities, dependencies, key flows
├── urd.md            # ⓜ User Requirement Doc: personas, scope, functional requirements, acceptance
├── prds/
│   ├── index.md      # ⓜ PRD catalogue
│   └── YYYY-MM-DD-<slug>.md   # ⊕ one PRD per feature increment
└── <feature>.md ...  # ⊕ Optional per-feature deep dive (rarely needed at module level)

ⓜ mandatory · ⊕ optional

Folder-based, like developer packages. The overview lives at <module>/index.md so the URL stays /modules/<tier>/<module>. Do not keep a sibling <module>.md file.

Status-scaled mandatory set

Module status	Mandatory files

4. Document Roles

Page	Role	Answers
index.md	Identity card / overview	"What is this module, what can it do, what does it depend on?"
urd.md	User Requirement Doc	"What must it do for users, and how do we know it's correct?"
prds/*.md	Product Requirement Doc	"What are we building this increment, and why?"
<feature>.md	Feature deep-dive	"How does this one non-trivial sub-area behave end to end?"

5. Per-Page Templates

Skeleton files live at content/{en,vi}/modules/_template/ (source only). Section order is fixed.

index.md - 11 sections

Traceability block (see §6.1) · Identity (table) · Purpose & Scope (in/out) · Capabilities · Module Dependencies · Engineering Mapping (§5.1, Module ⇄ Package) · Backend Packages (link to developer docs) · Key User Flows (mermaid) · Roles & Permissions · Status & Roadmap · Related Pages

5.1 Engineering Mapping (Module ⇄ Package) - the horizontal axis

The module index carries one table that closes the gap between the business and engineering docs. One row per feature:

## Engineering Mapping

| Feature | Dev package | ADRs | Status |
|---|---|---|---|
| `STK` Stock Tracking | [@nx/inventory](/en/developer/packages/inventory/) | [ADR-0001](/en/developer/packages/inventory/decisions/0001-...) | Built |

Reciprocal: each linked package index adds a row back to the module (see §6.2).

urd.md - feature-organized

The URD is the module's feature list. Order is fixed:

Header (module id · version · date) · Purpose · Scope (in/out) · Definitions (optional) · Conceptual Model (mermaid, optional) · Feature Catalog (the at-a-glance feature table) · Features (one sub-section per feature) · Constraints & Non-Goals · Version History

• Feature Catalog - a summary table: Feature ID · Feature · Phase · Status · Priority. This is the scannable feature list; status is per-feature.
• Features - the body. One sub-section per feature, in catalog order. Each feature keeps description + requirements + acceptance together so a reader jumps to one feature and sees everything:

### `STK` - Stock Tracking  <Badge text="Built" />

**Feature ID:** `inventory/STK` · **Phase:** P1 · **PRDs:** [PRD-STK-001](./prds/...) · **Dev:** [@nx/inventory](...)

What it does for users: <1-3 lines, business language>

**Requirements**

| ID | P | Requirement |
|---|:-:|---|
| URD-STK-001 | **M** | ... |

**Acceptance**

::: details AC-STK-01: ...
| Given | When | Then |
:::

The old split - one global Functional-Requirements table plus a separate global Acceptance-Criteria section - is retired. Requirements and acceptance now live inside their feature.

prds/index.md

Single table: PRD · Date · Status · Title · Modules touched.

prds/YYYY-MM-DD-<slug>.md - PRD

Header declares its Feature ID (<module>/<AREA>) so 1 Feature → many PRDs is visible. Body: Context (problem/opportunity) · Goals & Non-Goals · Requirements (link URD IDs) · UX / Flows · Rollout & Metrics · Open Questions.

6. ID & Traceability Conventions

Artifact	ID format	Example
Module	<TIER>-NN	CORE-06, EXT-02, IND-03
Feature (= Functional Area)	<module>/<AREA>	inventory/STK, inventory/PO
URD requirement	URD-<AREA>-NNN	URD-STK-001
PRD	PRD-<AREA>-NNN	PRD-STK-001
ADR (dev)	ADR-NNNN	ADR-0005
Priority (requirements)	MoSCoW: Must · Should · Could · Won't	-

• <AREA> is a short 2-4 letter code per functional area = one feature, consistent across URD, TC, and PRD so they line up (URD-STK-001 ↔ TC-STK-001) and resolve to the same Feature ID <module>/<AREA>.
• IDs are zero-padded, sequential, and never reused - even after a requirement is dropped, its number is retired, not recycled.

6.1 Traceability block (top of every module index.md) - MANDATORY

The wiki has ONE spine: a reader must be able to follow a single feature from roadmap → module → PRD → ADR → dev → test → runbook. Every module index.md opens with this fixed block. Missing links are written - (never omitted) so gaps are visible:

> **Status:** In-progress · **Owner:** <name> · **Phase:** 1 · **Last reviewed:** YYYY-MM-DD
>
> | Chain | Link |
> |-------|------|
> | Roadmap | [Phase 1](/en/delivery/roadmap#phase-1) |
> | URD | [URD](./urd) |
> | PRD | [PRD-STK-001](./prds/2026-05-10-opening-balance) |
> | Decisions (ADR) | [ADR-0001](/en/developer/packages/inventory/decisions/0001-polymorphic-inventory-item) |
> | Plan | [.agents/plans/2026-05-10-inventory-opening-balance](#) |
> | Dev docs | [@nx/inventory](/en/developer/packages/inventory/) |
> | Runbook | [Inventory ops](/en/runbook/operations/) |
> | Delivery log | [Traceability matrix](/en/delivery/traceability-matrix) |

6.2 Reciprocal "Related Pages" footer - MANDATORY

Markdown links are one-directional, so a link MUST be added in BOTH directions. When you add module → ADR, also add ADR → module. Every page ends with ## Related Pages. Required reciprocal pairs:

If page A links to B	B must link back to A
Delivery feature row → URD feature anchor	URD feature → Delivery feature catalog
module index Engineering Mapping → developer package	package index → module
module index → roadmap phase	roadmap phase row → module
PRD → URD requirement IDs	URD → its PRDs
module / PRD → ADR	ADR "Related" → module / PRD
feature → runbook	runbook → feature / package

A lightweight CI lint can later verify every related: reference resolves and is reciprocated - the cheap stand-in for build-time link checking.

7. Authoring Style Rules

Rule	Enforcement
Audience	PM/PO/BA/QE/sales. Explain features in user terms; link to developer docs for internals - never inline schema/SQL/code.
Visual-first	Tables/mermaid for any list ≥3 items. Prose only when neither fits.
Compact prose	Max 4 lines per paragraph. Bullet > paragraph.
Frontmatter	Always title, description, outline: deep.
Status badges	Use VitePress <Badge> for phase/status (Built, In-progress, Planned, Phase A/B/C).
Cross-link	Internal links use /en/... absolute path. Link module → backend package docs, and module → use-cases that use it.
English-only in identifiers	Vietnamese only in user-facing localized strings.
No emojis	Unless part of a UI being documented.

8. Status & Roadmap Policy

Status	Meaning	In index.md
Built	Shipped and verifiable in code today	Describe actual behavior
In-progress	Partially shipped	Mark which capabilities are live vs pending
Planned	Roadmap only	Clearly labelled; no claims of working behavior

Roadmap phases (P1/P2/P3 within a module, and tier Phase A/B/C) live in the Status & Roadmap section of index.md and link to the delivery roadmap. Do not scatter phase notes through requirement tables - keep them in one place.

9. EN ↔ VI Parallel

Rule	Detail
Mirror	Every EN file has a VI counterpart at the same relative path
Line parity	EN/VI line counts within ±5%
Translation order	EN ships first → VI follows in batch
Mermaid labels	Translate node labels; keep state/event identifiers and IDs in English
Frontmatter title & description	Translated
IDs / code / identifier names	Never translated (URD-STK-001, CORE-06, entity names)
Link graph	Traceability-block and Related-footer links are identical across EN/VI - translate prose, never diverge the link graph. EN is canonical for IDs.

10. Sidebar Convention

Each module nests under its tier. A module with sub-pages shows them in fixed order:

<Module Name>            (link → index.md)
├─ URD                   (the feature list)
├─ PRDs                  (link → prds/index.md)
├─ Test Cases
└─ <feature pages…>      (only if any)

Rules:

• Module label links to index.md; sub-items follow the spine order URD → PRDs → Test Cases → Features (a test case is written from a PRD, so PRDs precede Test Cases).
• A Planned module with only an overview shows as a flat link (no nested items).
• Industry solutions are flat links (they compose, not specify).

11. Bootstrapping a New Module

# 1. Copy skeleton
cp -r content/en/modules/_template content/en/modules/<tier>/<module>
cp -r content/vi/modules/_template content/vi/modules/<tier>/<module>

# 2. Replace placeholders: <Module Name>, <TIER>-NN, <AREA>, TODO:, dates
#    Fill the §6.1 traceability block (use - for links that do not exist yet)

# 3. Register in sidebar: .vitepress/locales/en.ts and vi.ts

Step	Owner
Copy skeleton + fill index.md (incl. traceability block) + urd.md	PM/PO/BA
Add a PRD per increment	PM/PO
Sidebar registration	Author

12. Anti-patterns (do not do)

Anti-pattern	Why bad
Sibling <module>.md + <module>/ folder	Two homes for one module; use <module>/index.md
Inlining DB schema, SQL, or code in module docs	Wrong audience; link to developer package docs
Requirements with no test case	Breaks traceability; every Must needs a TC
One global Functional-Requirements table + separate global Acceptance section	Retired; organize the URD by feature (§5) so each feature is self-contained
A feature in the URD but not in the Delivery catalog (or vice-versa)	Breaks the spine; the two homes must agree
Describing Planned features as if Built	Misleads readers; always status-badge
One-directional links	Breaks the spine; add the reciprocal Related link (§6.2)
Omitting the traceability block	A reader cannot follow the feature end-to-end
Free-form per-module structure	The whole reason this convention exists

13. Related

• Development Lifecycle - the order these artifacts are produced (URD → PRD → ADR → Plan → code → test) and the one home for each
• Developer Docs Structure - engineer-facing counterpart
• Delivery - Roadmap - forward-looking phase plan
• Delivery - Feature Catalog - the per-phase feature list (one home of the Feature Spine)
• Delivery - Traceability Matrix - cross-project coverage view
• _template/ skeleton - content/{en,vi}/modules/_template/
• Modules Overview - the module catalog
• MoSCoW prioritization - https://en.wikipedia.org/wiki/MoSCoW_method