Keep one architecture overview with a context view and a container view

How to do it

A new developer, an auditor and a coding agent all ask the same first question, which is what talks to what. Draw two views at most, a context view and a container view, as the C4 model names them. Code-level detail goes stale too fast to draw. Label every arrow with what it carries and how, such as "orders, HTTPS". Keep the diagrams as text, such as Structurizr DSL, Mermaid or PlantUML, as Draw diagrams as code says. They then change in the same pull request as the code. Update the views in the change that adds or removes a container or an outside system. List each part with its owner, its language and where it runs. Link the decision records behind the shape, as Link each decision record from the code it governs says. Link the page from the README section in Give the README a fixed set of sections.

Examples

JavaScript example

// Every deployable part is on the architecture page, and nothing extra
import { readFileSync, readdirSync } from 'node:fs';
const services = readdirSync('services', { withFileTypes: true }).filter(entry => entry.isDirectory()).map(entry => entry.name);
const overview = readFileSync('docs/architecture.md', 'utf8');
const missing = services.filter(name => !overview.includes(`\`${name}\``));
missing.forEach(name => console.log(`FAIL ${name} is not on the architecture page`));
process.exit(missing.length ? 1 : 0);

Python example

# The same check in Python
import pathlib, sys
services = [p.name for p in pathlib.Path("services").iterdir() if p.is_dir()]
overview = pathlib.Path("docs/architecture.md").read_text()
missing = [name for name in services if f"`{name}`" not in overview]
for name in missing:
    print(f"FAIL {name} is not on the architecture page")
sys.exit(1 if missing else 0)

Mermaid example

C4Container
  title Example Shop containers
  Person(shopper, "Shopper")
  System_Ext(psp, "Payment provider")
  Container(web, "Web app", "Node.js", "Pages and checkout")
  ContainerDb(db, "Database", "PostgreSQL", "Orders and stock")
  Rel(shopper, web, "Browses and buys", "HTTPS")
  Rel(web, db, "Reads and writes orders", "SQL")
  Rel(web, psp, "Creates payments", "HTTPS")

How to check

A script reads the list of deployable services, such as the services in the Compose file or the folders under services/. Each name appears in docs/architecture.md, and the page names no service that no longer exists. The same script compares the containers in the diagram with the services in the deploy files, such as Compose or Kubernetes manifests.

Sources

• ISO/IEC/IEEE 42010:2022 Architecture description

Related rules

• DOC-46 Draw diagrams as code in Documentation
• DOC-10 Number decision records and link each one from the code it governs in Documentation
• DOC-6 Give the README a fixed set of sections in Documentation