Architecture Review Checklist (ADR Template)
Purpose
Use this checklist for every architecture change proposal to enforce 02-island-boundaries-and-performance.md and prevent service/package sprawl.
How To Use
- Copy this file into a dated ADR file, for example
docs/migration/adr/ADR-2026-02-07-example.md.
- Fill every field with
Pass, Partial, or Fail.
- Attach evidence (doc sections, diagrams, API contracts, benchmarks).
- Do not approve implementation until all mandatory gates pass.
| Field |
Value |
| ADR ID |
|
| Date |
|
Status (Proposed/Accepted/Rejected/Superseded) |
|
| Author(s) |
|
| Reviewer(s) |
|
| Related Ticket(s) |
|
| Affected Island(s) |
|
| Related Docs |
|
Change Summary
| Item |
Value |
| Decision statement |
|
| Problem being solved |
|
| Option selected |
|
| Rejected options |
|
| Rollout scope |
|
Gate A: Deployable Boundary (Mandatory)
| Check |
Result |
Evidence |
Notes |
| Total Day 1 deployables remain <= 5 |
|
|
|
| If adding a new app, at least 2 split criteria are met (security boundary, scaling profile, release cadence, data ownership) |
|
|
|
| If criteria are not met, change stays inside existing island |
|
|
|
Gate B: Package Extraction (Mandatory)
| Check |
Result |
Evidence |
Notes |
| Internal shared package count remains <= 3 |
|
|
|
| New package is reused by at least 2 islands |
|
|
|
| New package API is expected stable for >= 6 months |
|
|
|
| Package does not contain app-specific ORM entities/workflows |
|
|
|
No shared mutable domain bundle is introduced (Article, Order, Vehicle, etc.) |
|
|
|
Gate C: Data Ownership And Contracts (Mandatory)
| Check |
Result |
Evidence |
Notes |
| Each island owns its schema and migrations |
|
|
|
| No cross-island direct DB queries/writes |
|
|
|
| Sync API contracts are documented for low-latency reads |
|
|
|
| Async contracts are documented for write propagation |
|
|
|
| Outbox/inbox and idempotency design is defined |
|
|
|
| Check |
Result |
Evidence |
Notes |
| Read model/projection strategy exists for impacted high-volume paths |
|
|
|
| Stock availability path has explicit p95 target |
|
|
|
| Vehicle fitment path has explicit p95 target |
|
|
|
| Wheel-set composition path has explicit p95 target |
|
|
|
| Capacity plan for peak import/export windows is documented |
|
|
|
Gate E: Operability And Resilience (Mandatory)
| Check |
Result |
Evidence |
Notes |
Queue topology documented (high-priority, bulk, DLQ) |
|
|
|
| Retry/backoff policy defined per connector flow |
|
|
|
| Checkpoint/watermark strategy exists for resumable jobs |
|
|
|
| Structured logs, metrics, and alerts defined |
|
|
|
| Failure replay/runbook documented |
|
|
|
Decision Outcome
| Item |
Value |
Outcome (Approve/Approve with conditions/Reject) |
|
| Blocking conditions |
|
| Follow-up actions |
|
| Target completion date |
|
Post-Implementation Review
| Check |
Value |
| Actual p95 metrics vs planned |
|
| Incident count during rollout |
|
| Contract-break incidents |
|
| Needed ADR updates |
|