System design practice
Treat architecture decisions as experiments, not declarations
A practical way to move from a convincing diagram to a design you can question, observe, explain, and improve.
- Published
- 31 August 2026
- Reading time
- 7 min read
- Author
- Agnicode Product Team
Illustrative personaA diagram is a useful start, not the final evidence
Architecture diagrams are excellent compression tools. They help a team establish vocabulary, boundaries, and the shape of a proposed system. The risk begins when the clarity of the picture is mistaken for evidence that the system will behave as intended.
A diagram can show that a queue sits between two services. It cannot, by itself, explain what happens when producers outpace consumers, retries arrive out of order, or a dependency remains slow for twenty minutes. Those are behavioral questions, and they need a way to be explored explicitly.
Begin with the question the design must answer
Before selecting a pattern, state the decision in operational language. “We need a queue” is a component choice. “Order intake must continue during a short fulfilment outage without losing accepted work” is a behavior the team can reason about.
The second statement creates useful follow-up questions: how long is “short,” what counts as accepted, how much backlog can be absorbed, how are duplicates handled, and who can see that recovery is falling behind? Those questions expose the real design surface.
- What user or business outcome must continue?
- Which failure, load, or change is most likely to challenge it?
- What would we observe if the design were succeeding?
- Which uncertainty is too expensive to leave implicit?
Use a repeatable architecture learning loop
The goal of an experiment is not to prove the original idea correct. It is to reduce uncertainty cheaply enough that the next decision is better. A lightweight loop can be used in a workshop, an interactive model, a proof of concept, or a production readiness review.
- Frame one decision and the behavior it should protect.
- Model only the boundaries, dependencies, and constraints relevant to that question.
- Introduce one meaningful scenario such as a traffic spike, slow dependency, partial failure, or ownership change.
- Observe bottlenecks, queues, failure propagation, recovery needs, and the signals operators would require.
- Explain the trade-off, revise the design, and record what still needs validation.
Make the decision record useful after the meeting
A durable decision record should preserve the context that made the choice reasonable. Record the user outcome, constraints, alternatives considered, the scenario explored, observations, the chosen trade-off, and the condition that would cause the team to revisit it.
This turns the record into more than historical paperwork. A future engineer can distinguish a deliberate constraint from an accident, understand what evidence existed at the time, and run the next experiment when the operating environment changes.
Questions that improve an architecture review
A strong review creates shared understanding rather than rewarding the most confident presentation. Use questions that connect the design to behavior, ownership, and recovery.
- Which assumption would invalidate this design fastest?
- Where can work accumulate, and how will we know?
- What fails together even though the diagram makes it look separate?
- Who owns recovery when the happy path stops?
- What is the smallest experiment that would change our confidence?