Lesson 1 of 4
Architecture Is What You Cannot Cheaply Undo
Every popular definition of architecture is either circular or useless in a meeting. This one is neither: architecture is the set of decisions whose cost of reversal is high.
Ask ten engineers what software architecture is and you will get ten answers involving the words "high-level", "structure", and "the big picture". None of them help you on the day you have to decide whether the new notifications feature gets its own service. You need a definition that resolves an argument, not one that decorates a slide.
This is Ralph Johnson's framing, sharpened by Martin Fowler, and it is the only definition that survives contact with a real project. It is useful precisely because it is testable. You can look at a decision and ask a concrete question: if we get this wrong and discover it in nine months, what does it cost to undo? If the answer is "an afternoon", it is not architecture. If the answer is "two quarters and a data migration", it is.
The reversibility test
Reversibility is not a binary. It is a spectrum, and most decisions sit somewhere in the middle. What makes the test practical is that you rarely need precision — you need to know which side of "a sprint" the answer falls on.
| Decision | Cost to reverse in month 9 | Architectural? |
|---|---|---|
| Which HTTP client library the service uses | A day. One adapter, one set of tests. | No |
| Whether payments are a module or a separate service | A quarter. Split or merge a datastore, re-do deployment, re-do observability. | Yes |
| Naming convention for REST endpoints | A week internally; forever if partners consume them. | Depends on who is coupled to it |
| Whether the system stores money as integers or floats | A migration of every historical row, plus a reconciliation exercise. | Yes |
| Which validation library the API layer uses | A day per endpoint, mechanical. | No |
| Whether tenants share a database or get one each | A rebuild of the data access layer and every query in it. | Yes |
The same question, asked two ways
As a developer
Should we use PostgreSQL or MongoDB for this feature? You weigh the developer experience, the query syntax you prefer, and what the team already knows. You are choosing a tool, and you are optimising for how quickly you can ship the feature in front of you.
As an architect
What are the consistency, query and growth characteristics of this data over the next three years, and which store fails least badly when we are wrong? You are choosing a constraint that a dozen future features will inherit, and you are optimising for how cheaply the team recovers when the requirement you were not told about arrives.
Why anyone bothers
Architecture is not free. It costs meetings, documents, and the patience of people who would rather be writing code. It earns that cost back in exactly one way: it reduces the number of expensive surprises. A system with no deliberate architecture does not avoid architectural decisions — it makes them accidentally, one pull request at a time, and discovers the bill later.
- It makes the expensive decisions explicit, so they get the scrutiny their cost deserves rather than being settled by whoever opened the pull request first.
- It creates shared constraints, so five teams building independently still produce one coherent system rather than five overlapping ones.
- It bounds the blast radius of being wrong, because a decision made behind an interface can be replaced without touching everything that used it.
- It gives the organisation a vocabulary for saying no, which is the only defence against a system that slowly accumulates every feature anyone ever asked for.
In practice
A decision that looked like a detail
A B2B scheduling product launched with a single shared PostgreSQL database and a `tenant_id` column on every table. It was the obviously pragmatic choice for a team of four with eleven customers, and it worked well for three years.
Constraints
- Team of four at the time of the decision
- No compliance requirements yet
- Speed to first revenue mattered more than anything
- Nobody had asked about data residency
Decision
Ship with a shared database and a tenant discriminator column, deferring per-tenant isolation until a customer required it.
Why
At eleven customers the operational cost of managing separate databases was real and the benefit was hypothetical. The decision was correct for the information available, and the team wrote down why — including the trigger that would force a revisit.
What it cost
Three years later a European health customer required data residency in the EU and physical isolation. The reversal took two engineers five months: extracting the data access layer, backfilling a tenant-routing abstraction, migrating 40 million rows and re-validating every query. The team had been right to defer, and it still cost five months — which is exactly what "architectural" means.
Your team is deciding whether to expose a new internal capability as a REST endpoint or as a library other services import. Is this an architectural decision?RevealHide
Yes, and it is one of the most consequential ones available. A library couples every consumer to your release cycle, your language runtime and your in-process failure modes; an endpoint couples them to your availability and your network. Reversing it means changing every consumer, and consumers are the thing you control least. The tell is not that it involves an API — it is that other teams will build on top of whichever you choose.
Key takeaways
- Architecture is the set of decisions that are expensive to change; everything else is design.
- Apply the test by asking what reversing the decision costs in nine months, not how important it feels today.
- Decisions become expensive because other things couple to them — data shape, team structure, or external consumers.
- A decision can drift into being architectural over time, which is why deferred decisions need a written trigger for revisiting them.
- The value of doing architecture deliberately is fewer expensive surprises, not better diagrams.