Software architecture · Level 6: Governance and evolution · Module 29 of 46

Analysing an existing architecture

Most architects spend more time with systems that already exist than with new ones. The first job is to see what's really there, which is rarely what the diagrams say. Code and its history hold the evidence: which components have grown out of proportion, where dependencies form cycles, which few files cause most of the bugs. This module covers the signs of structural decay and the measurements that find them.

1. The idea

A building survey before you buy a house. The estate agent's brochure shows the rooms; the surveyor checks for damp, cracks and subsidence, measures them, and says which ones matter. The brochure is the architecture diagram; the survey reads the building itself.

Sign of decay	What it looks like	How to measure
Components out of proportion	One component holds a third of all the code; others are tiny	Lines or statements per component as % of the codebase
Dependency cycles	A depends on B, B on C, C on A: none can change or be released alone	Cycle detection on the dependency graph; a dependency structure matrix
Rising coupling	Each release adds dependencies between components	Afferent/efferent coupling over time (Module 07)
Hotspots	A few complex files change constantly and carry most of the bugs	Change frequency × complexity, from version control history
Blurred boundaries	Code in the wrong component; "shared" packages with business logic	Namespace rules (Module 08), architecture tests (Module 26)

For distributed systems, add: services that share databases (Module 09), call graphs with long synchronous chains (Module 10), and services so small that every feature touches several of them.

2. How it works

Two years of structural decay

A system's components, sized by their share of the code. Watch what releases do to them.

Finding a cycle nobody drew

The architecture diagram shows dependencies flowing one way. The code says otherwise.

3. Try it yourself

Find the hotspots

Thirty files from an orders service, plotted by how complex they are and how often they changed in six months (dot size = bug fixes). Set the thresholds that define a hotspot and see how much of the trouble a few files cause.

Illustrative data, shaped like real repositories: change and defects concentrate in a small share of files. Tools such as CodeScene, code-maat or a short script over git log produce the same plot from your own history.

4. Trade-offs

Tools vs judgement

Metrics point to where to look; they don't say what's wrong. A big component may be big because the domain is; a frequently changed file may be the right place for change. Read the code the numbers point to.

Static vs historical

Static analysis shows structure today; version-control history shows where effort and bugs actually go. Combine them: a complex file nobody touches is less urgent than a moderately complex one changed daily.

Fix everything vs fix hotspots

Rewriting all the messy code is expensive and risky. Fixing the few hotspots that absorb most change gives most of the benefit.

Snapshot vs trend

One measurement tells you little; the trend tells you whether it's getting better or worse. Track a few numbers per release.

5. In real projects

Start an analysis with three questions. What are the components and how big is each? What depends on what (and are there cycles)? Where has change and pain concentrated over the last six to twelve months? Each can be answered from the code and its history in a day.

Talk to the people. The numbers say where; developers say why. "We all avoid touching PricingEngine" is architecture information no tool reports.

Use the findings to plan, not to blame. Present decay as risk with a cost (Module 28) and a proposed remedy, in the business's terms: "every change to checkout takes three times longer than it should because of these four files."

A formal review: ATAM

Code analysis finds structural decay. To check whether an architecture can meet its quality goals at all, the Software Engineering Institute's Architecture Tradeoff Analysis Method (ATAM) is the best-known formal review. A trained team runs it with architects and stakeholders over a few days, in nine steps:

Present the method.
Present the business drivers.
Present the architecture.
Identify the architectural approaches used (without judging them yet).
Build a utility tree: quality attributes broken down into concrete scenarios (Module 05), each rated for business importance and technical difficulty.
Analyse the approaches against the most important scenarios.
Brainstorm and prioritise more scenarios with the wider stakeholder group.
Analyse again with the top new scenarios.
Present the results.

Utility tree branch	Scenario	Importance, difficulty
Availability → zone failure	One zone fails at peak; checkout errors back under 0.1% within 60 s	High, high
Performance → search latency	10,000 searches a second; p99 under 300 ms	High, medium
Modifiability → new market	Add a country's tax rules in under 2 weeks, touching one module	Medium, low

The outputs are lists of risks (decisions that may stop a goal being met), non-risks, sensitivity points (where one parameter strongly affects a quality, such as a cache's size on latency) and trade-off points (where one decision affects several qualities in opposite directions). Few teams run a full ATAM; most borrow its core: a utility tree of scenarios, then walking each high-priority scenario through the design.

Say it in the interview

Two-sentence answers

"How would you assess a codebase you've just inherited?" Map the components and their sizes, find dependency cycles, and plot change frequency against complexity from version control to find hotspots. Then talk to the developers about what the numbers show.
"What's a hotspot?" A file or component that is both complex and changed often. A small share of files usually carries most of the change and most of the bugs, so they're where refactoring pays off first.
"What are signs of structural decay?" Components out of proportion, dependency cycles, coupling rising release by release, and business logic leaking into shared packages.

Red flags interviewers notice

Trusting the architecture diagram without checking the code.
"Rewrite it all" as the first recommendation.
Metrics presented without interpretation.

6. Remember it

Memory hook: "Survey the house, not the brochure"Measure the code and its history; the diagram is what someone hoped the system would be.

How this hook works: what "survey the house, not the brochure" means

What the slogan means, phrase by phrase

"Survey the house": Read the evidence: component sizes, dependencies, cycles, change history.
"not the brochure": Diagrams and documents describe intent, not what the code became.

Why this picture fits: nobody buys a house from the brochure alone, yet teams plan years of work from diagrams nobody has checked against the code.

The story → the concept

House survey	Architecture analysis
Measuring the rooms	Component sizes
Cracks in load-bearing walls	Dependency cycles
The damp patch that keeps returning	A hotspot
The surveyor's priced report	Findings as risks with costs

The trap it saves you from

Planning a migration around an architecture that exists only on the diagram.

7. Common mistakes

Analysing only the presentA snapshot misses the trend and the history of where effort goes. Mine version control.

Metrics as targets"Every class under complexity 10" gets gamed. Use metrics to find problems, not as goals.

Refactoring cold codeCleaning up complex code nobody changes feels productive and buys little. Start with hotspots.

Skipping the peopleThe team knows which parts hurt and why; the tools don't.

8. Design exercise (30 minutes)

Size the components (10 min). For a codebase you know, count lines per top-level component. Which is over a quarter of the total?
Find a cycle (10 min). Run a dependency tool (or read imports) between components. Is there a cycle?
List the hotspots (10 min). From git log, list the ten most-changed files in six months. Which of them are also the most complex?

9. Self-check quiz

In ATAM, what is a trade-off point?

Example: encrypting every message raises security and lowers throughput.

What is a hotspot?

Complexity × change frequency: where effort and bugs concentrate.

Components A, B and C depend on each other in a cycle. What's the problem?

A cycle makes them one unit in practice.

Where does change-frequency data come from?

Commits per file over time.

One component holds 35% of the codebase. What does that suggest?

Out-of-proportion components often hide several responsibilities.

Where should refactoring effort go first?

That's where most of the cost of change is paid.

10. Go deeper

Resource	Time	Why
Your Code as a Crime Scene, 2nd edition (Adam Tornhill)	book	Hotspots and behavioural code analysis from version control.
code-maat	tool	An open-source tool for mining change history.
Is High Quality Software Worth the Cost? (Martin Fowler)	15 min	How internal quality affects the speed of change, for business audiences.