A map of a system's parts and how they connect, for the engineers and clients who work with it.
An architecture diagram answers what a new engineer asks in their first week and a client's technical lead asks before signing: which parts exist, and what talks to what. Two finished ones are linked here: a system map for an inspection app and a database diagram for a booking system. Borrow their shape. Yours has to come from your own system, checked against the code.
Who it's for
Engineers explaining a system to people who didn't build it: a new teammate, a contractor, a client's technical lead. Send it before the first walkthrough call, so the call goes on questions.
It's a picture of one moment, drawn by hand and corrected when the system changes. A diagram that redraws itself from your infrastructure is a job for a tool wired into your cloud account.
What a good one contains
- Every part named for what it does. "Job queue" and "File storage" tell a newcomer more than a vendor's logo would.
- Arrows that mean something. Solid for a request where the caller waits, dashed for work handed to the queue. When every arrow looks alike, nobody can tell a slow path from a fast one.
- A legend. Five entries cover both arrows, both borders and the numbered dots. Without it, a dashed border is a guess.
- One real request, traced. The dots follow a finished inspection from the phone to the client's inbox. A trace gives the order of events, which a field of boxes can't.
- A reason for each part. Why is there a queue? So the API can answer in milliseconds and leave the PDF for later. Reasons stop the next person from removing something that mattered.
- What you left out, said out loud. Logging, monitoring and the deploy pipeline are named as missing on purpose.
- In a database diagram, the fields and the keys. The booking example lists every column with its type, marks the primary and foreign keys, and labels each line one-to-many.
So it still matches production
A diagram goes stale the week someone adds a service and doesn't redraw it. Put a "checked against production" date on it, as the Snagbook map does, and change the page in the same pull request as the system. The link stays the same, so the one in your onboarding notes doesn't break.
Ten boxes can be read on a phone and forty can't. For a bigger system, draw the whole thing at low detail and give the hard part a page of its own.
For a data model, follow one real record through the tables and check the arithmetic, as the booking example does with a $105 session. A missing table shows up there first.
How to send it
To named people. A system map shows where the data lives and which outside services you lean on. Limit it to your engineers and the client's technical lead.
Every page you publish gets one link that opens in any browser. You choose who can open it: anyone with the link, anyone with the password, or only the people and company domains you name, who sign in with Google or Microsoft. Change the page later and the link stays the same.
