Deciding & Communicating
Making architectural decisions explicit, recording why, and getting them understood by the people who have to live with them.
Which Decisions Are Architectural
| Usually architectural | Usually not |
|---|---|
| Service and module boundaries | Which HTTP client library |
| Data ownership and the source of truth | Folder layout |
| Synchronous versus event-driven integration | Formatter settings |
| Database engine and consistency model | Test framework |
| Authentication and tenancy model | Logging format |
The useful instinct is to spend decision effort in proportion to reversal cost. A two-way door — easy to undo — should be decided quickly by whoever is closest to it. A one-way door deserves options, trade-offs and a written record.
Architecture Decision Records
An ADR is a short document capturing one decision: the context, the options, the choice and its consequences. They live in the repository next to the code, numbered and immutable — superseded rather than edited.
# ADR 014 — Store money as integer minor units
## Status
Accepted — 2026-03-11. Supersedes ADR 006.
## Context
Totals disagreed between the ledger and invoices by a few pence. Floating
point rounding in the pricing service is the cause.
## Decision
All monetary values are stored and transported as integer minor units with
an explicit ISO currency code. No float or double may hold money.
## Consequences
+ Arithmetic is exact; ledger and invoices reconcile.
+ One Money value object enforces currency matching.
− A migration is required for three existing tables.
− Every external API integration needs a conversion at the boundary.| Why ADRs work | Detail |
|---|---|
| They record the why | Code shows what was decided, never the alternatives rejected |
| They stop re-litigation | The same debate does not reopen every six months |
| They onboard people | A new joiner reads how the system came to be this way |
| They are cheap | One page, written once, reviewed in a pull request |
| They are honest | Consequences include the costs, not only the benefits |
Running The Decision
| Step | Detail |
|---|---|
| Frame the problem | Written down, agreed, before anyone names a technology |
| State the constraints | Budget, deadline, skills, compliance, existing estate |
| Generate real options | At least two, each genuinely viable — a straw man is not an option |
| Evaluate against criteria | Named in advance, so the criteria are not chosen to fit the answer |
| Decide and record | Who decided, when, and on what basis |
| Set a review trigger | What would make us revisit this |
Say who decides. Consensus is not required and often not achievable; what is required is that the decision-maker is named, the objections are recorded, and the people who disagreed know they were heard.
Communicating It
An architecture that only exists in one person's head is a risk, not a design. Different audiences need different things from the same decision.
| Audience | Wants |
|---|---|
| Executives | Cost, risk and timeline — in one slide, no diagrams |
| Product | What becomes possible, what becomes slower |
| Engineers | Boundaries, contracts, and what they must not do |
| Operations | Failure modes, scaling behaviour, what pages at 3am |
| Future maintainers | The ADR, and a diagram that still matches reality |
Interview Questions
Which decisions deserve an ADR?
The ones expensive to reverse — service boundaries, data ownership, integration style, consistency model. Two-way doors should be decided quickly and not documented at length.
What goes in an ADR?
Context, the options considered, the decision, and the consequences including the costs. Status makes it immutable — superseded by a new record rather than edited.
Why is the consequences section the important one?
Without the costs an ADR reads as an endorsement. The next person cannot tell whether a trade-off was weighed or simply missed.
How do you avoid a decision document that is really a justification?
Name the evaluation criteria before generating options, and include at least two genuinely viable ones. Criteria written after the preferred choice fool nobody.
Does an architectural decision need consensus?
No, but it needs a named decision-maker and a record of the objections. People accept decisions they disagreed with far more readily when they know they were heard.
How should the same decision be communicated to different audiences?
Executives want cost, risk and timeline; engineers want boundaries and contracts; operations want failure modes. Same decision, different extraction — starting from a one-sentence summary.