Software Architecture Review
A decision record for the next system change
Six fields to agree before the review begins.
Dmytro Nasyrov PhD
The review intake record
Decision: the choice the review must inform.
Candidate: the exact revision or proposed configuration.
Boundary: the systems and operating actions in scope.
Evidence: the artifacts available and the questions they can answer.
Owner: the person authorized to accept the consequence.
Reopening trigger: the change that requires another review.
An example with an unresolved dependency
Illustrative scenario. A team wants to enable a new partner to submit orders.
The review concerns partner order intake. It excludes unrelated billing changes.
The team has an interface description but has not established whether the downstream provider supports order-status lookup.
The open question belongs in the record before anyone recommends a recovery design.
What each artifact can establish
| Artifact | Useful evidence | Remaining question |
|---|---|---|
| Architecture diagram | Intended boundaries | Does the running system match? |
| Current configuration | Selected access policy | Does enforcement match the policy? |
| Observed trace | One operation under recorded conditions | Does it cover the proposed change? |
Record the revision and observation conditions beside each artifact.
The uncertain order outcome
A caller loses the response after submitting an order. The team cannot yet establish whether the provider accepted it.
The proposed review asks how an operator can identify the original instruction and investigate its outcome.
A repeat submission needs a justified contract and an authorized action. A missing response alone does not establish that the first request failed.
This is a review scenario. No failure test or client result is claimed.
A decision with explicit conditions
Proceed within scope: the decision owner accepts the documented conditions and unresolved limitations.
Defer: a named evidence gap prevents the owner from deciding.
Reduce scope: the team chooses a smaller change with boundaries it can establish.
The record names the next owner and the evidence needed to close each open question. Acceptance does not mean remediation.
Architecture review scope and support
When architecture choices lack a clear review scope, Pharos Production offers IT consulting and software architecture review.
Agree the decision, available evidence and expected deliverables before commissioning the work.
The six-field record is a proposed working aid. Engagement scope and acceptance terms require agreement.
About the author
Written by Dmytro Nasyrov PhD, software architect with 24 years of production experience. Dmytro is the founder and CTO of Pharos Production. He works on production software architecture for FinTech, AI, Web3 and blockchain systems.
Dmytro Nasyrov. Photo supplied by the author.