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.[n1] 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.
Related¶
- Instantiates: Substrate Lineage Risk Audit — it produces the whole-substrate frame the narrower mechanisms operate within.
- Consumes: Dependency Tree Static Analysis supplies the resolved dependency and substrate map the review reasons over.
- Sibling mechanisms: Clean-Room Rebuild or Replatforming Pilot · Dependency Tree Static Analysis · Inherited Permission Review · Configuration Baseline Diff · End-of-Life and Maintainer Activity Check
Editorial Notes¶
Form Classification¶
Form family: Assessment, Review & Assurance
Rationale: Legacy Substrate Architecture Review operates as a bounded evaluation of existing evidence or work that produces a finding or disposition because it 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
Independent corroboration: The frozen evidence defines Legacy Substrate Architecture Review as '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', so its operative form is Assessment, Review & Assurance.
Review outcome: Independent reviewer agreement; high confidence.
Origin Attribution¶
Primary origin: Computer Science & Software Engineering
Origin pattern: Cross-disciplinary synthesis
Present-day reach: Multi-domain
Rationale: Software architecture developed expert whole-system reviews that recover true boundaries, coupling, and failure propagation in inherited platforms.
Related originating lineages:
- Engineering & Design — Systems and safety engineering materially shaped blast-radius and substrate-risk analysis.
Review resolution: Both independent reviews place the primary lineage in computer_science. The queued differences (domain_reach_disagreement) concern secondary metadata rather than primary provenance. The final retains engineering_design only where a reviewer supplied a formative-lineage rationale; downstream application by itself is not treated as origin. origin_mode=cross_disciplinary_synthesis records the relationship among origin traditions, while domain_reach=multi_domain records application breadth separately. encyclopedia_synthesis=true reflects whether either reviewer identified a corpus-specific synthesis, and confidence=high preserves the more cautious evidence assessment.
Encyclopedia synthesis: The exact catalogued form synthesizes established practice rather than reproducing a single standard historical label.
Review outcome: Reconciled after independent review; high confidence.
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.
[n1] "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. ↩