The most expensive mistakes in software are rarely bugs. They are decisions — about data models, boundaries, and integrations — that were made implicitly, discovered late, and expensive to reverse. By the time they show up in a demo, the cost of changing them has multiplied.
So before we build anything, we write an architecture document and review it with you. It is short, it is specific, and it is the single most useful thing we produce in the first two weeks of a project.
What goes in it
The document is not a diagram for its own sake. It answers the questions that are cheap to change on paper and painful to change in production:
- The data model. The core entities, how they relate, and where the tricky ownership rules live. Most of a system's future flexibility is decided here.
- Boundaries. Which parts of the system are separate, why, and how they talk to each other. This is where we decide what can be changed independently later.
- Integrations. Every external system we depend on, what happens when it is slow, and what happens when it is down.
- Security and tenancy. How data is isolated, who can see what, and where the sensitive paths are — designed in, not bolted on.
- The parts we are unsure about. The open questions, written down honestly, with how we plan to resolve them.
Why review it before code
Writing it down forces the vague parts to become concrete. You cannot hand-wave past "we'll figure out permissions later" when there is a heading that says permissions and nothing under it.
Reviewing it with you does two things. It catches the assumptions we got wrong about your business while they are still a paragraph, not a feature. And it gives you a real artifact to push back on — you can disagree with a design decision when it is a sentence, in a way you never can once it is three weeks of code.
The goal of the document is not to be right the first time. It is to make being wrong cheap.
It is a living document, not a gate
We are not trying to specify the whole system up front. That never survives contact with real requirements. The document covers the decisions that are hard to reverse and leaves the rest to be worked out during the build. As those decisions get made, it gets updated — so there is always one place that describes how the system actually works.
The practical payoff
When the architecture is written down and agreed, the build is calmer. There are fewer mid-sprint surprises, onboarding a new engineer takes hours instead of weeks, and when something needs to change, we can reason about the blast radius instead of guessing at it.
None of this requires a heavy process. It requires writing the important decisions down before they harden, and being willing to be told you got one wrong while it is still easy to fix.