Skip to content

Legacy Substrate Architecture Review

Architecture review — instantiates Substrate Lineage Risk Audit

A structured human review of an inherited system's architecture — its real boundaries, coupling, and failure spread — to understand a legacy substrate as a whole before trusting anything built on it.

The automated tools in this archetype each inspect one facet of an inherited substrate; this mechanism reads the whole. Legacy Substrate Architecture Review is the expert, human pass over an inherited platform that answers the two questions the point tools assume already have answers: what actually is this substrate — where does it begin and end — and how far does a failure inside it spread? Its defining contribution is the frame: it draws the substrate's true boundary and models its blast radius, establishing the scope and failure geography that the narrower audits then operate within. It is sense-making over a legacy whole, grounded in what the system actually is rather than what its diagram claims.

Example

After acquiring a smaller company, a team inherits its order-management monolith — several hundred thousand lines, one shared database, sparse documentation, original authors gone. Before building the promised integrations on top of it, they run an architecture review of the inherited substrate. Reconstructing the real module boundaries from the code, they find the boundaries don't match the diagram at all; a single shared "core" table turns out to be written by nine different subsystems. Tracing failure paths, they establish that an outage in the billing module would cascade through that table into order intake and fulfillment — a blast radius far wider than anyone assumed. The review's output is not a fix. It is a bounded, honest picture of what the team is actually standing on.

How it works

  • Reconstruct the real structure. Derive the substrate's actual architecture from code and runtime evidence, not from the intended diagram.
  • Draw the boundary. Establish what genuinely constitutes this substrate versus its neighbors — where its edges truly lie.
  • Find the coupling. Identify chokepoints, shared state, and hidden couplings that concentrate structural risk.
  • Model the blast radius. Trace what fails if a given part fails, so the spread of a failure is understood before, not during, an incident.

Tuning parameters

  • Review depth — a diagram sanity-check versus a code-grounded reconstruction; deeper reveals where the diagram lies, at a cost of weeks.
  • Boundary strictness — how tightly you draw what counts as "this substrate"; a wide boundary reviews more but dilutes focus.
  • Blast-radius resolution — coarse (subsystem) versus fine (data and call paths); finer localizes risk but costs analysis.
  • Evidence base — interviews and documents versus static and runtime evidence; grounding in evidence resists the flattering story a team tells about its own system.
  • Reviewer independence — the inheriting team versus outside eyes; independence catches assumptions insiders can no longer see.

When it helps, and when it misleads

Its strength is that it is the only mechanism here that comprehends the substrate as a whole, so it sets the scope and blast-radius frame the finer audits depend on — and it is especially valuable on legacy systems whose real structure has drifted from any diagram.

Its weaknesses are cost and reviewer-dependence: it is slow, and a legacy substrate's structure may have eroded past clean description, so its boundary and blast-radius model are approximations.[1] The classic misuse is accepting the architecture as documented rather than reconstructing it, which launders the very assumptions the audit exists to test. The discipline is to ground the review in code and runtime evidence and to treat the diagram as a hypothesis to be checked, not a fact.

How it implements the components

Legacy Substrate Architecture Review fills the framing slice of the archetype — establishing the substrate's extent and how failure propagates through it:

  • substrate_scope_boundary — draws what actually constitutes this inherited substrate and where it ends.
  • substrate_blast_radius_model — models how far a failure inside the substrate propagates into what's built on it.

It frames the substrate but does not enumerate its dependency graph — that's Dependency Tree Static Analysis's — nor carry out any fix; replatforming is Clean-Room Rebuild or Replatforming Pilot's job, and the per-privilege access call is Inherited Permission Review's.

Notes

This review is usually the first mechanism run on an inherited substrate, because its scope boundary tells the narrower tools where to look. A sloppy boundary here caps the entire audit: a dependency scan, a permission review, and an end-of-life check are all only as complete as the substrate they're pointed at, and that substrate is defined here.

References

[1] "Big Ball of Mud," the anti-pattern named by Brian Foote and Joseph Yoder, describes a system whose architecture has eroded into ad-hoc, tangled structure through years of expedient change. Inherited legacy substrates are its natural habitat, and it is exactly why blast radius must be reconstructed from the code rather than read off a diagram that no longer holds. ↩