Architecture Review Framework

An architecture review is a structured conversation that tests a proposed design against quality attributes before it is expensive to change. The aim is better decisions, not approval rituals.

The framework should be proportionate. A tiered model works well: self-review with a checklist for small changes, peer review for medium ones, and a panel for changes that affect many teams or carry regulatory risk. Authors then spend review effort where it earns the most.

How it works

The author writes a design document covering context, goals and non-goals, the proposed design, alternatives considered, and risks. Reviewers evaluate it against a standard set of quality attributes: availability, scalability, security, operability, data consistency, cost, and evolvability. Scenario-based analysis, in the spirit of ATAM, asks how the design behaves under specific stress, such as a regional outage or tenfold traffic. Outcomes are recorded as decisions with status and a revisit trigger.

Implementation steps

1. Define triggers that require review and the lighter path for everything else.
2. Publish a template with a required alternatives section and explicit tradeoffs.
3. Circulate the document at least two working days before discussion.
4. Reviewers submit written comments in advance, tagged blocking or advisory.
5. Hold a 45-minute meeting that resolves only the blocking items.
6. Record the decision in a decision record stored in the repository.
7. Schedule a follow-up after launch to compare predictions with reality.

Rotate reviewers so knowledge spreads and no individual becomes a bottleneck, and publish accepted designs in a searchable index so teams can reuse prior reasoning before starting a new document.

Common pitfalls

• Reviewing after implementation is done, when feedback cannot change anything.
• Debating technology preferences instead of quality scenarios.
• Letting a single senior reviewer dominate.
• Never revisiting decisions whose assumptions changed.

Metrics to watch

Median time from submission to decision, share of eligible changes reviewed, post-launch incidents traced to unreviewed designs, number of decisions with revisit dates met, and author satisfaction from periodic surveys.

Collect qualitative feedback too. If authors regard reviews as a tax, adjust triggers and templates, because a process that teams avoid produces worse outcomes than none.

Example decision record

# ADR-023: Use a managed message broker for order events

Status: Accepted
Date: 2026-03-14
Context: Order events must be delivered to billing and shipping reliably.
Decision: Adopt a managed broker with at-least-once delivery and idempotent consumers.
Alternatives: Self-hosted broker; database outbox polling only.
Consequences: Lower operations burden; vendor dependency; consumers must dedupe.
Revisit: When monthly volume exceeds 200 million events.

Key takeaways

• Scale review effort to risk and keep the common path light.
• Review quality scenarios and alternatives, not preferences.
• Record decisions with revisit triggers.
• Review early, while the design can still change.