Architecture review report
Used in the playbook Architecture review.
Download architecture-review-report.md — the source, as in the repository.
How to use
The template's own instructions:
Playbook arch.architecture-review. Use it to write up the findings of an architecture review once its scope (architecture-review-scope.md) is agreed. Section numbers are referenced from the playbook's stages, so keep them. A section that does not apply says so in one line ("Not in scope: the question asks for no change"). Never paste secrets or personal data (R11): name the type and the location only.
Fields
Front-matter fields and sections of the document the template creates. A section marked Optional in the template may be deleted from a copy; every other field and section stays (tools/check_artifacts.py checks this for the kinds it knows).
| Field or section | Where | Required |
|---|---|---|
title | front matter | required |
status | front matter | required |
version | front matter | required |
date | front matter | required |
owner | front matter | required |
review | front matter | required |
| 1. Summary for the decision owner | section | required |
| 2. Scope, method and limitations | section | required |
| 3. As-is architecture | section | required |
| 4. Components and dependencies | section | required |
| 5. Business goals and quality scenarios | section | required |
| 6. Analysis | section | required |
| 7. Decisions and ADRs | section | required |
| 8. Findings | section | required |
| 9. Risk themes | section | required |
| 10. Technical debt register | section | required |
| 11. Target architecture and migration roadmap | section | required |
| 12. Follow-up | section | required |
| Appendix A. Evidence index | section | required |
| Appendix B. Sign-off | section | required |
| Appendix C. Questions for the system experts | section | required |
Example
A filled-in copy for an invented product, templates/examples/architecture-review-report.md, in the Hub repository.It shows the level of detail to aim for, not text to reuse.
---title: Architecture review — Example shopstatus: draftversion: 0.1.0date: 2026-04-08owner: Alex Doereview: AR-2026-04-example-shop---
# Architecture review — Example shop
## 1. Summary for the decision owner
- **Question:** Can the shop be upgraded to the current platform version without a rebuild?- **Answer:** yes, if the runtime is upgraded first; the upgrade itself is blocked until then.- **Top risk themes:** an unsupported runtime blocks every upgrade (goal: keep taking card payments).- **Recommended next steps:** upgrade the runtime on staging, then the platform, then production.
| Severity | Critical | High | Medium | Low | Info ||---|---|---|---|---|---|| Findings | 0 | 2 | 1 | 0 | 0 |
## 2. Scope, method and limitations
- **Scope:** `architecture-review-scope.md`, agreed 2026-04-02; deviations: none.- **Ranking of scenarios:** agreed on 2026-04-03 (R5)- **Method:** lightweight architecture review per `arch.architecture-review`; timebox used: 3 of 3 days.- **Not examined:** the payment provider's side of the integration (R12)- **Missing access:** logs of the last month; they would have shown the real error rate.- **Assumptions:** the staging server matches production; confirmed by comparing package lists.
## 3. As-is architecture
### 3.1 System context
```mermaidflowchart LR U["Customer<br/>[Person]"] -->|orders| S["Example shop<br/>[Software system]"] S -->|takes payment| X["Payment service<br/>[Software system]"]```
### 3.2 Containers and deployment
One web container and one database on a single shared host; the web container runs PHP 7.4. Orders carry personal data andcross the boundary to the payment service.
### 3.3 Where documentation and evidence disagree
| Documented | Found | Evidence | Finding ||---|---|---|---|| ADR-0004: sessions in Redis | sessions in files on one host | E-02 | F-02 |
### 3.4 Claims register
| Claim | Document | Source checked | Result | Evidence | Finding ||---|---|---|---|---|---|| the shop has a staging site | the old handover note | hosting panel | confirmed | E-03 | — |
### 3.5 External interfaces and environment
| Interface or setting | Today | After the switch | Covered by | Evidence | Finding ||---|---|---|---|---|---|| notification address of the payment service | the old host | the new host | none | E-04 | F-03 |
## 4. Components and dependencies
| Component | State | Version | Origin | Licence | Support status | Known exploited vulnerabilities | Locally modified | Evidence ||---|---|---|---|---|---|---|---|---|| PHP | installed | 7.4.33 | distribution package | PHP-3.01 | ended 2022-11-28 | none found | no | E-01 |
**Dependency notes:** the payment extension needs PHP 7.4 and blocks the runtime upgrade.
## 5. Business goals and quality scenarios
**Business goals and constraints:** keep taking card payments; no downtime during the spring sale.
| Id | Attribute → refinement | Stimulus | Environment | Response | Response measure | Importance | Difficulty ||---|---|---|---|---|---|---|---|| S-01 | Reliability → recovery | the database server fails | opening hours | maintenance page, recovery | back within 30 min, no order lost | High | Medium |
## 6. Analysis
### S-01 — Recovery from a database failure
- **Approach that serves it:** nightly dump kept on the host- **Verdict:** at risk- **Risks:** F-01- **Non-risks:** the dump is complete and restores in 12 minutes- **Sensitivity points:** the dump lives on the same host as the database- **Trade-off points:** none
### Traceability
| Requirement | Acceptance criterion | Source of the requirement | Finding ||---|---|---|---|| FR-3 | AC-2 | client brief, clause 4 | — |
### Acceptance criteria that can be performed
| Criterion | Method | Environment | Expected result | Performed by | Can it be performed there | Finding ||---|---|---|---|---|---|---|| AC-5 | login with a test account | test site | session opens within 3 s | owner | yes | — |
## 7. Decisions and ADRs
| Decision found in the system | ADR | State | Finding ||---|---|---|---|| Platform: OpenCart 3.0 | none | gap | F-02 || Sessions in Redis | ADR-0004 | drift | F-02 |
## 8. Findings
| Id | Category | Severity | Element | Finding | Basis | Evidence | Check | Recommendation | Decision | Issue ||---|---|---|---|---|---|---|---|---|---|---|| F-01 | risk | High | database container | the only backup is on the database host | evidence | E-05 | — | copy the dump off the host | fix | #12 || F-02 | adr-gap | Medium | sessions | sessions are in files, not Redis | evidence | E-02 | — | record the real decision as an ADR | fix | #13 || F-03 | scope-gap | High | payment notifications | the new host would not receive payment notifications | assumption | E-04 | read the setting in the payment service's panel | list the address in the migration plan | fix | #14 |
## 9. Risk themes
| Theme | Threatens | Findings ||---|---|---|| Single host holds everything | goal: keep taking card payments; S-01 | F-01, F-03 |
## 10. Technical debt register
| Finding | Principal | Interest | Trigger to pay ||---|---|---|---|| F-02 | 1 day | every new developer asks where sessions live | before the platform upgrade |
## 11. Target architecture and migration roadmap
| Stage | Goal | Changes | Rollback | Exit criterion | Effort | Depends on ||---|---|---|---|---|---|---|| 1 | supported runtime | PHP 8.x on staging, then production | switch the PHP version back in the panel | S-01 passes on staging | 2 days | — |
## 12. Follow-up
- **Issues:** #12, #13, #14- **Retrospective ADRs drafted (status `proposed`):** none yet- **Accepted risks:** none- **Next review:** 2026-10-08
## Appendix A. Evidence index
| Id | What | Source | How obtained | Date ||---|---|---|---|---|| E-01 | package list | staging host | read | 2026-04-06 |
## Appendix B. Sign-off
| Role | Name | Date | Note ||---|---|---|---|| Reviewer | the lead agent | 2026-04-08 | || Independent reviewer | a separate agent session | 2026-04-08 | checked F-01, F-03 || Decision owner | Alex Doe | — | decisions to be recorded in §8 |
## Appendix C. Questions for the system experts
| Question | Addressee | Affects | Answer and date ||---|---|---|---|| which address receives the payment service's notifications? | the previous developer | F-03 | |Completion checks
A copy is complete when:
- every required field and section above is present, in the same order, and no bracketed placeholder is left;
- the exit criteria of its stage of the playbook Architecture review are met;
- the owner has approved it, where the playbook asks for approval. Only the owner sets
approved.
Source
templates/architecture-review-report.md, as in the repository. Placeholders are in square brackets; comments carry the instructions.
---title: Architecture review — [system]status: draft # draft | finalversion: 0.1.0date: YYYY-MM-DDowner: [decision owner]review: AR-YYYY-MM-[system]---
# Architecture review — [system]
<!-- Playbook arch.architecture-review. Use it to write up the findings of an architecture review once its scope(architecture-review-scope.md) is agreed. Section numbers are referenced from the playbook's stages, so keep them.A section that does not apply says so in one line ("Not in scope: the question asks for no change").Never paste secrets or personal data (R11): name the type and the location only. -->
## 1. Summary for the decision owner
<!-- Write this last, read first. Plain language; for a client, no jargon. At most one page. -->
- **Question:** [from the scope]- **Answer:** [yes / no / yes, if … — in one or two sentences]- **Top risk themes:** [two or three, each with the business goal it threatens]- **Recommended next steps:** [ordered]
| Severity | Critical | High | Medium | Low | Info ||---|---|---|---|---|---|| Findings | 0 | 0 | 0 | 0 | 0 |
## 2. Scope, method and limitations
- **Scope:** [link to the agreed scope, or the scope copied from the brief and marked "not confirmed by the decision owner" (R1)]; deviations: [none / what changed and why].- **Ranking of scenarios:** [agreed on YYYY-MM-DD / proposed, not agreed (R5)]- **Method:** lightweight architecture review per `arch.architecture-review`; timebox used: [n of m days].- **Not examined:** [parts, environments, attributes] (R12)- **Missing access:** [what, and what it would have changed]- **Assumptions:** [conclusions that rest on assumptions, with the check that would confirm each]
## 3. As-is architecture
<!-- Built from evidence, not from intended design (R3). Diagrams follow arch.c4-model: title, key, typedelements, labelled one-way relationships. Keep diagram sources as text next to this report. -->
### 3.1 System context
```mermaidflowchart LR %% System context diagram for [system] — replace; key: box = software system, person = user role U["[User role]<br/>[Person]"] -->|"[intent]"| S["[System]<br/>[Software system]"] S -->|"[intent]"| X["[External system]<br/>[Software system]"]```
### 3.2 Containers and deployment
[Container diagram; where each container runs (host, runtime version); data flows that carry personal data andthe trust boundaries they cross.]
### 3.3 Where documentation and evidence disagree
| Documented | Found | Evidence | Finding ||---|---|---|---|| [ADR-0004: sessions in Redis] | [sessions in files on one host] | E-12 | F-08 |
### 3.4 Claims register
<!-- Variant "documents of a design under construction" (R16). One row per claim of the documents that a decisiondepends on. Result: confirmed, contradicted, not verifiable (say what would settle it). Delete this section whenit does not apply. -->
| Claim | Document | Source checked | Result | Evidence | Finding ||---|---|---|---|---|---|| [the old payment notifications use one address] | [PRD §4] | [hosting panel, settings export] | [confirmed] | E-15 | — |
### 3.5 External interfaces and environment
<!-- Replacement, migration or rebuild (R18). The checklist is in templates/prd.md, section "External interfacesand environment". One row per interface or setting; "Covered by" names the requirement, criterion, or decisionthat deals with it, or "none" with a finding. Delete this section when it does not apply. -->
| Interface or setting | Today | After the switch | Covered by | Evidence | Finding ||---|---|---|---|---|---|| [notification address of the payment service] | [old host] | [new host] | [none] | E-18 | F-02 |
## 4. Components and dependencies
<!-- R4. Platform, runtime, frameworks, extensions, libraries, hosted services. Support status from endoflife.dateor the vendor; known exploited vulnerabilities from the CISA catalogue and vendor advisories. If a check cannot berun (no network access), write "not checked" in the row, list it in §2, and keep the row. -->
| Component | State | Version | Origin | Licence | Support status | Known exploited vulnerabilities | Locally modified | Evidence ||---|---|---|---|---|---|---|---|---|| [PHP] | [installed / planned / not confirmed] | [7.4.33] | [distribution package] | [PHP-3.01] | [ended 2022-11-28] | [none found / ids / not checked] | [no] | E-07 |
**Dependency notes:** [coupling hot spots, single points of failure, components that block upgrades of others]
## 5. Business goals and quality scenarios
<!-- R5. Utility tree: attribute (ISO/IEC 25010 vocabulary) → refinement → scenario. Five to fifteen scenarios.Importance and difficulty: High, Medium, Low; the decision owner agrees the ranking, or it is marked "proposed, notagreed" in §2 (R5). A response measure the requirements do not give is proposed here and marked "(proposed)". -->
**Business goals and constraints:** [from vision and requirements, or the client interview]
| Id | Attribute → refinement | Stimulus | Environment | Response | Response measure | Importance | Difficulty ||---|---|---|---|---|---|---|---|| S-01 | [Reliability → recovery] | [database server fails] | [opening hours] | [maintenance page, recovery] | [back within 30 min, no order lost] | High | Medium |
## 6. Analysis
<!-- One block per scenario ranked high on importance. Verdict: supported / at risk / not supported /unknown (with the check that would settle it). -->
### S-01 — [scenario title]
- **Approach that serves it:** [mechanism, element]- **Verdict:** [at risk]- **Risks:** [F-03]- **Non-risks:** [decisions that are sound — keep them]- **Sensitivity points:** [a property a response depends on strongly]- **Trade-off points:** [a property that helps one attribute and hurts another]
### Traceability
<!-- Variant "documents of a design under construction" (R16). Delete when it does not apply. -->
| Requirement | Acceptance criterion | Source of the requirement | Finding ||---|---|---|---|| [FR-3] | [AC-2] | [client brief, clause 4] | — |
### Acceptance criteria that can be performed
<!-- Variant "documents of a design under construction" (R16). One row per criterion. "Can it be performed there"is yes, no (finding) or unknown (the check that would settle it). -->
| Criterion | Method | Environment | Expected result | Performed by | Can it be performed there | Finding ||---|---|---|---|---|---|---|| [AC-5] | [login with a test account] | [test site] | [session opens within 3 s] | [owner] | [yes] | — |
## 7. Decisions and ADRs
<!-- R9. Significant decisions visible in the system, compared with the decision log. -->
| Decision found in the system | ADR | State | Finding ||---|---|---|---|| [Platform: OpenCart 3.0] | [none] | gap | F-10 || [Sessions in Redis] | [ADR-0004] | drift | F-08 || [Static site, no database] | [ADR-0002] | recorded | — |
## 8. Findings
<!-- R6–R8. Categories: risk, debt, adr-gap, non-conformance (cite the rule id, e.g. ops.backups#R6), inconsistency(documents contradict each other or the evidence, or a criterion cannot be performed where it says), scope-gap(something the goals depend on is missing from the documents), observation. Basis: evidence or assumption; for anassumption, Check names what would confirm it. Severity from the table in R7 (impact × likelihood of harm withinthe planning horizon; for a defect that certainly exists, say so in the finding). Decision (R15): fix, accept,defer, reject. Issue: link once created, or a roadmap row id when there is no tracker. -->
| Id | Category | Severity | Element | Finding | Basis | Evidence | Check | Recommendation | Decision | Issue ||---|---|---|---|---|---|---|---|---|---|---|| F-01 | [risk] | [High] | [container "Web shop"] | [one sentence] | [evidence] | [E-07] | [—] | [one sentence] | [fix] | [#123] || F-02 | [scope-gap] | [High] | [payment notifications] | [one sentence] | [assumption] | [E-18:6] | [read the setting in the payment service's panel] | [one sentence] | [fix] | [#124] |
## 9. Risk themes
<!-- R10. Group risks; each theme names the business goal or top scenario it threatens. -->
| Theme | Threatens | Findings ||---|---|---|| [Unsupported runtime blocks every upgrade] | [goal: keep taking card payments; S-02] | [F-01, F-05] |
## 10. Technical debt register
<!-- Findings of category debt. Principal: effort to remove. Interest: what it costs while it stays.Trigger: when it becomes worth paying. -->
| Finding | Principal | Interest | Trigger to pay ||---|---|---|---|| [F-06] | [3 days] | [every extension update needs manual merging, about 2 h each] | [before the platform upgrade] |
## 11. Target architecture and migration roadmap
<!-- Only when the question asks for change (R14). To-be Context and Container views, then stages; every stageships on its own and can be rolled back. -->
[To-be views]
| Stage | Goal | Changes | Rollback | Exit criterion | Effort | Depends on ||---|---|---|---|---|---|---|| 1 | [supported runtime] | [PHP 8.x on staging, then production] | [switch the PHP version back in the panel] | [all S-0x pass on staging] | [2 days] | — |
## 12. Follow-up
- **Issues:** [list, or a link to the issue query for label `architecture-review`]- **Retrospective ADRs drafted (status `proposed`):** [list]- **Accepted risks:** [finding, owner, reason, review date]- **Next review:** YYYY-MM-DD or [trigger]
## Appendix A. Evidence index
<!-- One id per file or output; cite a line as E-01:120. A number taken from a result file is recomputed fromthat file (R17). -->
| Id | What | Source | How obtained | Date ||---|---|---|---|---|| E-01 | [composer.lock] | [repository, commit abc1234] | [read] | YYYY-MM-DD |
## Appendix B. Sign-off
| Role | Name | Date | Note ||---|---|---|---|| Reviewer | | | || Independent reviewer | | | [checked F-…] || Decision owner | | | [decisions recorded in §8] |
## Appendix C. Questions for the system experts
<!-- What only the maintainers, the hosting provider or the client's staff can answer. One row per question. -->
| Question | Addressee | Affects | Answer and date ||---|---|---|---|| [which address receives the payment service's notifications?] | [client's developer] | [F-02] | |