Software Architecture

The test for whether something is architecture

Ask how much it would cost to change your mind in six months. Swapping a date-formatting library is a Tuesday. Splitting a single database into one per service, or changing how services authenticate to each other, is a quarter. The second kind deserves a written decision with its alternatives; the first does not.

What an architecture document should contain

Short and decision-focused beats long and exhaustive, because a twenty-page design is accurate for about a week.

The shape

What the major pieces are and what each is responsible for. A diagram earns its place here.

How the pieces talk

Synchronous calls, queues, events - and what happens when one of them is down.

Where data lives

Which store owns what, and which piece is allowed to write it.

Alternatives considered

What else was on the table and why it lost. This is the single most useful section eighteen months later, and the one most often missing.

Known trade-offs

What this choice makes harder. Every architecture makes something harder; writing it down stops the next person treating it as a bug.

Why it drifts from reality, and what to do

The document is written before the work and the work teaches you things. A constraint appears, an approach turns out wrong, a shortcut becomes necessary, and nobody updates the prose because the code now works. The realistic fix is to keep architecture docs short and about decisions rather than about details. A two-page record of what was decided and why survives contact with reality; a full design does not.