§ CAPABILITY

Software Architecture Review

An independent read on how the system is put together, where it will bend under the growth you are planning for, and what preventing that bend costs.

Who
Founder holds the engineering leadership seat; the delivery team executes underneath it.
Request a call How the work runs

What you're seeing

The architecture diagram and the deployment do not match, and nobody is sure when they diverged.
Usually means The diagram describes intent from some point in the past. The gap between it and what is running is usually the first finding, and it is often larger than the team expects.
Every meaningful change requires three teams to coordinate.
Usually means Service boundaries do not follow the way work actually arrives. The coordination cost is being paid on every feature, and it is invisible because it looks like normal planning.
Two senior engineers want a rewrite and two do not, and the argument has been running for months.
Usually means Neither position has been costed. The argument is unresolvable in that form and will stay open until someone puts a range of engineering months against both paths.
The plan assumes ten times the current volume and nobody has checked what breaks first.
Usually means The design is being underwritten by a forecast it has never been tested against. What breaks is usually a specific, unglamorous thing — one table, one queue, one third-party rate limit — and it is findable in advance.

What a review is for

A system that works today and a system that supports next year’s plan are different claims, and most teams only have evidence for the first.

The evidence for the first is that nothing is on fire. The evidence for the second does not exist by default, because nothing in normal operation tests it — you find out whether the design holds at four times the volume by reaching four times the volume, which is the worst available moment to learn.

So the review loads the plan onto the design deliberately: the growth assumptions, the roadmap, the enterprise deal that brings a data residency requirement, the integration that turns a batch job into a synchronous dependency. Then it asks what breaks first, at what multiple, and what preventing it costs.

Read as built, not as drawn

The first artefact is a current-state picture that matches what is deployed.

This sounds like a formality and it is usually the first finding. Architecture documents describe intentions, recorded at the moment someone had time to write them down. What is running describes a sequence of decisions made under delivery pressure, each individually reasonable. The gap between them is not negligence — it is what happens to every system that ships — but it means every conversation held against the diagram has been held about a system that does not exist.

After that, two or three commercially important paths get traced end to end. A trace surfaces what a diagram cannot: the synchronous call added for one edge case, the retry policy that multiplies load exactly when the dependency is struggling, the timeout that is longer than the timeout in front of it.

Ranked, costed, and startable

The output is a ranked list where each item carries a range of engineering effort and a statement of what happens if it is left alone.

Two things follow from that format. It is possible to start — the first three items can begin this quarter, without waiting for a target architecture nobody has time to build. And it is possible to decide not to: an item with a cost and a consequence can be deliberately deferred, which is a legitimate answer and one an uncosted finding does not permit.

Where it sits

This capability appears under four parents, which is unusual and not accidental. It is part of Software Development when a build is large enough that the structure decides its cost, and part of Engineering Velocity when slow delivery turns out to be architectural rather than procedural. It is one of the four capabilities inside Technical Due Diligence, where the same reading is priced for a buyer, and it is part of the five-day Engineering Audit in a compressed form.

The nearest neighbour is Technical Debt Assessment, which inventories and prices what is already carried, where this asks whether the structure survives what is planned. The other is Database & Data Modeling — a surprising share of architectural constraints turn out to be data model constraints wearing a different name.

How the work runs

  1. Read the system as built

    Repositories, deployment topology and data stores, against whatever architecture document exists. The gap between the two is usually the first finding.

  2. Trace the paths that carry the business

    Two or three flows that matter commercially, followed end to end. Diagrams describe intent; a trace describes behaviour.

  3. Load the plan onto the design

    The roadmap and the growth assumptions applied to the current design, to find what breaks first and at what multiple.

  4. Rank and cost

    Findings ordered by what they cost and when they bite, each with a range of engineering effort and the consequence of leaving it.

What arrives

  • A written review with findings ranked by cost and urgency
  • Current-state diagrams that match what is deployed
  • Architecture decision records for the choices worth revisiting
  • A sequenced remediation list with effort ranges

What it costs your team

Around six hours from your senior engineers: one walkthrough session, one review of the draft, and answers to written questions in between.

Next step

Tell us where this is breaking and we'll say what it takes to fix.

Request a call

How we decide

  • The system is read as built before it is read as documented

    Costs It needs read access to repositories and the cloud console, which some organisations are slow to grant.

    Every architecture document describes an intention. What is deployed describes a history of decisions made under pressure, and the difference between the two is where the risk lives. Starting from the diagram means inheriting its blind spots.

  • Two or three business-critical paths are traced end to end

    Costs It goes deep on a few flows at the cost of surveying everything.

    A diagram shows what connects to what. A trace shows what actually happens on the path a customer pays for — including the synchronous call nobody remembered, the retry that amplifies load, and the timeout that is longer than the one in front of it. Breadth is available cheaply from the repository; depth on the paths that matter is not.

  • A rewrite has to be costed against the incremental path before it is recommended

    Costs It sometimes means arguing against what the strongest engineers in the room already want.

    Rewrites are the most expensive option available and they fail more often than they succeed, usually by running past the point where the business can wait. Recommending one is legitimate; recommending one without having costed the alternative is how a review becomes permission for a decision that had already been made.

Frequently Asked Questions

An independent assessment of how a system is structured, judged against what the business intends to do with it. It answers whether the design supports the plan, which parts will fail first and at what multiple, and what the alternatives cost in engineering months. It is a decision input rather than a quality score.
A code audit reads implementation quality — defects, patterns, test coverage. This reads structure: service boundaries, data ownership, coupling, failure modes, and whether they hold at the scale the plan assumes. Different altitude, different findings, and the structural ones are usually the expensive ones.
Almost never, and a review that arrives at a rewrite by default has not done its work. A rewrite earns a recommendation only when the incremental path has been costed and is genuinely worse, which is rarer than the engineering instinct suggests.
Read access to repositories and the cloud console. Production telemetry helps and is not essential. Where access cannot be granted, the report says what could not be verified rather than inferring around it — an inference presented as a finding is worse than an acknowledged gap.
Typically one to two weeks depending on the size of the estate. From your side it is around six hours of senior engineering time: one walkthrough, one review of the draft, and written answers in between. The rest happens against the repository without anyone sitting with us.

Sources

Page reviewed