Architecture Reviews: Turn Uncertainty into Owned Decisions

Run a focused architecture review with explicit decision authority, blocking risks and a worked RFC-to-ADR example that separates pilot approval from release readiness.

A review can reduce risk and make an approval decision

An architecture review should expose consequential assumptions before they become expensive commitments. It may also authorize work. Those purposes are compatible, provided the participants know who can decide and what the decision permits.

“Looks reasonable” is not a useful release gate. An approval to investigate an approach is different from approval to implement it, migrate data or serve production traffic. Write the boundary down.

This article describes a software design review. It is not an AWS Well-Architected pillar checklist, a security certification or a substitute for an organization's formal risk process.

Review the decision that is actually expensive to reverse

Choose the scope from the consequences. A new persistence model, trust boundary, external dependency or migration may warrant review. A routine change inside an established boundary may not need the same process.

The author should identify the decision, why it is needed now and what happens if it is deferred. Include the current behavior, important constraints and alternatives, including a smaller change or no change. The technical-decision cost model helps compare initial work, ongoing operation and exit obligations over the same planning horizon.

Use diagrams to clarify the system boundary and important interactions. The C4 system-context guidance starts with the people and neighboring systems around the system of interest. Add lower-level detail only where it helps answer the review's question. A diagram with every deployment component can obscure a simple ownership or data-flow problem.

Separate participation from authority

Invite people because their knowledge or responsibility is needed, not because of a fixed attendance rule. Async review can resolve some questions; a discussion helps when assumptions conflict or a tradeoff needs a decision.

One person may hold several roles, but the responsibilities still need to exist. The technical decision owner cannot waive a control outside their authority. If an essential owner is missing, record the question and defer the affected approval.

Give reviewers a document they can challenge

Use a concise request for comments, or RFC. A written record is useful because reviewers can inspect assumptions before the meeting and return to the reasoning later. A diagram, experiment or demonstration may accompany it; the medium is less important than accessible evidence.

Design proposal
  Decision requested and work it would authorize:
  Problem, current behavior and evidence:
  Goals, non-goals and affected users:
  Constraints and accountable owners:
  Proposed design and important data flows:
  Alternatives, including a smaller change:
  Failure, security and operational risks:
  Migration, compatibility and recovery:
  Unknowns and experiments:
  Acceptance evidence:
  Revisit triggers:

Ask reviewers to connect objections to a requirement, risk or missing fact. “I prefer another database” is incomplete feedback. “This option cannot meet the agreed restore requirement with the team's current capabilities” is a question the proposal can address.

Do not punish an author for surfacing uncertainty. A review that conceals unknowns produces an apparently cleaner decision and a less reliable implementation plan.

Work through a hypothetical catalog-search proposal

Suppose an application currently searches its product catalog in its primary database. The proposal adds a separate search index to support richer queries. These details and thresholds are invented to demonstrate the review method, not customer results or universal targets.

The RFC proposes that the primary database remain authoritative. A committed publication change produces a durable event through an outbox recorded in the same transaction. A worker updates the index. Browsing may use the index, but checkout still verifies current price and availability against authoritative data.

The first review identifies three unresolved questions: can draft products enter the index, can reordered events restore an older version, and can the existing search path absorb traffic after rollback?

The review does not prove that the outbox, version rule or fallback works. It defines what evidence the implementation must produce. Publishing an event without a durable relationship to the database commit would leave a different failure gap and require a revised design.

Record what was decided, including the limits

Michael Nygard's original architecture decision record describes recording context, decision, status and consequences, and retaining a superseded decision rather than erasing its history.

An ADR captures the outcome of the review; it does not need to reproduce the whole discussion. Link the proposal, experiments and unresolved actions. The example below is a completed illustrative decision, not an actual approval.

ADR: Evaluate a derived catalog-search index

Status: Accepted for a sandbox pilot only
Decision owner: Accountable engineering lead
Risk owners: Product/data owner and security owner

Decision:
  Keep the primary database authoritative.
  Test a derived index with version-aware event processing.
  Do not route production search to the index yet.

Alternatives:
  Tune the existing database search.
  Narrow the proposed query features.
  Defer the index if operating cost outweighs user value.

Pilot acceptance assumptions:
  No draft results in the agreed negative-test fixtures.
  No stale overwrite in duplicate and reordered-event tests.
  Commit-to-visible delay within 60 seconds for the test workload.
  Search p95 within 300 ms at 100 requests/second in the recorded
  test environment, with agreed query and catalog distributions.
  Rebuild and fallback exercises completed and evidence attached.

Consequences:
  Another derived copy, worker and reconciliation process to own.
  Search may lag publication; checkout cannot trust index values.

Production gate:
  Relevant owners review test results, cost and operating readiness.
  A separate release decision authorizes a bounded traffic rollout.

Revisit:
  Correctness failure, missed freshness objective, new data class,
  changed workload, or unsupported fallback capacity.

The performance numbers only make this example testable. A real review must derive targets from user needs and record the environment, data, cache state and traffic model. Passing a small sandbox test cannot establish production capacity.

Make blocking and non-blocking feedback distinguishable

A comment is not minor merely because it is easy to write. Missing authorization, data-loss recovery or an accountable operator can block progress. Conversely, a preference that does not affect the agreed requirements need not become a release condition.

For dissent, record the concern, evidence and decision owner rather than manufacturing consensus. Escalate only the tradeoff that exceeds the group's authority.

Verify the transition and preserve a return path

Before the catalog-search pilot reaches users, compare shadow query results without changing user-facing behavior. Review mismatches, excluded data and index lag. A bounded rollout can follow only after the production gate is satisfied.

If correctness or freshness fails, stop expanding the cohort. Restore the known-compatible search path if its capacity and semantics remain valid. Continue preserving and reconciling publication events as required by the chosen recovery procedure. Reverting the application flag does not repair an inconsistent index.

Keep the decision record current when a premise changes. Supersede the ADR when the decision changes, linking the new rationale. Avoid making every implementation detail a permanent architectural rule.

Close the review with an executable record

• The requested decision and its authorization boundary are explicit.
• The problem, alternatives and current evidence are available to reviewers.
• Data, dependency, operating and risk responsibilities are represented.
• Blocking questions have owners and objective acceptance evidence.
• The ADR records consequences and unresolved limitations.
• Migration and rollback include committed data and derived state.
• Production release is not inferred from a pilot approval.
• Revisit triggers identify when the decision must be examined again.

For implementation work, system architecture design is the related service scope. The immediate output of the review should be smaller and clearer: a decision someone owns, a set of conditions someone can verify and a recovery path someone can execute.

Schedule the next review from a real trigger, such as a load boundary, incompatible schema change, new regulated data class or failed recovery exercise. A calendar reminder alone should not keep reopening a decision whose assumptions remain unchanged.