Skip to main content

Documentation Model (Ownership and Rules)

This repo uses Docusaurus (docs/) as the canonical documentation system.

Ownership rules (single source of truth)​

  • Architecture: docs/internal/architecture/
  • Operations (bootstrap/deploy/env/backups/troubleshooting): docs/internal/operations/
  • Technology references (Kafka, Redis, MQTT, MCP, ...): docs/internal/technologies/
  • Service-specific docs: docs/internal/services/<layer>/<service>.md
  • Service READMEs: gateway only (what it is, quick start, minimal config pointers, links)

If you need to update the same explanation in multiple places, it is in the wrong place.

README rules​

Service README.md files must stay small and stable:

  • 1-3 line description
  • minimal quick start commands
  • minimal config entry points (file names only)
  • links to full docs in docs/

Adding a new service​

  1. Create the service folder under the correct layer (e.g. infrastructure/<service>/).
  2. Add a minimal README.md (gateway).
  3. Add full docs at docs/internal/services/<layer>/<service>.md.
  4. If a new reusable technology is introduced, add a page under docs/internal/technologies/.