Skip to main content

Architecture Is Structure Plus Decisions That Are Hard to Change

What This Concept Is​

Software architecture is two things, in parallel:

  • the structure of the system: its major components, their responsibilities, and how they relate to each other
  • the decisions about that structure - especially the ones that would be expensive to change later

The working definition used throughout this module is: architecture is the set of decisions that, if made wrong, you would be living with for quarters or years. Everything else is design or implementation.

Ralph Johnson's line, widely cited by Martin Fowler, sharpens this: "Architecture is about the important stuff. Whatever that is." The test is always reversal cost. If getting it wrong means an afternoon of refactoring, it is not architectural. If getting it wrong means a migration plan, a stakeholder meeting, and a budget line, it is.

Why It Matters Here​

Teams waste enormous effort treating architecture as a collection of patterns or buzzwords. The result is two symmetric failures:

  • Over-architecture. Every file has "Architecture" in its title; every decision is a formal review; velocity collapses.
  • Under-architecture. Nothing is called out as architectural, and the organization lives for a decade with accidental choices that nobody remembers making.

This concept is the filter. Every later concept in this module (quality attributes, characteristics, fitness functions, tradeoffs, risk) only makes sense once you can answer the question: is this decision architectural or not?

Concrete Example​

Consider three decisions from a payments platform that processes bank-teller transactions:

  1. "Accounts and transactions live in a single relational store with ACID guarantees."

    • Reversal cost: extreme. Moving to an eventually consistent store would rewrite every workflow that assumes a balance is correct on read.
    • Blast radius: the whole system, plus downstream reports, plus auditors.
    • Architectural. This is structure and a hard-to-change decision.

  2. "The ledger service exposes its domain through a REST API with idempotency keys required on writes."

    • Reversal cost: high. Every consumer is now coupled to the wire format.
    • Blast radius: every team that integrates.
    • Architectural. Classic boundary decision.

  3. "Inside the ledger service, the TransactionRepository class uses constructor injection for its DB client."

    • Reversal cost: an afternoon.
    • Blast radius: one file and its tests.
    • Not architectural. This is internal design; handle it in code review.

Same repository, three decisions, one architectural test applied.

Common Confusion / Misconception​

"Architecture is the diagram on the wiki." The diagram is a view of architecture. The architecture is the structure and the decisions that produced it, whether they are drawn or not.

"Architecture is the framework you chose." A framework is one decision among many. Picking Spring Boot is architectural; picking which of Spring Boot's annotations to import on a specific controller is not.

"If it's in the code, it's not architecture." Clean Architecture's central argument is the opposite: the code is where architecture becomes real. A layered diagram with no enforcement in the code is a marketing document, not architecture.

"Only senior engineers make architecture decisions." False and risky. Any engineer who picks something that will be expensive to reverse has just made an architectural decision. The role question is who reviews it.

How To Use It​

Before every decision, run the three-question test:

  1. Reversal cost. If I need to undo this in 12 months, is it an afternoon, a sprint, or a migration?
  2. Blast radius. Who would notice if it changed? One file, one service, or multiple teams?
  3. Externalized constraint. Does this impose something on someone not in this PR (another team, an operator, a consumer)?

If the reversal cost is "migration" or the blast radius is "multiple teams," treat the decision as architectural: write it down, name the alternatives, state the tradeoffs. If all three answers are small, it is design; handle it in code review.

Check Yourself​

  1. For each, architectural or not, with one-sentence justification: (a) choice of primary database engine; (b) name of an internal helper function; (c) adopting OpenTelemetry across all services; (d) internal naming convention for feature flags.
  2. Name one decision in a system you know that looked like design and turned out to be architecture. What escalated it?
  3. If architecture is "the important stuff, whatever that is," how do you stop the definition from becoming circular?

Mini Drill or Application​

Pick a system you have worked on. List 10 decisions that are currently in the code. For each:

  • reversal cost (afternoon / sprint / migration)
  • blast radius (one file / one service / multiple teams)
  • externalized constraint (yes / no)

Expect 2-4 of them to be architectural. The rest are design. Count how many of the architectural ones had any written record when they were made. The gap between "architectural" and "written down" is usually the real source of pain in the system.

Read This Only If Stuck​