Documentation development guide

Where to edit

Product and technical text: docs/wiki/*.md
Architecture elements, relationships and documentation URLs: docs/structurizr/model.dsl
C4 views: docs/structurizr/views.dsl
Documentation website: docs/starlight/

Do not manually modify generated Starlight content under src/content/docs/ or generated diagram assets under public/architecture-viewer/ and public/diagrams/.

Local preview

cd docs/starlight
npm install
npm run dev

The local viewer reflects the last exported architecture assets. Merge DSL changes to main to regenerate viewer and SVGs automatically. Cloudflare Pages builds the Starlight site after GitHub pushes.

How to maintain the specification set

Start from the documentation index. Keep the detailed contract in its specialised page rather than copying numerical requirements or algorithms into multiple summaries. Mark unresolved work clearly instead of treating proposed choices as shipped functionality.

For diagrams, double-click systems/containers to drill down, and follow element links to the relevant local reference page. The exporter is Structurizr’s static-site exporter.

Validation

The Validate Starlight site GitHub workflow builds the complete static website. The Generate Structurizr SVG diagrams workflow validates architecture DSL and refreshes both interactive and SVG assets. A documentation link check prevents links to external planning workspaces from appearing in the published site.