Architecture Documentation

Architecture Documentation (Verbose)

Core Patterns

Architecture Decision Records

An ADR records one decision at the moment it is made, with the information that was actually available. Its value is not the decision — that is visible in the code — but the forces: what was considered, what was rejected, and what the choice costs. Six months later the code shows what; only the ADR shows why.

Rules that make ADRs work:

• One decision per record. A record covering "our data layer" is a design doc.
• Immutable once accepted. To change your mind, write a new ADR that supersedes the old one and mark the old one Superseded by ADR-00NN. Editing history destroys the reason the record exists.
• Numbered, sequential, in the repo under docs/adr/. Not in a wiki, where they drift away from the code they describe.
• Written before or with the change, never as a retrospective chore.

A real one, complete:

# ADR-0021: Move session storage from sticky sessions to Redis

Status: Accepted (2026-01-18)
Deciders: platform team
Supersedes: ADR-0004 (ALB sticky sessions)

## Context
We run 12 API pods behind an ALB with cookie-based stickiness. Two problems have
become acute:

1. Deploys drop sessions. A rolling deploy evicts pods, and the ~9% of users
   pinned to an evicted pod are logged out. Support tickets spike after every
   release (median 31 tickets per deploy over the last 8 deploys).
2. Load is uneven. Stickiness pins long-lived browser sessions, so p99 CPU
   across pods varies 3.4x. We over-provision to the hottest pod.

We hold ~180k concurrent sessions, ~1.2 KB each (~220 MB), read on essentially
every request (~4k RPS) and written on ~3% of them.

## Decision
Store sessions in a Redis cluster (3 shards, 1 replica each), keyed
`sess:<id>`, TTL 14 days refreshed on write. Disable ALB stickiness. Sessions
remain opaque server-side state; we are not moving to JWTs.

## Alternatives considered
- **JWT sessions, no server state.** Rejected: we need immediate revocation for
  the admin "force logout" feature and for support-initiated account locks. A
  revocation list would reintroduce the shared store we would be avoiding.
- **Postgres session table.** Rejected: 4k RPS of session reads against the
  primary would roughly double its read load, and session reads sit on the
  latency path of every request.
- **Keep stickiness, drain connections on deploy.** Rejected: reduces but does
  not remove the logout problem, and does nothing for load skew.

## Consequences
+ Deploys stop logging users out; rolling restarts become boring.
+ Load balancing becomes round-robin; we expect to remove 3 of 12 pods.
+ Enables "log out all devices", previously impossible.
- Redis becomes a hard dependency on the request path. If Redis is fully
  unavailable, every request is unauthenticated. We mitigate with a 50 ms
  timeout, a 30 s in-process cache of validated sessions, and a runbook; we
  accept that a total Redis outage is an auth outage.
- Adds ~1.1 ms p50 / ~4 ms p99 to every request.
- New operational surface: cluster upgrades, failover behaviour, memory
  ceilings. ~250 MB working set today against 3 GB provisioned.

## Revisit if
Session payloads exceed ~4 KB (renegotiate what we store), concurrent sessions
exceed 1M, or Redis availability over a quarter falls below 99.95%.

Note what makes it useful: numbers in Context, rejected options with the reason for rejection, and Consequences that name a real failure mode the team agreed to accept. An ADR with no minus signs is marketing.

The C4 Model

C4 gives four levels of zoom. The discipline is choosing which levels you will actually maintain — usually one and two.

Level 1 — System Context. One box for your system, surrounded by users and external systems. No internal detail. Answers "what is this and what does it talk to". This is the diagram for a new joiner, a security reviewer, or a product manager. It changes maybe twice a year.

Level 2 — Container. Deployable or runnable things: web app, API, worker, database, queue — each with its technology and its protocol to its neighbours. This is the highest-value diagram in most repos: it is what on-call needs at 3am and what a new engineer needs on day one.

graph TB
    U[Customer browser] -->|HTTPS| W[Web SPA — React, S3+CloudFront]
    W -->|JSON/HTTPS| A[API — FastAPI, ECS]
    A -->|SQL| P[(Orders DB — Postgres 15)]
    A -->|publish| Q[[Events — SNS/SQS]]
    Q --> K[Fulfilment worker — Python, ECS]
    K -->|SQL| P
    K -->|REST| S[Shipping provider — external]
    A -->|GET/SETEX| R[(Sessions — Redis)]

Level 3 — Component. Modules within a single container. Worth drawing only for a container complex enough to need it, and only if someone owns keeping it current. Otherwise it becomes the most confidently wrong artifact you own.

Level 4 — Code. Class and sequence diagrams. Do not hand-maintain these; generate on demand from the IDE or from traces.

Fighting Diagram Rot

Diagrams go stale because they restate a truth that lives somewhere else, and nothing forces the two to agree. The fix is to remove the duplication, or to make the disagreement visible.

For hand-authored diagrams, three habits keep them alive:

1. Diagrams-as-code, in the repo. Mermaid, Structurizr DSL, PlantUML — text that diffs. A .png exported from a drawing tool cannot be reviewed, so it never is.
2. Co-locate with the code they describe. A diagram in docs/ beside the service gets edited when the service changes. One on a wiki does not.
3. Put them in the definition of done. A PR that adds a container or an external dependency updates the Level 2 diagram in the same PR. Reviewers enforce this, or it does not happen.

Give every generated diagram a footer: source, generator, timestamp. A reader who can see how a diagram was produced can judge whether to trust it.

arc42 for Whole-System Documentation

ADRs are decision-shaped; sometimes you need a document describing the system as it stands — for a new team, an audit, or a handover. arc42 supplies a stable 12-section skeleton so nobody argues about structure.

Sections 1, 3, 4, 5, 8, 9 and 11 carry nearly all the value. Delete empty sections rather than leaving "TBD" — a template full of TBDs teaches readers the document is unreliable.

Quality Attributes as Scenarios

Non-functional requirements written as adjectives cannot be designed against or verified. Write them as scenarios: source, stimulus, environment, response, measure.

❌ "The API must be highly available and fast."

✅ "Under normal load (≤ 4k RPS), 99% of POST /orders complete in < 200 ms measured at the ALB. During a single-AZ failure the API continues serving with p99 < 500 ms and no elevated error rate, recovering within 90 s."

The second version tells you to test AZ failure, sets a budget you can spend during design, and tells a future reader whether a proposed change violates a commitment or merely offends taste.

Common Anti-Patterns

❌ The one big "Architecture" wiki page. Nobody owns it, everything is in it, so it is comprehensively out of date and no part of it is trusted. ✅ A small maintained set: Context, Container, ADRs, crosscutting concepts. Delete what you will not maintain.

❌ ADRs written after the fact to satisfy a process gate. They reconstruct a justification for what was already built and omit the alternatives — precisely the information worth recording. ✅ Write the ADR while the decision is live and the alternatives still feel real.

❌ Editing an accepted ADR when the decision changes. The record now claims the team knew in March what it learned in September. ✅ New ADR with Supersedes:; mark the old one superseded, leave its text alone.

❌ Consequences listing only benefits. A decision with no downside was not a decision, it was a preference. ✅ Name the cost, the new failure mode, and the ceiling you are accepting.

❌ Hand-drawing things a machine already knows — VPC layouts, table relationships, service dependencies. ✅ Generate them in CI from Terraform state, the schema, or trace data.

❌ Binary images with no source. Cannot be diffed, cannot be reviewed, cannot be updated by anyone but the original author. ✅ Diagrams-as-code committed beside the service.

❌ Level 3 and 4 diagrams while Level 1 is missing. Detail is easy and comforting; the orienting overview is the hard, valuable one. ✅ Earn detail levels by first maintaining Context and Container.

❌ Documenting the aspiration instead of the system. The doc shows the event-driven design; production is still the monolith with a cron. ✅ Document what runs, label target state as target state, and record the gap in the risks and technical debt section.

Architecture Documentation Checklist

• ADRs live in the repo, numbered, one decision each
• Every ADR names the alternatives and why they were rejected
• Every ADR's Consequences section contains at least one real cost
• Every ADR states what would cause it to be revisited
• Superseded ADRs are marked, not edited or deleted
• A C4 Level 1 Context diagram exists and is current
• A C4 Level 2 Container diagram exists, with technologies and protocols
• No hand-maintained Level 4 diagrams
• Diagrams are text (Mermaid / Structurizr / PlantUML) in version control
• Infra, schema, and dependency diagrams are generated, not drawn
• Generated diagrams carry source, generator, and timestamp
• Updating the Container diagram is part of the definition of done
• Quality attributes are written as scenarios with thresholds
• Known risks and technical debt are recorded and dated
• Docs describe what runs today; target state is labelled as such
• A new engineer can find the system's entry points from the docs alone