Software Architecture Review Checklist
This is the checklist I walk through when a client asks me to review their architecture: 48 checks in eight categories, in the order I actually work. The whole thing is on this page. Nothing to sign up for, no PDF to request, no email required.
A software architecture review checklist is a structured set of questions you walk an existing system through (context, scalability, reliability, security, cost, modularity, AI-readiness, and documentation) to find what breaks first and what was built years too early. This is the working checklist Oleg Sotnikov uses on client reviews as a fractional CTO with 25+ years in IT and 1,000+ projects behind him: 48 checks in eight categories, published in full with no email gate. One rule governs all of it: architecture is judged against your stage, not against best practice, because over-engineering kills startups as reliably as under-engineering.
How to Use It
Fix the context first
Fill in category one before you judge anything else: stage, team size, real load, the constraints you cannot change this year. Every verdict further down is relative to those numbers. Without them you end up grading your system against somebody else's.
Walk each category with evidence
Answer with a query plan, a dashboard, a log line, or a file path, not with a memory of how the system was meant to work. Where nobody can produce the evidence, write that down: an unanswerable question is a finding in its own right.
Sequence findings into a roadmap, not a rewrite
Rank what you found by what it costs you, then order the work so each fix makes the next one cheaper. Forty red marks is not a case for a rewrite. It is a backlog with a priority problem, and those are far cheaper to solve.
The Checklist
Architecture is only right relative to something. The same design that is negligent at 500,000 users is overbuilt at 500, and the second mistake is the one that quietly kills startups: months of infrastructure work for load that never arrived, while the product question went unanswered.
So every check below is a comparison against your stage, your team, and the traffic you actually carry. Run it top to bottom. Category one comes first because it sets the baseline everything else is measured against.
Context and constraints
- Write down today's numbers before opening a single diagram: daily active users, peak requests per second, the largest table, total data volume.
- Name the stage in one line (pre-product-market-fit, scaling, or steady), because every verdict below is relative to it.
- Record the team as it is: how many engineers, who carries the pager, who is the only person who understands the payment path.
- Separate real load from aspirational load, and design for the traffic you have plus a year of plausible growth.
- List the constraints you cannot change this year: a compliance regime, an enterprise customer's on-prem requirement, a database you are contractually stuck with.
- State the twelve-month business goal the architecture has to serve (a raise, a new market, a margin target) and keep it in view for the rest of the review.
Scalability and performance
- Trace your three most frequent requests hop by hop and record where the time is actually spent.
- Find the slowest query on the busiest table, read its plan, and check whether a missing index or an unbounded result set explains it.
- Ask what gives way at ten times today's load, not a hundred. The first component to break is the only one worth arguing about right now.
- List every synchronous call sitting in a request path that could be a background job.
- Count the consumers on each queue, and check how long the backlog takes to drain once one of them dies.
- Look for N+1 queries and per-request fan-out on the endpoints your users hit most, before optimizing anything deeper in the stack.
Reliability and failure modes
- Name the single points of failure out loud: the one database, the one region, the one cron host, the one person.
- For every external dependency, write what happens when it is down for an hour: timeout, retry, fallback, or outage.
- Restore a production backup into a scratch environment and time it. An untested backup is not a backup.
- Confirm retries have limits and backoff, and that no retry path can duplicate a write that was never idempotent.
- Check that every critical path has an alert a human actually receives, then delete the alerts nobody has acted on in a year.
- Read the last three incidents and decide whether the structural cause was fixed or only the symptom was.
Security and data flows
- Draw where personal and regulated data enters, rests, and leaves, including logs, analytics, backups, and model prompts.
- Find where secrets live and how they rotate, then search the repository history for the ones that leaked.
- List which service can reach which, and flag every pair that trusts the other only because both sit inside the same network.
- Confirm authorization is enforced on the server for every endpoint, internal admin tools included.
- Check that third-party exports and analytics pipelines carry the same protections as production. That is where regulated data usually escapes.
- Verify dependencies and images are scanned, and name the person who acts on the results.
Cost profile of the design
- Attribute last month's bill to components: compute, storage, egress, managed services, model calls.
- Trace each large line back to the design decision that creates it: cross-zone chatter, per-request fan-out, an untiered bucket, a model call on every keystroke.
- Divide infrastructure cost by active users and check which way that number has moved over six months.
- Add up what non-production environments cost while nobody is using them, then decide whether that is a price worth paying.
- Price the frontier-model calls that a smaller model, a cache, or a nightly batch would serve identically.
- Give the weekly bill an owner who is also allowed to change the architecture that produces it.
Modularity and delivery impact
- Check whether two engineers can ship two features on the same day without editing the same files.
- Time the path from commit to production, and count how many humans have to act along the way.
- Find the modules with no owner, and the modules only one person can safely change.
- Look for database tables written by more than one service, the most common fake boundary in a system that calls itself modular.
- Count the environments teams queue for. One staging box serializes an entire organization.
- Confirm that a revert is routine rather than an emergency, and that somebody has done one recently.
AI-readiness
- Describe each module's responsibility in one sentence. Coding agents work well inside boundaries you can state that plainly, and flail without them.
- Run the test suite and judge honestly whether a green result means a change is safe to merge.
- Measure the loop from an edit to a signal that it worked. Anything longer than a coffee break slows humans and agents alike.
- Mark which parts of the codebase were AI-generated, roughly when, and who reviewed them line by line.
- Check the repository carries the context an agent needs: conventions, architecture notes, and how to run the thing locally.
- Write down the areas agents may not touch (payments, auth, migrations, schema changes) somewhere the tooling reads, not only in someone's head.
Documentation and decision records
- Hand the README to somebody new and watch them try to run the system locally. Fix whatever stops them.
- Find the decisions that were argued over for weeks and never written down, then write those records now, retroactively.
- Compare the architecture diagram against what actually runs in production, and put a date on it.
- Record the two or three constraints that explain the shape of the system. Those are what future readers get wrong first.
- Keep a list of the problems you have knowingly chosen to live with, so they read as decisions rather than oversights.
- Check there are runbooks for the three most likely incidents, written so somebody who wasn't there can follow them at 3am.
Frequently Asked Questions
What is an architecture review?
An architecture review is a structured assessment of a system you already have: how it is split into parts, how data moves between them, where it gives way under load, and what the design costs to run. It is measured against one company's stage and trajectory rather than against generic best practice, because the right architecture for 500 users and for 500,000 are different systems. The output is a written set of findings ranked by consequence, with a fix order attached. It is not a grade.
How often should we review our architecture?
At stage changes, not on a calendar. Before a scaling push, before a raise or an acquisition where technical questions get asked in detail, after a pivot that changed what the system has to do, and when delivery slowed and nobody can name the reason. For most companies that works out to once or twice a year. Between those moments, a pass over a single category is usually enough to catch drift.
Can I run this checklist on an AI-generated codebase?
Yes, and category seven exists for that case. Code produced by agents tends to be locally reasonable and globally inconsistent: duplicated logic, module boundaries that drifted, tests that assert nothing, dependencies nobody chose deliberately. Run the same eight categories, and pay particular attention to which parts a human has actually read. Unreviewed code carrying production load is usually the real risk, not the code quality itself.
What if the review says we should rewrite?
It almost never should. A full rewrite trades a system with known problems for a system with unknown ones, and it reliably takes longer than the estimate that justified it. Nearly everything a review finds can be fixed incrementally (extract one boundary, fix the hot path, split the shared table) while the product keeps shipping. The honest exceptions are narrow: a platform that no longer gets security updates, or a licence you can no longer live with.
Run It Yourself, or Have Me Run It
The checklist is the same one I use. What an engagement adds is the reading behind it: tracing critical paths through code you did not write, and ranking findings by what they cost you.
Scoped per engagement. Thirty minutes on a call is enough to size it. NDA on request.
Related reading
Architecture decisions, scaling, and the trade-offs behind both.
