What an Architecture Review Should Give You

An architecture review is an outside look at how a system is designed and built, and whether that design will hold up. It’s only worth paying for if it changes what you do next.

That sounds like a low bar, but a review that ends as a thick document of diagrams and options gets read once, if at all, discussed at one meeting and filed. Nothing changes, except that someone can now say the system has been reviewed.

Here’s when a review is worth commissioning, what a good reviewer looks at, and what you should insist on getting.

When a review is worth it

• Before a big commitment: a new platform, a re-architecture, or a significant build with a supplier. Before you commit, changing the plan costs a meeting. Afterwards, it can cost a rewrite.
• When something feels wrong: the system is slow, expensive or fragile, and nobody can quite say why. That calls for a look at the whole system, not one part: the cause often sits between teams or layers that each look fine on their own.
• When you need a second opinion: on a supplier’s work, on a plan, or on an internal debate that has stalled.

Whether it’s worth it depends on whether anyone will act on the result. If your team already knows the problem and the fix, and only needs time, give them the time. A small system with a clear problem needs fixing, not reviewing.

What a good reviewer looks at

The diagrams show what someone intended to build; the system is what was actually built. A good reviewer looks at the architecture and everything that decides whether it works in practice: the code, the data model (how the data is structured and stored, and how the pieces relate), the delivery pipeline (the automated route a change takes from a developer’s machine to production), how the system is run and monitored, and what it costs.

Some reviews come before anything is built. For a wholly new system there’s no code or outage history yet, so I work from what does exist: the design against its requirements, the draft data model, how it will be deployed and run, its expected cost, the systems it has to fit with, and the people who will build and run it. A re-architecture is different, because there’s a current system behind it, and that system is the best evidence of whether the new design fixes the real problems.

Wherever there’s an existing system, these are some of the things I look for:

• Code: whether it matches the design, and which parts change most often and hurt most when they do.
• Data model: whether it fits how the data is used, and which rules the database enforces and which are only enforced by the code.
• Delivery pipeline: how long a change takes to reach production, how often a deployment fails, and whether anyone has practised rolling one back (undoing a bad deployment).
• Running it: what’s monitored, who gets woken up, and what the last outage taught the team.
• Cost: what it costs and who sees the bill. I’ve written separately about where cloud bills actually go.

For example, imagine a diagram showing two services connected only by a queue (a place where one service leaves messages for another to pick up later). That suggests they’re independent and can be changed separately. Then the code shows the second service also reads the first one’s database tables directly. A change to those tables can now break the second service, whatever the diagram says.

And I talk to the people who build and run the system, not only the people who drew the diagrams. They know where it hurts, which parts nobody dares change, and which workarounds are holding things together. Their view deserves to be taken seriously, and a review that backs it up gives it weight with the people who pay for the fix.

What you should get

A clear written report, with findings ranked by impact and effort, and a short walkthrough of it with your team.

The ranking is the most useful part. High impact and low effort goes first. High impact and high effort becomes a plan. Low impact and high effort is usually best left alone. Low impact and low effort can wait until someone is working in that part of the system anyway. Twenty unranked findings tend to get the easiest ones done, not the important ones.

The report should tell you what to do first, what to leave alone, and what to stop doing. Some odd-looking parts work perfectly well, and changing them is risk for no benefit: the “wrong” answer is sometimes fine. And most systems that are slow, expensive or fragile got that way by adding things, so often the most valuable change is taking something away.

You should get a recommendation, not a slide deck of options. A menu of options hands the decision back to the person who commissioned the review, and that decision is often the reason they commissioned it. A reviewer should say what they would do and why, which alternatives they rejected and why, and what would change their mind. The recommendation should also say what it assumed about things a reviewer may not fully know, such as budget, deadlines and hiring plans.

The walkthrough is where the team can challenge the findings. If they can show a finding is wrong, it should be withdrawn.

Why independence matters

An outside reviewer can say things an insider can’t. They have no stake in past decisions, they don’t report to whoever chose the current design, and they aren’t marking their own homework. They can say “that was a reasonable decision at the time, and it isn’t now” without it becoming a career risk.

That matters most when you’re assessing a supplier’s work, when a decision is going to the board, or when a debate has stalled. It matters less when the team agrees and wants an extra pair of eyes. A senior engineer from another team can often do that.

At Thames Water, I was hired for a week as an independent expert to assess the architecture, development methodology and code quality of a system being built by a third-party supplier. My improvement plan helped the supplier release more often, with fewer errors.

What you want from a review of a supplier’s work is a plan the supplier can act on, not only a verdict. And if a reviewer might be hired for the follow-on work, they should say so up front, and their recommendation should stand on its evidence.

How long it takes

It depends on the size of the system, but a review is usually measured in days rather than weeks. It also depends on how many systems are involved, how quickly the reviewer can reach the code and the people, and how much is written down. One focused decision takes less time than “review everything”.

That also makes it a low-commitment way to start working with someone: a short piece of work with a clear result.

Questions to ask before you commission one

• Will you look at the real thing, or only the documents? For an existing system, the code and the running system; for a new design, the requirements, the constraints and the people who will build and run it.
• Who will you talk to? The answer should include the people who build and run it.
• Will the findings be ranked, and by what?
• Will you tell us what to leave alone, and what to stop doing?
• Will we get a recommendation, or a list of options?
• Will you walk the team through it, and what happens if they disagree?
• Do you have a stake in the outcome, such as follow-on work or a product to sell?

Certifications help. I’m TOGAF 9.1 certified and a Microsoft Certified Azure Solutions Architect Expert. But the answers to these questions will tell you more about whether a review will be useful.

If you have a big decision coming up, or a system that feels wrong, read more about my architecture reviews, or get in touch.