Skip to content

Draft — not approved. A working draft by UASK. It may change without notice.

Status: review · Version 0.1.0

Architecture review

Summary

An architecture review answers one question about a system — “can we build the next release on it?”, “can this site be upgraded?”, “is this blueprint ready to approve?” — with evidence instead of opinion. The reviewer agrees the scope with the person who decides, describes the architecture as it really is, states the quality goals as measurable scenarios, analyses how the architecture meets them, and turns what is found into graded findings that each end as a decision and, where needed, a tracked issue. It is a lightweight form of the SEI’s Architecture Tradeoff Analysis Method (ATAM), sized for one system and a few days of work.

Rules

  • R1. A review MUST start from a written scope agreed with the decision owner (templates/architecture-review-scope.md): the system and its boundary, the question the review answers and the decision it informs, the variant (own product, inherited system, proposed design), inputs and access, exclusions, timebox, planning horizon and the recipients of the report.

  • R2. A review MUST NOT change the code, configuration or data of a system in use. Analysis MUST run on copies or through read-only access; active testing (vulnerability scans, load or penetration tests) MUST have the system owner’s written permission and an agreed time window.

  • R3. The review MUST describe the architecture as it is (for a proposed design: as proposed), with at least a System Context diagram and, for a system of more than one deployable unit, a Container diagram (arch.c4-model#R1, arch.c4-model#R2), built from evidence — repository, deployed configuration, hosting — not from intended design alone. Where documentation and evidence disagree, the review MUST show the evidence and record the difference as a finding.

  • R4. The review MUST inventory the third-party parts the system depends on or will depend on — platform, runtime, frameworks, extensions, libraries, hosted services — with version, origin, licence and support status, and MUST check them against known exploited vulnerabilities and end-of-life dates. For an inherited system it MUST also identify local modifications to vendor code.

  • R5. Quality goals MUST be stated as concrete scenarios — stimulus, environment, response and a measurable response measure — and MUST be ranked by importance to the business and by difficulty before the architecture is analysed. Every scenario ranked high on importance MUST be analysed.

  • R6. Every finding MUST have an id, a category (risk, debt, adr-gap, non-conformance, observation), the affected element (a C4 element or a decision), evidence (file and line, command and output, measurement or document, by evidence id), a severity under R7 and a recommendation. A conclusion without evidence MUST be marked as an assumption, together with the check that would confirm it.

  • R7. Severity MUST be set from the impact on the business goals in scope and the likelihood within the planning horizon, using the table below — not from the effort to fix or the reviewer’s preference. Info MUST be used only for observations and non-risks that carry no harm.

    Likelihood within the horizon ↓ · Impact → High Medium Low
    Happening now, or expected Critical High Medium
    Plausible High Medium Low
    Unlikely Medium Low Low

    Impact is High for loss or corruption of data, a security or legal breach, an outage of a core function, or when the decision under review cannot be made safely; Medium when a top-ranked scenario misses its response measure or the cost of change grows with every change; Low for a local, recoverable inconvenience.

  • R8. A finding rated Critical MUST be reported to the decision owner as soon as it is confirmed, with an immediate mitigation, and MUST NOT be held back for the final report.

  • R9. The review MUST list the significant decisions it finds in the system (in the sense of arch.adr#R1) and compare them with the decision log. A decision without a record (gap) or a record that no longer matches the system (drift) MUST be recorded as a finding of category adr-gap. Recovered decisions SHOULD be written up as retrospective ADRs with status proposed.

  • R10. Risks MUST be grouped into risk themes, each naming the business goal or top scenario it threatens. Sensitivity points and trade-off points found during the analysis SHOULD be recorded even when they are not risks.

  • R11. Credentials, keys, tokens and personal data found during the review MUST NOT be copied into the report, issues, logs or chat; the report states only their type and location. An exposed secret MUST be a finding of at least High severity.

  • R12. The report MUST state what was not examined, which access was missing and which conclusions rest on assumptions, and MUST NOT claim more than the evidence supports — such as “secure”, “compliant” or “scalable” without the scenario and measurement behind the word.

  • R13. When the reviewer reviews their own design or code, Critical and High findings — and a conclusion that there are none — SHOULD be re-checked by an independent reviewer who receives the evidence, not the conclusions.

  • R14. When the review recommends structural change, the report MUST include a target (to-be) view and a staged migration roadmap in which every stage leaves the system working and can be rolled back. A full rewrite SHOULD be recommended only with evidence that staged change is not viable.

  • R15. The decision owner MUST decide on each finding of severity Medium or higher: fix, accept the risk, defer or reject. A finding to fix or defer MUST become a tracked issue that links back to the finding id; an accepted risk MUST be recorded with an owner, a reason and a review date.

Stages

Each stage lists what has to be true before it starts (entry), what is done, what it produces (outputs) and what has to be true when it ends (exit). Sections named “report §n” are in templates/architecture-review-report.md.

1. Intake and scope

  • Entry. A request that names a system and a question.
  • Do. Identify the decision owner and the decision the review informs; choose the variant; list the inputs and the read-only access needed; set the timebox and the planning horizon (default: until the next MAJOR release or six months). For an inherited system, get written authorisation, and agree how copies of files and database are taken without touching the live system (R2).
  • Outputs. The filled templates/architecture-review-scope.md.
  • Exit. The decision owner has agreed the scope (R1); access works.

2. Evidence

  • Entry. Agreed scope.
  • Do. Collect the repository and its history, decision records, blueprint, CI configuration, deployment and hosting configuration, runtime versions, logs and metrics, the issue tracker, and written answers from the system experts. For an inherited system add the file tree, a database copy, the list of installed extensions with their sources, scheduled jobs, and the hosting or control-panel versions. Give each piece an evidence id (E-01) with where and when it was obtained.
  • Outputs. Evidence index (report appendix A).
  • Exit. The evidence index covers every element in scope; missing access is listed as a limitation (R12).

3. As-is architecture and dependencies

  • Entry. Evidence index.
  • Do. Draw the System Context and Container views (R3) from the evidence, add where each container runs, and mark data flows that carry personal data and the trust boundaries they cross. Build the component inventory (R4): use package manifests and lock files, the platform’s extension list, endoflife.date for support status and the CISA catalogue for known exploited vulnerabilities; for an inherited system, compare its vendor code with a pristine copy of the same release. Note coupling hot spots and single points of failure.
  • Outputs. Report §3 (as-is architecture) and §4 (components and dependencies).
  • Exit. A system expert, or the deployed configuration itself, has confirmed the views; the inventory is complete for the scope.

4. Quality goals and scenarios

  • Entry. As-is views.
  • Do. Write down the business goals and constraints — from the vision and requirements, or from the client interview. Build a utility tree: quality attribute (the ISO/IEC 25010 vocabulary — for example performance efficiency, reliability, security, maintainability, flexibility) → refinement → scenarios (R5). Five to fifteen scenarios are enough for a lightweight review. Rank each by importance and difficulty (high, medium, low).
  • Outputs. Report §5 (goals and scenarios).
  • Exit. The decision owner has agreed the ranking.

5. Analysis

  • Entry. Ranked scenarios.
  • Do. For each scenario ranked high on importance, trace it through the views: which architectural approach or mechanism serves it, and what would make it fail. Record risks, non-risks, sensitivity points and trade-off points. Compare the decisions visible in the system with the decision log (R9). Check against the Hub items and standards that apply, citing rule ids: core items for every system; HIF for user interfaces (hif.evaluation, and hif.web-audit-playbook for websites); SCF for operating systems (scf.evaluation, scf.constitution). Measure where measuring is cheap — a page timing, a restore of last night’s backup into a copy (ops.backups#R6) — rather than estimate.
  • Outputs. Report §6 (analysis) and §7 (decisions and ADRs).
  • Exit. Every analysed scenario has a verdict: supported, at risk, not supported, or unknown with the check that would settle it.

6. Findings

  • Entry. Analysis complete.
  • Do. Turn what was found into findings (R6), grade them (R7), and group risks into themes (R10). Report a Critical finding at once (R8). For technical debt, estimate the principal (effort to remove it) and the interest (what it costs each change or each month while it stays). Write a recommendation per finding. Have Critical and High findings re-checked where R13 applies.
  • Outputs. Report §8 (findings), §9 (risk themes) and §10 (technical debt register).
  • Exit. Every finding has evidence and a severity; Critical and High findings have been checked.

7. Target and roadmap

Only when the question asks for change.

  • Entry. Findings.
  • Do. Draw the to-be Context and Container views and a staged migration roadmap (R14): each stage with its goal, changes, rollback, exit criterion, rough effort and dependencies. Prefer replacing parts behind a stable interface, one at a time, over a big-bang switch.
  • Outputs. Report §11 (target architecture and migration roadmap).
  • Exit. Every stage can be released and rolled back on its own.

8. Report and decisions

  • Entry. Draft report.
  • Do. Write the summary for the decision owner first: the answer to the question, the top risk themes, the recommended next steps, the count of findings per severity — for a client in plain language. Walk the decision owner through it and record a decision per finding (R15).
  • Outputs. The report with status final.
  • Exit. Every finding of severity Medium or higher has a decision.

9. Follow-up

  • Entry. Final report.
  • Do. Open an issue per finding to fix or defer, titled [<review id> F-07] <finding title> and labelled architecture-review, linking back to the finding; draft the retrospective ADRs (R9); record accepted risks; set the date of the next review. For a client system, feed the roadmap into the estimate and the delivery plan.
  • Outputs. Issues, ADR drafts, the accepted-risk entries and the re-review date (report §12).
  • Exit. Every Medium or higher finding has an issue or a recorded acceptance; the report is linked from the project’s documentation.

Guidance

When to use

Own product Inherited system (for example a client site) Proposed design
Trigger before a MAJOR release or a hard-to-reverse change; when change gets slow; yearly before taking over support, or quoting an upgrade or rebuild before the owner accepts a blueprint or a significant ADR
Typical inputs repository, ADRs, blueprint, CI, issues, metrics copy of files and database, hosting panel, list of extensions, interview with the client vision, requirements, blueprint, ADRs with status proposed
Emphasis drift from blueprint and ADRs; technical debt; top scenarios provenance and modified vendor code; end-of-life components; security exposure; backups; upgrade path scenario coverage; unresolved decisions; risks before anything is built
Report read by owner, team and agents the client (plain-language summary) and the delivery team the owner

Do not run a full review for a local, reversible choice — a code review or an ADR discussion is enough.

Roles

Role Typical holder in a UASK project Responsibility
Decision owner Product Owner, or the client for a client system agrees the scope, ranks the scenarios, decides on every finding
Reviewer Lead Developer (an agent) or an architect gathers evidence, writes the views, analysis and report
Independent reviewer Technical Lead, another person, or a separate agent session re-checks Critical and High findings from the evidence alone
System experts maintainers, hosting provider, client staff answer questions and confirm the as-is views

One person may hold several roles, except that the reviewer is never the only check on their own design (R13).

Tailoring

  • Proportional effort. A lightweight review of one system takes one to three days and involves the decision owner at two points: the scope and the scenario ranking. Run the full ATAM — nine steps with stakeholder workshops — only when a major, hard-to-reverse decision depends on the result.
  • Inherited client sites. Assume nothing is documented: the as-is views are often the first architecture description the client has ever had. The usual weak points are an unsupported runtime or platform version, extensions without a maintainer or from unofficial sources, edited vendor files that block upgrades, credentials kept in the web root, no tested restore, and personal data without a known retention period. Do not raise one adr-gap finding per undocumented decision; raise one finding for the missing decision log and write retrospective ADRs only for decisions that constrain the next step.
  • Own products. The best evidence is already in the repository: ADRs, CI runs, issues, release history. Look for drift — decisions that the code no longer follows — and for scenarios the roadmap depends on that nothing measures.
  • Proposed designs. There is no running system, so the as-is views are the proposed ones and most findings are risk or adr-gap. Run the review before the owner’s approval gate, while changing the design is still cheap.

Working with agents

  • Agents as reviewers. An agent can collect evidence, draw the views and draft findings quickly; the decision owner still agrees the scope, ranks the scenarios and decides on findings. Give an independent agent the evidence index and the scenarios, not the draft findings, so its read is not anchored on yours.
  • Scanner output. A tool warning becomes a finding only after it is verified, de-duplicated and placed on an element. A raw scanner dump is evidence for the appendix, not a list of findings.

Reporting and re-review

  • Talking about severity. Explain each Critical and High finding by its business effect (“orders placed during a database failover are lost”), not by its technical name.
  • Re-review. Re-run the review before the next MAJOR release, after a structural change, or at the date set in stage 9; check closed findings with new evidence, not with the issue status.

Anti-patterns

  • Opinion review — “I would have used X” with no scenario and no evidence behind it.
  • Boiling the ocean — every part of the system reviewed with equal depth instead of the top-ranked scenarios.
  • Diagram from memory — drawing the intended architecture instead of the deployed one.
  • Everything is High — severity set by the reviewer’s taste or by the effort to fix, so it no longer ranks anything.
  • Fixing while reviewing — changing the live system during the review, which mixes roles, destroys evidence and adds risk.
  • Report as the end — findings with no decision, no owner and no issue, forgotten within a month.
  • Secrets in the report — pasting a found password or key “as proof”.
  • Big-bang rewrite — recommending a full rewrite without showing why staged change cannot work.
  • Re-arguing accepted decisions — reopening an accepted ADR without new forces or new evidence; that is a new ADR’s job, not a finding.

Explanation

Architecture is the set of decisions that are expensive to change, so the cheapest moment to find a weak one is before the next decision is built on top of it. A review that only reads code finds code problems; a review that starts from the business goals finds the architectural ones — the places where the structure cannot deliver what the business needs.

The SEI’s ATAM (2000) made this repeatable: present the business drivers, elicit quality-attribute scenarios in a utility tree, analyse the architectural approaches against the highest-priority scenarios, and report risks, non-risks, sensitivity points, trade-off points and risk themes. A full ATAM needs several days and a room of stakeholders. This playbook keeps its chain of reasoning — goals, scenarios, approaches, risks — and drops the workshops, which is what small teams and agent-assisted reviews can sustain. ISO/IEC/IEEE 42030 is the international standard for architecture evaluation frameworks; this playbook is one small, practical instance of such an evaluation.

Severity follows the usual risk-assessment practice described in NIST SP 800-30: combine the likelihood of an event with the size of its impact, on a small qualitative scale that people can apply consistently. Grading by impact and likelihood rather than by effort keeps cheap-to-fix but dangerous problems at the top.

Technical debt is Ward Cunningham’s 1992 metaphor: shipping code that is not quite right is like borrowing — it speeds delivery, but every change pays interest until the debt is repaid. Recording principal and interest per debt item turns “the code is messy” into a number the decision owner can weigh against new features.

Staged migration follows the strangler-fig pattern described by Martin Fowler: replace the old system part by part behind a stable boundary, so that every step ships and can be undone, instead of betting on one big switch.

Examples

A quality-attribute scenario — good, then bad:

S-03 Reliability importance: High difficulty: Medium
Stimulus: the database server fails
Environment: opening hours, normal load
Response: the shop stops taking orders, shows a maintenance page, recovers
Response measure: back within 30 minutes; no confirmed order lost
S-03 Reliability The system is highly available.

A finding — good, then bad:

F-04 risk High element: container "Web shop" (PHP runtime)
Evidence: E-07 — `php -v` on the host prints 7.4.33; PHP 7.4 security support
ended on 2022-11-28 (endoflife.date).
E-09 — the vendor of the payment extension requires PHP 8.1 for current releases.
Recommendation: upgrade the runtime in stage 1 of the roadmap; blocks F-05.
F-04 risk High element: —
Finding: code quality is poor. Recommendation: rewrite.

The bad scenario cannot be tested; the bad finding names no element, cites no evidence and cannot be checked or turned into an issue.

Sources