Architecture decisions and diagrams

Intermediate 8 min read

Sketch how the system fits together and record the important decisions with their reasons.

Why it matters

Six months later nobody remembers why the queue exists or why that database was chosen. A small diagram and a one-page decision record save the team from re-arguing old decisions or undoing them by accident.

Where it fits

What you will learn

Draw a context and a container diagram of a system.
Write a decision record: context, options, decision, consequences.
Keep both next to the code.

Before you start

Project documentation✓ Learned

Diagrams at two zoom levels

Context — the system as one box, the people who use it and the other systems it talks to.
Containers — the deployable parts inside: web app, API, database, queue, and how they communicate.

The C4 model names these levels (and two more detailed ones). For most projects the first two are enough.

A decision record

docs/adr/0003-use-postgresql.md

# 3. Use PostgreSQL for application data

Status: accepted · 2026-10-23

## Context
We need transactions across orders and payments, and full-text search.

## Options
PostgreSQL, MySQL, a document database.

## Decision
PostgreSQL: transactions, mature full-text search, the team knows it.

## Consequences
One more service to back up and upgrade.

Tip: Record decisions when they are made, not afterwards. A superseded decision gets a new record that links to the old one — never edit history away.

Official documentation and references

Guides

The C4 model ↗ Official · c4model.com — The official site of the C4 model for software architecture diagrams.
Architectural Decision Records ↗ ADR community (adr.github.io)

Reference

MADR — Markdown ADR template ↗ ADR community (adr.github.io)

Learn next

Git basics ›✓ Learned

Project documentation✓ Learned
The software delivery lifecycle✓ Learned

Done with this topic?

Reviewed 2026-10-23. Links go to the official documentation unless marked otherwise.