Software Architecture Review Checklist: Find Risk Before Production

A focused code Analyzing Technical Review Feedback Multi Flavor surface for checking risk before production.

A software architecture review should answer a more useful question than “does this design look clean?” It should tell the team what is most likely to fail, become expensive, or slow future delivery , and what evidence supports that conclusion. For a review example across product variants, see analyzing technical review feedback for multi-flavor Android apps.

That distinction matters because a Multi Agent Review Pipeline can easily become architecture theatre. Teams discuss layers, naming, patterns, and diagrams while missing the risks that later hurt production: an unclear source of truth, an untested migration, a dependency with no failure strategy, authorization enforced only in the UI, or a deployment that cannot be rolled back safely.

A better review is risk-first and scenario-driven. Evaluate the system against the behavior it must survive, record evidence rather than opinions, and turn findings into owned decisions.

This checklist is designed for an existing software project or a design approaching implementation. It is intentionally broader than code review: architecture review should cover quality attributes such as reliability, security, operability, performance, cost, and evolvability, not just structural elegance.

Start With Context, Not Components

Before reviewing modules or frameworks, write down five things:

Question	Evidence to collect
What problem does the system solve?	Product or business requirement
What is inside the review boundary?	Context/container diagram or dependency map
What is explicitly outside it?	External services, platforms, teams
What can the system not compromise on?	Reliability, latency, security, offline behavior, cost, compliance
What change is expected next?	Roadmap, scale target, migration, new integration

This prevents a common failure: judging architecture against generic “best practices” instead of the system’s actual constraints.

A small internal application and a payment platform should not receive the same architecture. The right question is whether the current design is proportionate to its risks and expected change.

1. Review Boundaries and Dependency Direction

Start by drawing the dependency graph that exists in code, not the one shown in an old slide deck.

Check whether:

• business rules are isolated from UI and infrastructure details;
• feature modules have clear ownership;
• shared modules are genuinely shared rather than dumping grounds;
• replacing a database, API client, analytics SDK, or authentication provider has a visible blast radius;
• circular dependencies or hidden runtime coupling exist;
• public module APIs expose only what consumers actually need.

A useful test is the replacement question: if one implementation disappeared tomorrow, how much unrelated code would have to change?

High replacement cost is not automatically wrong. It is a signal that the coupling must be intentional and justified.

2. Trace the Source of Truth for Important Data

Architecture diagrams often show where data travels but not which copy wins.

For every important entity, identify:

1. the authoritative source;
2. local/cache representations;
3. who is allowed to write;
4. how freshness is determined;
5. what happens when two writers disagree;
6. how deletion propagates;
7. how schema changes are migrated.

Consider an offline-capable profile screen. Updating the local database immediately may give excellent UX, but the architecture is incomplete until it defines what happens when the server rejects the change, another device updates the same field, or the process dies before synchronization finishes.

“Room + API + background worker” describes components. It does not describe a consistency policy.

3. Review Failure Modes, Not Only Happy Paths

For each external dependency or asynchronous workflow, ask what happens when this step succeeds twice, fails halfway, times out ambiguously, or never returns?

A compact failure matrix makes this concrete:

Scenario	Expected behavior	Evidence
API timeout after write	Retry without duplicate side effects	Idempotency test/log
Database migration fails	Stop safely or recover predictably	Migration test
Process dies mid-workflow	State can be reconstructed	Process-death test
Dependency is unavailable	Degrade, queue, or fail clearly	Integration test/runbook
Same event arrives twice	Result remains correct	Duplicate-event test

This is where architecture review becomes more valuable than a diagram walkthrough. Production incidents live in transitions and partial failures.

4. Test Quality Attributes With Scenarios

Avoid questions such as “is the system scalable?” They invite yes/no answers without evidence.

Turn quality attributes into scenarios instead:

• Performance: what is the acceptable P95/P99 latency at expected peak load?
• Reliability: what happens when the primary dependency is unavailable for 15 minutes?
• Security: where does untrusted input cross a trust boundary, and where is authorization enforced?
• Operability: what signal would tell an on-call engineer that synchronization is stuck?
• Evolvability: what changes when a second implementation of this capability is introduced?
• Cost: which resource grows fastest as usage increases?

Scenario-based questions expose assumptions that generic checklist items hide.

5. Review Security as Architecture

Security should not be postponed to a final penetration test.

Map trust boundaries and verify:

• authentication and authorization are separate concerns;
• authorization is enforced at the trusted boundary, not only in client UI;
• secrets are not embedded in distributable clients or repositories;
• sensitive data has explicit storage and transport rules;
• third-party integrations receive the minimum access they need;
• logs do not leak credentials or sensitive payloads;
• dependency and credential rotation have owners.

The goal is not to declare the system “secure.” The review should identify concrete attack surfaces, controls, missing evidence, and accepted risks.

6. Review Observability and Recovery Together

A recoverable system must first be diagnosable.

For each critical workflow, ask:

• What metric shows success or failure?
• What log or trace explains why it failed?
• Can operators distinguish a dependency outage from an application bug?
• Is there a safe retry or replay mechanism?
• Can a bad deployment be rolled back?
• Who owns the alert and the recovery action?

An architecture that can survive failure only when the original developer is online has an operational dependency that should appear in the review findings.

7. Verify Delivery and Change Safety

CI/CD is part of architecture because it determines whether the design can evolve safely.

Review whether automation protects the risky boundaries identified earlier. Depending on the system, useful checks may include:

• unit tests for business rules;
• integration tests for persistence and APIs;
• database migration tests;
• contract tests at service boundaries;
• static analysis and dependency scanning;
• release smoke tests;
• rollback or staged-release procedures.

Do not measure pipeline maturity by the number of jobs. Measure it by how quickly the pipeline disproves a dangerous change.

8. Turn Findings Into Decisions

A review that produces twenty pages of observations but no priorities has not finished.

Record each meaningful finding with four fields:

Field	Example
Risk	Duplicate writes after ambiguous network timeout
Evidence	Retry path has no idempotency key
Impact	Duplicate transaction or corrupted state
Decision	Add idempotency contract before release

Then classify findings by consequence and urgency. A practical model is:

• Blocker: credible path to severe production/security/data failure; fix before release.
• High: significant risk or expensive future constraint; assign owner and near-term remediation.
• Medium: real weakness with bounded impact; track explicitly.
• Accepted: known trade-off whose cost is currently justified; document the condition that should trigger reconsideration.

This keeps architecture review from becoming a hunt for perfection.

A 60-Minute Architecture Review Flow

For a focused project review, use this sequence:

0–10 minutes , Context. Confirm scope, critical workflows, constraints, and expected change.

10–20 minutes , Boundaries and data. Trace dependencies and the source of truth.

20–35 minutes , Failure scenarios. Walk through timeouts, retries, partial failure, process restart, migration, and dependency outage.

35–45 minutes , Security and operability. Inspect trust boundaries, authorization, secrets, telemetry, recovery, and rollback.

45–55 minutes , Delivery evidence. Check which assumptions are protected by automated tests and CI/CD.

55–60 minutes , Decisions. Rank findings, assign owners, and record accepted trade-offs.

Large or regulated systems need deeper analysis, but this format is enough to prevent a lightweight review from collapsing into style discussion.

The Review Is Done When Risk Is Legible

A good software architecture review does not prove that an architecture is perfect. It makes the architecture’s risks, trade-offs, evidence, and ownership legible.

If the review ends with a prettier diagram but the team still cannot answer what happens during a partial failure, who owns a risky dependency, how data conflicts resolve, or how a bad release is recovered, the important work is still unfinished.

Use the checklist to find those unknowns early. The cheapest architectural problem is usually the one discovered while changing the design is still easier than debugging the production incident.