Solution architecture

Architecture is the set of decisions that are expensive to change later. The job is to work out which decisions those are, make them deliberately, and leave a record that answers "why is it like this?" in two years.

1. Write the constraints before the options

An option that violates a constraint is not an option, and listing it wastes everyone's afternoon. So the constraint list comes first:

The team constraint is the one most often left out and most often decisive. An architecture nobody on the team can debug at 2am is the wrong architecture, whatever its other properties.

2. Rank by reversibility, not elegance

Sort every decision into one of two piles, and spend your attention accordingly:

• One-way doors. Data model, the storage engine, the public API shape, tenancy model, the auth model, anything users will build on. These get the scrutiny, the prototype, and the written decision.
• Two-way doors. Which library, how a module is split, the queue implementation, most naming. Decide quickly, move on, change it later when you know more.

Teams reliably spend their deliberation on two-way doors, because those come with strong opinions, and rush the one-way doors, because those feel abstract. Watch for it.

3. At least three options, and one of them extends what exists

• Extend what is already here. Always evaluate this properly. It is frequently the right answer and is skipped because it is unexciting. If you reject it, say why in one sentence — that sentence is the justification for everything the new thing will cost.
• The straightforward new build. The obvious shape, done plainly.
• The one that is right if a constraint changes. Usually the one that scales further or costs more. Naming it makes the trade explicit rather than implicit.

For each: what it costs to build, what it costs to run, what it costs to operate, what it makes easy later, and what it makes hard later. That last column is the one that predicts regret.

4. Boring by default; spend novelty once

Every unfamiliar technology has a cost that does not show up in the comparison table: nobody knows its failure modes, its operational surprises, or how to debug it under pressure. That cost is real and it is paid at the worst moment.

Allow yourself one interesting choice per project, in the place where it buys the most. Everything else is the thing the team already runs.

A good test: for each component, who on the team could fix it if it broke on a Friday evening? If the answer is "the person who chose it", that is the risk, stated.

5. Design the failure, not just the success

For each option, walk the failure paths before deciding:

• What happens when the dependency is down? Slow is worse than down — plan for slow.
• What happens on a partial write, a retry, a duplicate delivery?
• What is the blast radius of one bad record, one bad deploy, one bad tenant?
• How does it behave at zero, at one, and at a hundred times the expected load?
• How do you know it is broken — what emits the signal, and who sees it?
• How do you recover, and has anyone tried?

An architecture diagram with no failure annotations is a sketch of the happy path.

6. Cost and operations are design, not an afterthought

• Idle cost. Many systems spend most of their life idle. What does this cost doing nothing? Pay-per-use and scale-to-zero change the shape of what is affordable, at the price of a cold start you must then design around.
• Cost that scales with the wrong thing. Per-request, per-GB-scanned and per-connection pricing all punish a specific mistake. Know which one you are exposed to.
• Who gets paged, for what, and what they can do about it at that hour.
• What the deploy looks like, including the rollback.
• What you will need to debug it — logging, tracing and a way to answer "what happened to this one record?" without a database console.

7. Draw the boundaries, and be honest about them

The valuable part of a diagram is the lines, not the boxes. For each boundary:

• What crosses it, in what format, and who owns that format?
• Is it synchronous or asynchronous, and what happens when the far side is slow?
• Is it a real boundary, or a folder pretending to be one? A "service" that shares a database with another service is one service with extra latency.

Prefer few, well-defined boundaries over many convenient ones. Every boundary is a place where versions drift, and drift is expensive — see contract-change.

8. Write the ADR

One file per significant decision, in the repo, numbered and dated. Short.

# ADR-014: Store submissions as immutable versions rather than editing in place

**Status:** Accepted · 2026-09-21 · Supersedes ADR-009

**Context**
Submissions reference a template that authors keep editing. Completed records
no longer match what the user saw. ~2% of records affected in the last quarter.

**Decision**
Publishing snapshots the template into a numbered immutable version. Records
store the version id at creation and read through it for their lifetime.

**Consequences**
+ Historical records stay readable; scores are reproducible.
+ The version diff becomes the changelog for free.
- Every typo fix creates a version; the version table grows.
- Readers must resolve through the record's version, including exports.

**Rejected**
- Edit in place with an audit log — does not make old records renderable.
- Copy the whole template onto each record — 40x storage, no diffing.

**What would reverse this**
If templates stop being editable after first use, versioning is unnecessary.

The decision is stated as a claim, not a topic. "ADR-014: Versioning" tells a future reader nothing; the sentence above tells them everything.

Rejected options and what would reverse it are the two sections people skip and the two that stop the same debate being re-run every year.

9. Say what you are not building

The architecture's non-goals are as load-bearing as the requirements' non-goals: no multi-region, no offline, no real-time, single tenant per database, English only. Each of these is a decision someone will otherwise assume went the other way.

Checklist

• Constraints written before options, including team and operational
• Decisions sorted into one-way and two-way doors; scrutiny spent on one-way
• Extending what exists evaluated properly and rejected in writing if rejected
• Each option carries what it makes hard later, not only what it makes easy
• At most one unfamiliar technology, and someone other than its champion can debug it
• Failure paths walked: dependency slow, partial write, retry, blast radius, recovery
• Idle cost, paging, deploy and rollback considered part of the design
• Boundaries real, few, and owned
• ADR written with the decision as a claim, plus rejected options and what would reverse it
• Architectural non-goals stated