E6 ยท Publication Volume 28

Architecture Review

trade-offs, technical debt, migration and deprecation

*trade-offs, technical debt, migration and deprecation*

Architecture viewpoints converging through evidence gates to migration, release or reconsideration
Architecture viewpoints converging through evidence gates to migration, release or reconsideration

Learning objectives

This lesson is general and institution-neutral. It uses no real company, individual, property, project or identifiable place. Generic roles describe responsibilities only, and SYN-ARCH identifiers denote explicitly synthetic teaching evidence.

  • Frame the decision governed by trade-offs, technical debt, migration and deprecation.
  • Model the relevant boundaries, states and contracts before selecting an implementation.
  • Define measurable invariants, failure evidence and a safe release consequence.
  • Produce a complete architecture review package with decisions, migration gates and unresolved risks from synthetic evidence and defend its trade-offs.

Decision boundary

An architecture review decides whether a proposed system can support declared decisions and risks with credible evidence, not whether a diagram looks complete. Review through stakeholder concerns and separate viewpoints: context, information, functional responsibilities, concurrency, deployment, security, operations and evolution. For each important choice, compare viable alternatives against quality scenarios, professional boundaries, constraints and uncertainty. Accept, accept with conditions, return for evidence or reject. Unresolved risk, technical debt and non-goals remain visible; approval does not convert assumptions into facts.

Core concepts

A concern is a question important to a stakeholder role; a viewpoint defines how evidence for that concern is organized; a view is the resulting representation. An architecture decision record captures context, options, evidence, decision, consequences, status and reconsideration triggers. Technical debt is a known future constraint or cost created by a choice, not a vague label for disliked code. Migration changes a running evidence system through bounded states and compatibility gates. Deprecation is a contract with consumers: replacement, warning, observation, evidence-retention path and removal condition.

System model and contracts

The review package contains scope and non-goals, stakeholder-role map, requirements and risk trace, viewpoint catalogue, system and data boundaries, contracts, provenance and version policy, permission model, performance budget, test portfolio, telemetry and recovery plan, decision records, debt register, migration plan, deprecation plan and unresolved findings. A decision matrix records criteria, evidence units, uncertainty and consequences without hiding judgement behind an unexplained total score. Dependencies show which contracts, data, tests, operations and consumers are affected by each migration step.

Invariants and acceptance criteria

| Invariant | Test evidence | Release consequence | |---|---|---| | Every architecture claim traces to a concern, evidence and review disposition. | contract test and recorded counterexample | block publication | | Alternatives are compared against the same declared decision criteria. | replay comparison and digest check | quarantine the artefact | | Approval signs one immutable architecture and evidence baseline. | role-based acceptance trace | return the decision unresolved | | Migration preserves identity, history and a tested safe-stop boundary. | failure injection and recovery record | retain the last verified version | | Technical debt and unresolved risk remain visible until evidenced closure. | domain review against declared evidence | record an explicit review finding |

Quantitative engineering

Trace completeness is measured for applicable concerns, requirements, risks, controls and tests, but ratios are accompanied by missing high-consequence items. A decision matrix may normalize measurements only when scales and direction are declared; weights express review judgement and receive sensitivity analysis. Migration measures include converted and verified population, reconciliation difference, dual-read or dual-write discrepancy, rollback readiness, deprecated-use cohort and unresolved exceptions. Quality scenarios keep their own units and thresholds. One composite score cannot erase a failed safety, integrity or professional-boundary gate.

Data quality, evidence and uncertainty

Review evidence is versioned and inspectable: representative workloads, contracts, manifests, diagrams, threat and failure scenarios, benchmarks, test results, recovery exercises, consumer inventory and domain findings. Claims distinguish measured, observed, derived, assumed and unknown. Alternative analysis uses the same decision criteria rather than giving the preferred option richer evidence. A proof of concept tests selected uncertainty and is labelled accordingly; it does not establish scale, security, recoverability or organisational fit unless those conditions were actually exercised.

Interoperability and versioning

Each review item has stable identity, concern, evidence links, finding, severity or consequence, disposition, responsible role, due condition and closure evidence. Decision records and view definitions are versioned with the architecture baseline. Migration contracts define source and target identity, mapping, compatibility window, validation, reconciliation, cutover, rollback boundary and retained history. Deprecation notices identify exact contract versions and measurable removal gates. Approval signs one immutable review package; later change requires impact analysis and a new or amended decision record.

Security and professional responsibility

Review access is bounded because diagrams, failure scenarios and migration paths may reveal protected structure. Publish a redacted view where broader communication is needed, while authorised reviewers retain exact evidence. No reviewer approves a control they alone designed, implemented and tested when consequence requires separation. Migration identities receive temporary least privilege and expire after verification. Compatibility bridges are treated as additional attack and failure surfaces. Archived review evidence is integrity protected and retention follows the affected scientific and operational record.

Operational workflow and observability

Architecture review continues after approval through decision triggers and operating evidence. Trigger review when a contract, data scale, reference model, threat, professional boundary, quality objective, dependency or consumer changes materially. Migration proceeds through rehearsed stages with entry and exit evidence, monitored cohorts, reconciliation and a tested stop condition. Deprecated use is measured by consumer and decision consequence. Close debt only when the constraint and acceptance evidence are resolved, not when the register entry becomes inconvenient. Periodic review removes stale assumptions while preserving historical rationale.

Integration checkpoint

Connect the architecture review artefact to the preceding volume architecture. Trace one synthetic object from source identity through the new boundary to a reviewed output, then trace one rejection or failure back to the earliest violated invariant. Update the architecture decision record with the chosen option, alternatives, assumptions, evidence, consequences, owner role, review state and triggers for reconsideration. A checkpoint passes only when another reviewer can reconstruct both the successful path and the blocked path without oral explanation.

Synthetic worked example

SYN-ARCH-13 proposes replacing one storage and delivery path because a prototype loads faster. The review finds that the prototype omits historical versions, restricted extents, restore evidence and two consumer contracts. Alternatives are compared against the same correctness, performance, security, recovery and migration criteria. The selected path uses immutable target packages, dual-read comparison, a bounded compatibility adapter, cohort monitoring and a rollback point before alias movement. Approval is conditional on reconciliation, recovery rehearsal and domain review; unresolved numerical tolerance remains an explicit risk rather than a hidden assumption.

Practice and assessment

  1. Which concerns and viewpoints are necessary for the declared decisions?
  2. What evidence supports each option, trade-off and unresolved risk?
  3. Which migration gates prove identity, compatibility and recovery?
  4. What operating change will trigger reconsideration of this decision?

Assessed artefact: a complete architecture review package with decisions, migration gates and unresolved risks. Submit the artefact with its source manifest, acceptance evidence, unresolved risks and a short explanation of why one plausible alternative was not selected.

Common failure modes

  • Reviewing component fashion instead of decisions, concerns and evidence.
  • Giving the preferred option stronger evidence than its alternatives.
  • Using a composite score to hide a failed high-consequence gate.
  • Migrating in place without reconciliation and a safe stop condition.
  • Removing a contract while dependent evidence and consumers still require it.

Sources and further reading