Quick Navigation
- Start here — What even is architecture?
- The misconception everyone believes
- The real definition
- Levels of architecture
- Architecture as a living thing
- What architects actually produce
- How to read an architecture
- Putting it all together
- Cheat sheet
Before we start — the one thing to hold onto
Most people think architecture is diagrams on a wall. I've sat in rooms with senior architects who had produced hundreds of diagrams over eighteen months, and when I asked a developer on the team why a particular technology was chosen, nobody could tell me. Not because the diagrams were bad. Because the diagrams weren't the architecture.
Architecture is the structure of a system — its components, the relationships between them, and the decisions that shaped them.
Everything else — the diagrams, the documents, the tools — is just how we communicate those decisions.
Keep it in mind.
1. What is architecture? — Let's start from scratch
The word "architecture" has become one of those terms that everyone uses and nobody can quite define. I see it in job descriptions, project charters, vendor pitches — and most of the time, the person writing it couldn't tell you what they mean by it if I asked.
Let's sort it out properly.
Here's a question I ask in every architecture workshop: if you removed all the diagrams, all the documents, all the wiki pages — would the system still have architecture?
The answer is yes. Every system has architecture. Even the ones nobody drew. Even the ones that grew organically over five years with twelve different teams touching the codebase. The structure is there. The relationships are there. The decisions are there — even if they were made by accident, by default, or by whoever happened to be in the room when the choice was made.
Architecture exists whether you design it or not. The only question is whether it's deliberate.
flowchart LR
A["❌ Accidental Architecture\nNo one designed it\nIt just grew"] --> B["Structure exists anyway\nComponents, relationships, decisions"]
B --> C["Consequences\nHard to change, hard to explain"]
D["✅ Intentional Architecture\nDesigned deliberately\nDecisions documented"] --> E["Structure exists deliberately\nComponents, relationships, decisions"]
E --> F["Consequences\nEasier to change, easier to explain"]
Once you understand that architecture exists whether you design it or not, the rest of this module makes sense — including why it matters who makes the decisions.
Try it yourself — Spot the architecture
Think of a system you work with — an application, a platform, a service. Now answer these three questions:
| Question | Your answer |
|---|---|
| What are the main components? | e.g. Frontend, API, database, message queue |
| How do they connect? | e.g. Frontend calls API, API writes to DB, publishes events |
| Who decided this structure? | e.g. Original tech lead, nobody remembers, it just evolved |
If you can't answer the third question, you have architecture. It just wasn't designed deliberately. Write that down before moving on.
2. The misconception — What people think architecture is
Here's what happens in most organisations. Someone says "we need architecture." So the architecture team gets to work. They draw boxes. They connect them with arrows. They pick colours for different layers. They produce a beautiful diagram. Everyone nods. Then a team starts building and makes a technology choice that doesn't match the diagram. Nobody notices. Six months later, the system has a structure — but it's not the one on the wall.
The diagram was never the architecture. The diagram was a picture of a decision that may or may not have been made.
A diagram is a picture of a decision. The decision is the architecture.
flowchart TD
MYTH["❌ Myth\n'Architecture = Diagrams'"] --> WASTE["Wasted effort on beautiful diagrams\nwith poor decisions behind them"]
TRUTH["✅ Truth\n'Architecture = Decisions + Structure + Relationships'"] --> VALUE["Clear decisions that guide teams\nand evolve over time"]
The ISO/IEC 42010 standard makes this distinction explicit — and most architects have never read it. Architecture is the fundamental organisation of a system. Architecture description is the document that captures it. They are different things. A beautiful diagram with poor decisions behind it is bad architecture. A great decision with no diagram is still good architecture — just poorly communicated.
Try it yourself — The diagram test
Find an architecture diagram from your organisation — any diagram, any system. Now ask:
| Question | What it reveals |
|---|---|
| What decision does this diagram represent? | If you can't name the decision, it's art, not architecture |
| Who made that decision? | If nobody owns it, it wasn't a decision — it was a suggestion |
| What would break if a team ignored it? | If nothing, it's not architecture — it's decoration |
Most people's "diagram test" results are uncomfortable. That's the point.
3. The real definition — Structure, relationships, decisions
So what is architecture, precisely?
Ralph Johnson — one of the original Gang of Four authors — put it this way: "Architecture is about the important stuff. Whatever that is."
That's funny, but not precise enough. Here's the definition I use:
Architecture is the set of significant design decisions — those that are costly to change, affect multiple teams, or shape future options.
Three pillars hold this up:
Structure — what the parts are. Components, services, layers, platforms. Not individual functions or classes — the things that teams build around.
Relationships — how the parts connect and interact. Dependencies, data flows, contracts, integration patterns. This is where most architecture fails — not in the components themselves, but in how they talk to each other.
Decisions — why the parts exist in this form. Trade-offs, constraints, principles, context. The reasoning behind the structure.
flowchart TD
A["🏗️ Architecture"] --> B["Structure\nWhat are the parts?"]
A --> C["Relationships\nHow do they connect?"]
A --> D["Decisions\nWhy this form?"]
B --> B1["Components\nServices\nLayers\nPlatforms"]
C --> C1["Dependencies\nData flows\nContracts\nIntegration"]
D --> D1["Trade-offs\nConstraints\nPrinciples\nContext"]
Here's the part that catches people out: choosing a variable name is not architecture. Choosing a database technology is. The difference isn't about technology — it's about cost of change. If you change a variable name, one file changes. If you change a database, three teams rewrite their code, data migrates, and downtime happens.
Architecture = decisions and their consequences, not diagrams.
Try it yourself — The cost of change test
List three recent technology decisions from your team. For each one, rate the cost of reversing it:
| Decision | Cost to reverse | Why? |
|---|---|---|
| e.g. Chose PostgreSQL over MongoDB | High — data model, queries, team skills all tied to it | |
| e.g. Named this service 'OrderService' | Low — find and replace, maybe a config change | |
| e.g. Decided all services use async messaging | Very high — every service needs rewriting |
Which of these three is architecture? The answer is the one that's most expensive to undo. That's always the right test.
4. Levels of architecture — From component to enterprise
Architecture exists at every scale. People often think of it only at one level — usually the one they work at. A developer thinks component architecture is the real thing. A CTO thinks enterprise architecture is the only thing that matters. Both are wrong.
Architecture is fractal. The same thinking applies whether you're designing a single service or an entire organisation.
Enterprise → How does the whole organisation connect?
Domain → How do business capabilities map to systems?
System → How do services and platforms fit together?
Component → How is this service structured internally?
Code → How is this module designed?
flowchart TD
E["🏢 Enterprise Architecture\nWhole organisation"]
E --> D["📦 Domain Architecture\nBusiness capabilities"]
D --> S["⚙️ System Architecture\nServices & platforms"]
S --> C["🧩 Component Architecture\nIndividual service"]
C --> K["💻 Code Architecture\nModules & patterns"]
A component-level decision — like "use event sourcing in this service" — ripples upward. Suddenly you need event infrastructure. Suddenly other teams want to publish and subscribe. Suddenly your system architecture needs an event bus. Suddenly your enterprise architecture needs an integration platform.
Architecture is fractal — same patterns, different zoom levels.
Try it yourself — The ripple test
Think of a recent technical decision your team made. Now trace the ripple:
| Level | Who is affected? | What changes? |
|---|---|---|
| Code | Your team | Design patterns, code structure |
| Component | Your team + adjacent teams | API contracts, data models |
| System | Multiple teams | Integration patterns, deployment |
| Domain | Business unit | Capability ownership, data boundaries |
| Enterprise | Whole organisation | Platform strategy, vendor relationships |
Where does your decision stop rippling? If it doesn't ripple at all, it's probably too local to be architecture. If it ripples to enterprise, it definitely is.
5. Architecture as a living thing — It evolves or it rots
Here's something nobody tells you about architecture: it has a half-life.
Architecture that was right in year one may be wrong in year three. Requirements change. Technology moves. Teams grow. The structure that made sense when you had three microservices and one team makes no sense when you have thirty microservices and eight teams.
There are two paths every architecture takes:
Designed → Adapted → Adapted → Current. Deliberate evolution. Decisions are revisited as context changes. The architecture stays fit for purpose.
Undesigned → Accidental → Entangled → Unmaintainable. Accidental drift. Nobody maintains the structure. Every change makes the next change harder. The architecture becomes a constraint instead of an enabler.
flowchart LR
D1["📐 Designed\nYear 1"] -->|"Change"| D2["📐 Adapted\nYear 2"]
D2 -->|"Change"| D3["📐 Adapted\nYear 3"]
D3 -->|"Change"| D4["📐 Current\nYear 4"]
N1["❌ Undesigned\nYear 1"] -->|"Drift"| N2["❌ Accidental\nYear 2"]
N2 -->|"Drift"| N3["❌ Entangled\nYear 3"]
N3 -->|"Drift"| N4["❌ Unmaintainable\nYear 4"]
Architecture erosion happens through three mechanisms. Entropy — changes accumulate without design review. Drift — implementation diverges from documented architecture. Ossification — architecture becomes too rigid to change.
The fix isn't more diagrams. It's continuous maintenance. ADRs to track decisions. Architecture reviews to catch drift. Evolutionary design to keep the structure fit for purpose.
Architecture evolves — or it rots.
Try it yourself — The architecture health check
Think of a system you work with. Rate each statement from 1 to 5:
| Statement | Rating (1-5) | Evidence |
|---|---|---|
| The team can explain why key technology choices were made | ||
| The architecture diagrams match what's actually running | ||
| Adding a new feature is easier than it was a year ago | ||
| Decisions are documented somewhere beyond people's heads | ||
| The architecture has changed deliberately in the last 6 months |
Where are your weakest areas? That's where architecture maintenance needs to focus. Be honest — most teams score lower than they'd like on the second and fourth rows.
6. What architects actually produce — Clarity, not diagrams
If architecture isn't diagrams, what do architects actually produce?
I've asked this question in workshops with architects who've been doing this for twenty years. The answers range from "vision" to "strategy" to "governance." All true. None precise.
Here's what architects produce:
Decisions — what to do and what not to do. Not suggestions. Not options. Decisions.
Constraints — what teams must work within. Not everything is a choice. Some things are fixed so teams can move fast within the guardrails.
Principles — how to make future decisions consistently. If you can't be in every room, you need rules that let teams decide without you.
Models — simplified representations that help people understand the system. Not the full system. The parts that matter for a specific conversation.
Communication — shared understanding across teams and stakeholders. The ability for teams to make good decisions independently.
flowchart TD
INPUT["Architect's Input\nContext, constraints, stakeholders"] --> WORK["Architect's Work\nDecisions, principles, models"]
WORK --> OUTPUT["Architect's Output\nShared understanding"]
OUTPUT --> RESULT["Teams make good decisions\nwithout the architect in the room"]
The maturity of an organisation's architecture practice shows up in a simple progression. Level 1: Architecture exists in people's heads. Level 2: Key decisions are documented. Level 3: Reviews ensure compliance. Level 4: Automated checks track health. Level 5: Architecture evolves deliberately.
Most organisations are between 2 and 3. The ones at 4 are rare. The ones at 5 are the ones you want to work for.
Architects produce decisions and shared understanding, not just diagrams.
Try it yourself — The artefact audit
What architecture artefacts does your organisation actually produce? Be honest — not what you should produce, what you do produce:
| Artefact | Do you have it? | Is it used? | Does it help teams decide? |
|---|---|---|---|
| ADRs | |||
| Architecture principles | |||
| System context diagrams | |||
| Technology standards | |||
| Roadmaps |
If your "is it used?" column has more blanks than ticks, you're producing architecture theatre — artefacts that look like architecture but don't help anyone decide anything.
7. How to read an architecture — Finding decisions, not diagrams
You join a new team. Or inherit a system. Or get asked to review something. Where do you start?
Most people start with the diagrams. That's the wrong place. The diagrams show you what exists. The decisions tell you why.
Here's the approach I use:
Start with the context. What does the system do? Who uses it? What does it connect to? If you can't answer this in two sentences, you don't understand the system yet.
Find the boundaries. Where are the major seams between components? Where does one thing end and another begin? Boundaries reveal where the architecture drew its lines.
Identify the decisions. What was chosen? What was rejected? Why? If nobody can tell you why a technology was chosen, it wasn't a decision — it was a default.
Check for consistency. Do the diagrams match reality? If they don't, the architecture has drifted. That's not necessarily bad — but you need to know whether the drift was deliberate.
Find the pain points. Where does the architecture fight the team? Where do people complain? Pain reveals where the architecture no longer matches the context.
flowchart TD
Q1["1. Context\nWhat does the system do?"] --> Q2["2. Boundaries\nWhere are the seams?"]
Q2 --> Q3["3. Decisions\nWhat was chosen and why?"]
Q3 --> Q4["4. Consistency\nDoes reality match design?"]
Q4 --> Q5["5. Pain Points\nWhere does it hurt?"]
The C4 model gives you a standard reading order: Context (who uses it, what does it connect to), Containers (deployable units), Components (modules within each application), Code (only for critical parts). But the model is just a lens. The real work is finding the decisions.
To evaluate an architecture, ask: "What decisions were made, and what are their consequences?"
Try it yourself — The architecture reading exercise
Pick a system you know. Now answer these five questions without looking at any diagrams:
| Question | Your answer | Can you verify it? |
|---|---|---|
| Why was the main database chosen? | Ask the person who decided, not the person who implemented | |
| What happens if the message queue goes down? | If nobody knows, failure modes weren't designed | |
| How does data flow between the two biggest services? | Draw it from memory, then check against reality | |
| What's the cost of adding a new API endpoint? | If it takes weeks, the architecture fights you | |
| What would the team change if they could start over? | This reveals the known weaknesses |
Any answer you can't verify means the decision wasn't captured. That's not necessarily a failure — but it means the architecture lives in people's heads, not in shared understanding.
Putting it all together
Here's the complete picture in one diagram. This is the mental model worth internalising.
flowchart TD
BIZ["Business Context\nGoals, constraints, stakeholders"] --> DEC["Architecture Decisions\nSignificant, costly to change"]
DEC --> STR["Structure\nComponents, services, layers"]
DEC --> REL["Relationships\nDependencies, contracts, data flows"]
DEC --> PRN["Principles\nGuiding rules for future decisions"]
STR --> DIAG["Architecture Description\nDiagrams, ADRs, views"]
REL --> DIAG
PRN --> DIAG
DIAG --> TEAM["Shared Understanding\nTeams make good\nlocal decisions"]
DIAG --> GOV["Governance\nReviews, standards,\nfitness functions"]
DIAG --> EVOL["Evolution\nDeliberate adaptation\nas context changes"]
The foundation:
Architecture is decisions, not diagrams. The structure and relationships that are costly to change. It exists whether you design it or not — the only question is whether it's deliberate. It's living — it must evolve or it rots. It's fractal — the same thinking applies from code to enterprise. And it's communication — its value comes from shared understanding that lets teams decide independently.
Cheat Sheet — All the key terms
| Term | Plain English | Technical name |
|---|---|---|
| Architecture | Decisions and their consequences | Fundamental organisation of a system |
| Architecture description | The document that captures the architecture | Views, diagrams, ADRs |
| Accidental architecture | Structure that emerges without deliberate design | Architectural drift |
| Intentional architecture | Structure that is consciously shaped | Deliberate architecture |
| Architectural erosion | Gradual departure from intended architecture | Architecture decay |
| Architectural fitness function | Automated check that architecture holds | Constraint validation |
| Architecture principle | Guiding rule for future decisions | Decision heuristic |
| Architecture view | One perspective on the system | C4 level, deployment view, etc. |
How to know if this landed
You'll know this has landed when someone stops treating architecture diagrams as the architecture itself and starts asking: "What decision does this represent? Who made it? What would it cost to change?" They can explain the difference between architecture and architecture description using their own words. They understand that architecture exists at every level — from code to enterprise — and that the same thinking applies at each one. They treat architecture as something that must be maintained, not something you do once at the start. And they can read an architecture by finding decisions, not just reading diagrams.
What changes when the mental model clicks
I've run this session with teams ranging from junior developers to CTOs. The misconception gap at the start is usually not about technical depth — it's about what people think architecture is.
Most teams spending time on architecture are actually spending time on architecture description. They draw. They document. They present. But they don't decide — or they decide without capturing why. Without a shared understanding of what architecture actually is, every conversation about architecture improvement goes in circles.
What changes after this session:
Teams stop asking "how do we document our architecture?" and start asking "what decisions have we made, and are they still right?" The diagram test — finding a diagram and asking what decision it represents — is always the moment things click. People stop treating architecture as a documentation exercise and start treating it as a decision discipline.
The architecture reading exercise — trying to understand a system by finding decisions rather than reading diagrams — tends to immediately change how people approach onboarding. They start asking "why" instead of "what." Their understanding gets deeper. They stop blaming the previous team when the real problem was that nobody captured the reasoning.
Book a Workshop
Ready to build architecture foundations in your organisation?
or
Half-day workshop includes interactive exercises on architecture definition, architecture canvas creation for your real systems, what it is / what it isn't reference card, and a decision-vs-diagram workshop using your own architecture artefacts.