Why We Draw the System Before We Write Any Code

There's a version of software development where you open a code editor, start building, and figure out the architecture as you go. We've tried it. It works for prototypes. For anything a real business depends on, it reliably produces systems that are hard to change, impossible to explain, and expensive to maintain.

Not a formal UML spec — nobody's reading those. We mean a simple visual that answers three questions:

1. What are the pieces of this system? 2. How do they talk to each other? 3. Where does the data live and how does it move?

A decent architecture diagram for most projects fits on one page. If it doesn't, that's useful information too — it usually means the system is more complex than the client expected, or we've overcomplicated something.

The diagram's job isn't to document the system. It's to create a conversation about the system before anyone's committed to anything.

When we show a client an architecture diagram early, they catch things we'd miss. 'That data can't go through a US-hosted service — we have compliance requirements.' 'Actually that team handles that process, not this one.' 'Wait, we already have a system that does that.'

You want those conversations in week one, not week eight.

For a recent project — a multi-vendor marketplace for a retail client — the architecture had roughly: a storefront layer (Next.js, server-rendered product pages), an order management layer (custom API, Postgres), a vendor portal (separate Next.js app, shared auth), and integrations out to a 3PL for fulfilment and Xero for accounting.

Drawing that out took about two hours. It immediately surfaced that the Xero integration was going to be the messiest part — not the storefront — because the client's chart of accounts had years of inconsistency that no amount of clever API work could paper over. They needed to fix their accounting data first. That conversation happened in week one, not week six.

For client-facing diagrams: Miro or FigJam — collaborative, easy to iterate live in a call, no special software to install.

For more technical internal diagrams: Excalidraw (free, hand-drawn aesthetic that signals 'this is still a draft') or Lucidchart when we need something polished.

We've settled on a simple notation across all projects: rectangles for services, cylinders for data stores, lightning bolts for async events, solid lines for synchronous calls, dashed for async. It's not a formal standard but anyone on the team can read a diagram without a legend. Consistency matters more than correctness.

The architecture diagram is wrong by the end of the first sprint. That's fine — update it. A diagram that accurately reflects last week's system is more useful than one that accurately reflected the original plan.

The failure mode we see most often: the diagram gets made, everyone nods at it, then it lives in a Confluence page nobody opens for the rest of the project. By go-live it bears no resemblance to reality and new team members have to reverse-engineer the system from the code. Keep it alive.