Architecture Documentation Template

A structured template for creating consistent, comprehensive architecture documentation based on arc42 and C4 Model.

Purpose

This template serves as:

• Protocol for AI collaboration: Consistent structure for discussing architecture with LLMs
• Team alignment: Shared vocabulary and documentation standards
• Knowledge preservation: Capture decisions before they become tribal knowledge

Quick Start

# Copy template to your project
cp TEMPLATE.md docs/architecture.md

# Fill in placeholders marked with {{PLACEHOLDER}}
# Remove sections not applicable to your project

Template Structure

Section	Purpose	Audience
Overview	2-3 sentence system summary	Everyone
1. Introduction & Goals	Business context, requirements, quality goals	Product, new joiners
2. Constraints	Technical, organizational, legal boundaries	Architects, leads
3. Context & Scope	System boundaries, external integrations	All technical
4. Solution Strategy	Key architectural decisions rationale	Architects, senior devs
5. Building Blocks	C2/C3 diagrams, component responsibilities	Developers
6. Runtime View	Sequence diagrams, critical flows	Developers, QA
7. Deployment View	Infrastructure, environments	DevOps, SRE
8. Crosscutting Concepts	Security, logging, error handling	All technical
9. Architecture Decisions	ADRs with context and consequences	Decision makers
10. Quality Requirements	Quality tree, concrete scenarios	QA, architects
11. Risks & Technical Debt	Known issues and mitigation plans	Leads, management
12. Glossary	Domain terms definitions	Everyone

Principles

Scalable Detail

Not every project needs all sections. Start minimal:

• MVP/Prototype: Overview + Context + ADRs
• Production Service: Add Building Blocks + Deployment + Crosscutting
• Complex System: Full template

Diagrams Over Text

graph LR
    A[Problem] --> B{Diagram<br/>possible?}
    B -->|Yes| C[Draw it]
    B -->|No| D[Write it]

Loading

Living Documentation

• Update ADRs when decisions change
• Mark deprecated sections explicitly
• Version significant changes

Files

• TEMPLATE.md — Annotated template with section descriptions
• examples/service-architecture.md — Filled example for a typical microservice

Conventions

Diagram Style

All diagrams use Mermaid. Standard node shapes:

graph TB
    user[👤 User/Actor]
    system[System Name<br/>Description]
    database[(Database)]
    external[[External System]]
    decision{Decision Point}

Loading

ADR Format

### ADR-NNN: Decision Title

- **Status**: proposed | accepted | deprecated | superseded by ADR-XXX
- **Context**: What forces are at play
- **Decision**: What we decided
- **Consequences**:
  - ➕ Positive outcome
  - ➖ Negative tradeoff

Quality Scenarios

- **Scenario**: Specific situation description
- **Metric**: Measurable success criteria
- **Status**: Implemented | Planned | At risk

Lint Compliance

Template passes markdownlint with included config:

npx markdownlint-cli2 "**/*.md"
# or copy .markdownlint.json to your project

The .markdownlint.json config disables:

• MD013 (line-length): Long tables and URLs are fine
• MD033 (no-inline-html): Mermaid sometimes needs HTML entities
• MD060 (table-column-style): Compact tables are acceptable

Key rules enforced:

• MD001: Heading levels increment by one
• MD009: No trailing spaces
• MD012: No multiple consecutive blank lines
• MD032: Lists surrounded by blank lines
• MD041: First line should be a top-level heading

Credits

Based on:

• arc42 — Pragmatic architecture documentation
• C4 Model — Visualizing software architecture
• ADR — Architecture Decision Records

License

MIT — Use freely, attribution appreciated.