Skip to content

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 sectionWhereRequired
titlefront matterrequired
statusfront matterrequired
versionfront matterrequired
datefront matterrequired
ownerfront matterrequired
reviewfront matterrequired
1. Summary for the decision ownersectionrequired
2. Scope, method and limitationssectionrequired
3. As-is architecturesectionrequired
4. Components and dependenciessectionrequired
5. Business goals and quality scenariossectionrequired
6. Analysissectionrequired
7. Decisions and ADRssectionrequired
8. Findingssectionrequired
9. Risk themessectionrequired
10. Technical debt registersectionrequired
11. Target architecture and migration roadmapsectionrequired
12. Follow-upsectionrequired
Appendix A. Evidence indexsectionrequired
Appendix B. Sign-offsectionrequired
Appendix C. Questions for the system expertssectionrequired

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.

example-architecture-review-report.md
---
title: Architecture review — Example shop
status: draft
version: 0.1.0
date: 2026-04-08
owner: Alex Doe
review: 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
```mermaid
flowchart 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 and
cross 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.

architecture-review-report.md
---
title: Architecture review — [system]
status: draft # draft | final
version: 0.1.0
date: YYYY-MM-DD
owner: [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, typed
elements, labelled one-way relationships. Keep diagram sources as text next to this report. -->
### 3.1 System context
```mermaid
flowchart 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 and
the 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 decision
depends on. Result: confirmed, contradicted, not verifiable (say what would settle it). Delete this section when
it 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 interfaces
and environment". One row per interface or setting; "Covered by" names the requirement, criterion, or decision
that 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.date
or the vendor; known exploited vulnerabilities from the CISA catalogue and vendor advisories. If a check cannot be
run (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, not
agreed" 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 an
assumption, Check names what would confirm it. Severity from the table in R7 (impact × likelihood of harm within
the 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 stage
ships 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 from
that 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] | |