Skip to main content

Foundationbeginner

What Software Architecture Is

Overview​

There are dozens of definitions of software architecture in the literature, and most are true and useless at the same time. "The high-level structure of the system" describes something real and helps nobody decide whether a specific choice is architectural.

The operational definition used throughout this material is different:

Architecture is the set of decisions whose cost of reversal is high.

That formulation, close to the one Martin Fowler popularized, has a property the others lack: it is applicable. Faced with any choice, you can ask what it would cost to undo it in six months, with the system in production and consumers coupled to it. If the answer is "a lot", the decision is architectural, and deserves the corresponding care.

The Problem​

The question "is this architecture?" comes up constantly in real teams, and is usually answered by proxy: it is architecture if the architect decided it, or if it appears in the diagram, or if it spans more than one service.

None of those proxies works.

The choice of identifier format for an entity — sequential integer, UUID, natural key — appears in no diagram, spans no more than one service, and is frequently made by whoever writes the first migration. It is also one of the most expensive decisions to reverse that exists: it changes the schema, the indexes, the foreign keys, the API contracts, the historical data, and every system that stored that identifier.

Meanwhile, the choice between two serialization libraries — which routinely consumes half an hour of debate — can usually be swapped in an afternoon.

Using hierarchy or the diagram as the criterion makes the team spend architectural attention on the second and none on the first.

Core Concepts​

Cost of reversal, not importance​

The criterion is not how important the decision seems. It is what it costs to undo once the system is in use.

That cost has predictable components: how many modules depend on the decision, how many external systems observe it, how much data exists in the old format, and whether there is an incremental migration path or only a single cutover.

Every system has an architecture​

Every system has an architecture, whether or not anybody decided it. High-cost-of-reversal decisions get made regardless — the difference is whether they were made deliberately or by accident of implementation.

"We don't have an architecture" is never true. What exists is accidental architecture: the accumulated result of local decisions nobody evaluated against future cost.

The scope is contextual​

What counts as architectural depends on the system. In an application with ten internal users, the choice of database is easily reversible — little data, no external consumers, an afternoon of work. In the same application eight years and forty integrations later, the same choice has become irreversible in practice.

The decision did not change. The cost of reversal changed. That is why architecture is a property of the relationship between a decision and its context, not of the decision alone.

Architecture is not the diagram​

The diagram is a representation, and a partial one. It shows static structure and rarely shows the decisions that cost the most: consistency guarantees, data ownership, error contracts, retry semantics.

A system can have an impeccable diagram and a poor architecture.

Mental Model​

Think of architecture as the set of doors you close.

Every decision opens one path and closes others. Choosing strong consistency closes the door of operating during a network partition. Choosing a document database closes the door of cheap relational queries. Choosing microservices closes the door of local transactions between them.

Architectural decisions are the ones whose closed doors are expensive to reopen.

That leads directly to a practical heuristic: when two options tie on merit, choose the one that is cheaper to abandon. You will get some of these decisions wrong — everyone does — and what separates a system that recovers from one that does not is what each mistake costs.

Why This Matters​

Defining architecture by cost of reversal changes three things in practice.

It changes where attention goes. A team applying this criterion spends two hours deciding an identifier format and ten minutes choosing a logging library — which is the inverse of the common pattern, and the correct one.

It changes who decides. If architecture is defined by cost of reversal rather than by job title, then whoever writes the migration is making an architectural decision, and needs to know that. The alternative — concentrating decisions in an architect who is not present at every choice — does not scale: past a handful of decisions a week the queue becomes the bottleneck, and what does not fit it gets decided by omission.

It changes what gets documented. You record the reasoning behind decisions that are expensive to reverse, because those are the ones someone will want to reassess when the context changes, and the ones that cannot be rediscovered experimentally.

Without that criterion, architectural discussions become disputes about what "counts" as architecture, which is a conversation with no exit because it has no criterion.

Common Mistakes​

Confusing architecture with technology. "Our architecture is Kubernetes with Kafka" describes infrastructure choices, not architecture. The architectural decisions live in how the boundaries were drawn and what guarantees exist between them — things that survive replacing Kafka with something else.

Treating architecture as a phase. Architecture does not happen before development and then end. High-cost-of-reversal decisions keep being made in year three, frequently by people who do not consider themselves architects.

Assuming a decision that is hard to make is hard to reverse. They are independent. Choosing between two cloud providers is painful to make and expensive to reverse. Choosing the name of a public API field is trivial to make and expensive to reverse. The second gets less attention than it deserves precisely because it is easy.

Believing an architectural decision has to be big. Many are small in effort and enormous in consequence: the format of an identifier, the semantics of a nullable field, whether an endpoint is idempotent.

Deferring decisions on the assumption that deferral is free. Deferral has a cost: the system keeps being built on the absence of the decision, and frequently the decision ends up being made by omission. Deferring is useful when it buys relevant information — not when it merely pushes the choice onto whoever has less context.

Real-World Example​

A subscription system needs to record the moment of each charge. Two options come up in code review.

Option A — store in UTC and convert for presentation. Option B — store in the customer's time zone.

Framed as an implementation detail, the debate resolves by preference and takes fifteen minutes.

Evaluated by cost of reversal: which of the two is more expensive to undo with two years of data? Option B, by a wide margin — reversing requires reinterpreting every historical record against the time zone in force for that customer on that date, including daylight-saving changes that already happened. Part of the information needed may not even have been stored.

Option A is not obviously better on every dimension — reports by local day become more laborious. But it is dramatically cheaper to abandon, and it is that asymmetry that settles the case.

The value of the criterion here was not pointing at the answer. It was turning a discussion of preference into a question with a verifiable answer.

Practical Exercise​

Take a system you work on. List ten decisions made in the past six months — any decision, from library choice to field name.

For each, estimate in working days what it would cost to reverse today.

Two questions about the result: how many of the five most expensive received explicit discussion when they were made? And how many were made by someone who knew they were deciding something high-cost?

What is missing from five is the team's architectural gap. The parallel question — how many were explicitly discussed — measures something else: how much was debated without knowing what was at stake.

Interview Questions​

  • How do you decide whether a choice is architectural?
  • Name a decision that was small in effort and large in consequence that you have made.
  • Can a system have good architecture without documentation? Can it have impeccable documentation and poor architecture?

Further Exploration​

  • Fowler, Martin. Who Needs an Architect? IEEE Software, 2003 — the origin of the cost-of-change formulation.
  • Ford, Neal; Parsons, Rebecca; Kua, Patrick. Building Evolutionary Architectures. O'Reilly, 2017 — architecture as a property that evolves.
  • Bass, Len; Clements, Paul; Kazman, Rick. Software Architecture in Practice. 4th ed., Addison-Wesley, 2021 — the classic structural definition, useful as a counterpoint to the one adopted here.
Finished reading this document?Your progress is saved in this browser only.