Documentation
1. Human documentation in Markdown
Human documentation should live in Markdown. Examples:
docs/architecture/overview.md
docs/architecture/context.md
docs/architecture/containers.md
docs/architecture/runtime.md
docs/architecture/deployment.md
docs/adr/*.md
docs/quality/quality-goals.md
docs/quality/known-risks.md
docs/glossary/glossary.md
These documents are written for humans. They should make it quickly understandable what a service does, why it exists, and how it relates to other systems.
Important: these documents may be created or updated by AI, but must be reviewed by humans and validated by CI rules.
→ For Markdown templates, see Templates and CLI.
2. C4 diagrams
AURA uses C4 as the standard model for architecture visualization.
C4 essentially consists of multiple levels:
C1: System Context
C2: Container
C3: Component
C4: Code
For AURA, C1 and C2 are the most important. C3 makes sense for more complex services. C4 should rarely be used or only generated automatically.
Minimum requirement per relevant system or service:
C1: System Context
C2: Container
optional C3: Component
A good C4 diagram answers quickly:
- Where am I?
- What belongs here?
- What does not belong here?
- Who talks to whom?
- Through which interface?
- Why is it like this?
3. Diagram sources instead of screenshots
Diagrams should not be stored only as images. The source of the diagram should live in the repository under version control.
Possible formats:
Mermaid
PlantUML
Structurizr DSL
C4-PlantUML
Examples:
docs/architecture/context.mmd
docs/architecture/container.mmd
docs/architecture/workspace.dsl
docs/architecture/container.puml
The central AURA website can display rendered diagrams. The verifiable truth, however, remains the textual diagram source in the repository.
4. Mermaid, PlantUML, or Structurizr?
For the start, Mermaid is attractive because it can be embedded directly in Markdown. For more complex landscapes with many services, a model-based approach can be better.
Possible stages:
Simple:
Markdown + Mermaid
More robust:
Markdown + Mermaid or PlantUML + fixed rules
Architecturally modeled:
Structurizr DSL / C4 model / service graph
Recommendation:
- For individual repo diagrams, Mermaid can be enough.
- For organization-wide architecture and dependency models, AURA should maintain a structured model in the long run.
- Structurizr DSL or a dedicated normalized service graph can be useful for that.
5. ADRs — Architecture Decision Records
C4 shows how the architecture looks. ADRs explain why it is the way it is.
Every repository should store relevant architectural decisions under version control:
docs/adr/0001-use-postgres.md
docs/adr/0002-introduce-event-driven-billing.md
docs/adr/0003-remove-direct-user-service-dependency.md
An ADR should at least contain:
title
status
context
decision
alternatives
consequences
links to Jira, PRs, diagrams, and code
Example ADR
# ADR-0003: Remove direct dependency to user-service
## Status
Accepted
## Context
The billing-service currently calls user-service synchronously during invoice creation.
## Decision
We will replace the synchronous call with user-profile events.
## Consequences
- billing-service becomes less coupled to user-service
- eventual consistency must be handled
- additional event processing is required
## Related
- Jira: PAY-123
- PR: #847
- Services: billing-service, user-service
→ For an ADR template, see Templates and CLI.
6. Quality and risk documentation
Beyond architectural structure and decisions, AURA needs information about quality and risks.
Examples:
docs/quality/quality-goals.md
docs/quality/known-risks.md
docs/quality/technical-debt.md
These documents should answer:
- Which quality goals are particularly important?
- Is performance critical?
- Is resilience critical?
- Are there regulatory requirements?
- Which risks are known?
- Which technical debts exist?
- Which parts are hard to maintain?
- Which parts were generated by AI and not yet sufficiently reviewed?
7. Trust status per document
Every service page and every document in AURA should have a visible trust status.
Possible statuses:
validated
outdated
missing owner
missing C4
missing ADR
documentation drift detected
AI-generated, not human-approved
last reviewed over threshold
source unavailable
Example:
documentation_status: validated
last_human_review: 2026-05-01
last_ingested: 2026-05-09
source_commit: a81f3c2
ai_generated: true
human_approved: true
drift_detected: false
This matters so that humans and AI do not blindly trust the documentation.
Continue reading
- Next page: PR Check — how AURA enforces documentation duty
- Templates and CLI — full Markdown and ADR templates
- Governance and drift — drift detection and trust assessment