orion/docs/development/module-documentation.md

Module Documentation Standard

This page defines the convention for where documentation lives in the Orion platform.

Principle: Single Source of Truth

Every module owns its documentation in app/modules/{name}/docs/. The top-level docs/modules/ directory contains symlinks to these module docs folders — never duplicate files.

Module docs/ Folder (Source of Truth)

Content specific to one module's internals lives inside the module:

app/modules/{name}/docs/
├── index.md              # Module overview (REQUIRED)
├── data-model.md         # Entity relationships, schema, field descriptions
├── api.md                # API endpoints with request/response examples
├── business-logic.md     # Algorithms, scoring, state machines, workflows
└── {topic}.md            # Additional topic files as needed

Required: index.md

Every module must have an index.md with this structure:

Section	Content
Overview table	Code, classification, dependencies, status
Features	Feature list from definition.py
Permissions	Permission table (if any)
Data Model	Brief entity overview or "No database models."
API Endpoints	Summary table or "No API endpoints."
Configuration	Config keys or "No module-specific configuration."

Optional Files

File	When to Create
data-model.md	Module has database models with non-trivial relationships
api.md	Module has API routes that need detailed request/response docs
business-logic.md	Module has complex algorithms, scoring, or state machines
Additional topic files	As needed (e.g., scoring.md, wallet-integration.md)

Top-Level docs/

Cross-cutting, architectural, or multi-module concerns:

Directory	Content
docs/architecture/	Module system design, cross-module import rules, middleware, multi-tenancy
docs/development/	How to create modules, coding standards, migration guides
docs/deployment/	Server setup, Docker, CI/CD
docs/features/	Feature guides that span multiple modules (e.g., email system touches messaging + tenancy)
docs/guides/	End-user / store-admin facing guides

Rule of Thumb

If it's about how one module works internally, it goes in the module's docs/. If it's about how modules interact or cross-cutting concerns, it goes in top-level docs/.

How Symlinks Work

The docs/modules/ directory is populated with symlinks:

# Each module gets a symlink
docs/modules/{name} → ../../app/modules/{name}/docs

# Example
docs/modules/loyalty → ../../app/modules/loyalty/docs
docs/modules/billing → ../../app/modules/billing/docs

MkDocs follows these symlinks via its default configuration. When editing module docs, always edit the source files in app/modules/{name}/docs/ — the symlinks ensure MkDocs picks them up automatically.

Adding Documentation to a Module

1. Create app/modules/{name}/docs/index.md (use existing modules as reference)
2. Add optional files (data-model.md, api.md, etc.) as needed
3. Create the symlink: ln -s ../../app/modules/{name}/docs docs/modules/{name}
4. Add the nav entry in mkdocs.yml under the appropriate classification group
5. Run mkdocs build --strict to verify