# 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:

```bash
# 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