---
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] | |
