Architectural decisions and trade-offs: reversibility and timing

Everything is a trade-off

Every significant architectural choice buys something by giving something else up. Splitting a system into independently deployable services buys team autonomy and independent scaling, and pays in network latency, operational complexity and harder data consistency. Caching buys speed and pays in staleness and invalidation logic. A managed cloud database buys freedom from patching and backups and pays in cost and dependence on one provider. Mark Richards and Neal Ford put this at the head of Fundamentals of Software Architecture (2020; second edition 2025) as their first law: Everything in software architecture is a trade-off. A corollary they draw is that if you think you have found something that is not a trade-off, you have probably not yet identified the trade-off.

Their second law is that why is more important than how. Anyone can look at a running system and see how it is built: three services, a message broker, a document database. What cannot be recovered from the code is why: which alternatives were considered, which concerns won, which risks were accepted. Without the why, later engineers either preserve choices that no longer make sense or undo choices whose reasons still apply. The second edition adds a third law: most architectural decisions are not binary but sit on a spectrum between extremes. You rarely choose between "monolith" and "microservices"; you choose how many deployable units, split along which lines, sharing what.

Thinking in trade-offs is the habit that most clearly separates architectural thinking from enthusiasm. When someone proposes a technology, the useful questions are not "is it good?" but "what does it cost, what does it make harder, and are those costs acceptable given our concerns?" The previous section showed where those concerns come from.

The anatomy of a decision

An architectural decision is more than its outcome. A decision that can be explained, reviewed and revisited has six parts, and naming them is the first step to making decisions well.

Context: the forces at play. The problem being solved, the quality attribute requirements that bear on it, the constraints (budget, deadlines, regulations, existing systems, team skills) and the assumptions being made. Options: at least two genuine alternatives, often including "do nothing" or "defer". A decision with only one option considered is an announcement, not a decision. Criteria: how options will be judged, derived from stakeholder concerns and weighted by importance. Decision and rationale: the option chosen and, crucially, why it beat the others on the criteria. Consequences: what becomes easier, what becomes harder, what new risks appear, and which future options are now closed. Status: proposed, accepted, deprecated or superseded, plus who made the decision and when.

Consequences deserve particular attention because they are where honesty is tested. Every option has downsides; writing them down protects the team from surprise and gives the next decision-maker a fair account. The consequences of one decision also become part of the context for the next: once you have chosen asynchronous messaging, you must decide how to handle duplicate and out-of-order messages.

One-way doors and two-way doors

The most useful single property of a decision is its reversibility: how cheaply and safely it can be undone. In his 2015 letter to Amazon shareholders, Jeff Bezos distinguished Type 1 decisions, which are consequential and irreversible or nearly so ("one-way doors"), from Type 2 decisions, which are changeable and reversible ("two-way doors"). Type 1 decisions deserve slow, careful deliberation and consultation. Type 2 decisions should be made quickly by individuals or small groups with good judgement, because if they turn out wrong you can walk back through the door. His warning was that large organisations tend to apply the heavyweight Type 1 process to everything, which makes them slow and timid.

The idea translates directly into architecture. A one-way door in software is a decision that would require rewriting large parts of the system, migrating large amounts of data, renegotiating contracts or retraining many people to undo: the primary programming language of a large codebase, the data model of a system of record, the public API that hundreds of partners integrate with, a multi-year cloud commitment. Two-way doors include the choice of a logging library behind your own interface, the internal structure of one module, the tuning of a cache, or which of two equivalent message formats to use inside one service.

Two cautions. First, reversibility is a spectrum, not a binary: most decisions sit somewhere between "trivial to undo" and "impossible to undo", and the cost of reversal usually grows as more code, data and people come to depend on the choice. A decision that is a two-way door in month one can become a one-way door by month twelve. Second, you can often change which kind of door you are facing, by design, as the section on reversibility below shows.

Timing: the last responsible moment

When should a decision be made? Mary and Tom Poppendieck, in Lean Software Development: An Agile Toolkit (2003), popularised the idea of deciding at the last responsible moment: the moment at which failing to decide would eliminate an important alternative. Before that moment you are deciding with less information than you could have; after it, the decision is made for you by default, usually badly.

The principle cuts both ways. It argues against deciding too early: fixing the database technology in week one, before you understand the data's shape and access patterns, is guessing. It equally argues against deciding too late. If the team has started writing persistence code against an unspoken assumption, the decision has already been made, just not consciously. If procurement needs six weeks to approve a cloud provider, the last responsible moment for that choice is at least six weeks before you need the environment.

Practitioners disagree about how far to push this. Critics point out that "last responsible moment" is easily misused as a licence to procrastinate, that some decisions (team structure, programming language) shape everything that follows and so must be made early, and that indecision has its own cost: teams cannot work in parallel without agreed interfaces. Advocates reply that the principle never meant "as late as possible" but "as late as is responsible", and that identifying the moment is itself an act of planning. Both positions agree on the practical core: know which decisions are pending, know when each must be made, and use the time before then to learn.

Designing for reversibility

The cheapest way to make a hard decision is often to turn it into an easier one. Several techniques lower the cost of changing your mind later, at the price of some effort now.

Abstraction at the boundary. Put a narrow interface of your own between your core logic and a technology you might replace, such as a payment provider, a message broker or a large language model API. Swapping the technology later then touches one adapter instead of the whole codebase. The idea goes back to David Parnas's information hiding (1972) and reappears in hexagonal architecture (Chapter 5). Feature flags. Ship new behaviour switched off, turn it on for a small share of users, and switch it off again in seconds if it misbehaves; this makes releases two-way doors. Incremental migration. Run old and new side by side and move traffic gradually rather than switching in one step. Spikes and proofs of concept. Spend a few days building the riskiest part with a candidate technology before committing to it. Contractual exits. Prefer shorter commitments, standard data formats and the ability to export your data.

This is options thinking, borrowed from finance: you pay a small premium now (an adapter, a flag, a spike) to buy the right, but not the obligation, to change course later. Like any option, it is only worth buying when the premium is small relative to the value of the flexibility. Wrapping every library in an abstraction "in case we change it" is a classic way to add cost and indirection for flexibility nobody uses. Buy options on the decisions that are both uncertain and expensive to reverse; for everything else, decide and move on.

Cognitive traps

Architects are human, and architectural decisions are made under uncertainty, time pressure and social pressure: ideal conditions for cognitive biases. Knowing the common ones by name makes them easier to catch in yourself and to challenge kindly in others.

Recording decisions: a preview of ADRs

The second law says the why matters more than the how, so the why must be written down. The most widely used lightweight format is the Architecture Decision Record (ADR), proposed by Michael Nygard in a 2011 blog post. An ADR is a short text file, kept with the code in version control, that records one decision using the anatomy described above: title, status, context, decision and consequences. ADRs are never edited to change history; a later decision supersedes an earlier one and links to it, so the log tells the story of how the architecture evolved.

Chapter 4 covers templates, tooling and the habits that keep ADRs useful in Architecture Decision Records. The example below records the decision from the worked example.

ADR 7: Use managed PostgreSQL for the order service

Status: Accepted (2026-10-12)

Context
Orders and payments need multi-row transactions and must never be lost.
The team knows PostgreSQL well and has no database administrator.
Expected growth is about 3x in two years.

Decision
We will use the cloud provider's managed PostgreSQL service.

Consequences
+ Backups, patching and failover are handled by the provider.
+ Standard SQL keeps self-hosting or another provider open as a fallback.
- Monthly cost is about 30% higher than self-hosting at current load.
- Maintenance windows are set by the provider.
Revisit if write volume exceeds what one primary instance can handle.