Ta strona jest po angielsku. Nie ma jeszcze tłumaczenia; kanoniczny jest adres angielski. Otwórz wersję angielską
Software architecture
A practical software architecture review framework
An architecture review that cannot name the decision it supports is a tour. I use a short set of questions that can fail. If a system passes them, we are arguing taste. If it fails them, we have a sequence. This is the list I actually bring into the repository.
1. Constraint
Which failure is expensive: lead time, incident rate, infra cost, correctness, or a date you cannot move? If nobody can answer, the review will become a stack debate. I will stop and get the constraint in writing before drawing boxes.
2. Change shape
Where do diffs concentrate? If every feature touches the same module, splitting into services will clone the bottleneck. Decompose the module first. Service boundaries are for independently changing reasons, not for org charts you wish you had.
3. Contracts
Are boundaries typed, versioned, and owned? Implicit JSON between three teams is an outage with extra steps. This is stricter once a model is on the path: probabilistic outputs need schemas and reject paths more than human-written payloads do.
4. Failure
What happens when the queue, the provider, or the model is wrong or gone? 'The user retries' is not a design. Idempotency, timeouts, poisoning, and a human path are. I read jobs and consumers before I trust a happy-path sequence diagram.
5. Operability
Can a competent new engineer find the path from an HTTP request to a row in an afternoon? If the answer depends on one person, you have a bus factor, not an architecture. Logs and traces that cannot answer 'what happened to this id' are decoration.
6. Team fit
Would this design still work if the platform team you do not have never appears? Recommending Kubernetes, a mesh, and a data lake to a six-person product team is malpractice. I will recommend the least complex shape that survives the constraint and the headcount.
How I write the output
A decision memo: context, what I could verify, options with trade-offs, recommendation, and what we are explicitly not doing. Diagrams only where they change the call. A 40-box C4 that nobody can map to a repository path is worse than no diagram.
If the honest result is 'stay, and spend the rewrite budget on tests and the module that actually hurts', I will write that. The review is not a prelude to selling a rebuild.
Takeaways
- Name the constraint or you are reviewing taste.
- Follow the change concentration, not the org chart.
- Treat failure and operability as first-class, including for AI components.
- Fit the design to the team you have.
- Write a decision, not a poster.