A 34-minute working session on the diagrams every engineer should recognize and draw — C4 for architecture, UML sequence for flows, BPMN for processes, ERDs for data — plus the tools that keep them honest.
Read three paragraphs describing how an order moves through five services and you'll build five different mental models. Show one diagram and the whole room is suddenly arguing about the same thing. A diagram is a shared, low-cost place to think out loud before you write any code.
There is no single "right" diagram of a system — only the right diagram for this audience and this question. The same checkout system is four different pictures depending on who's in the room.
Same system, four audiences — four diagrams at four zoom levels.
The diagram is cheaper to argue over than the code. Disagreements surface in minutes, not in the next sprint's pull request.
A good context diagram saves a new hire a week of reading code to learn what talks to what.
Drawing the design forces the hard questions early — where the data lives, who calls whom, what happens on failure.
Most architecture diagrams fail the same way: one canvas tries to show users, services, classes and queues all at once, and nobody can read it. C4 fixes this by giving you four fixed zoom levels, like Google Maps for software — country, city, street, building.
A container in C4 does notmean Docker — it means a separately runnable or deployable thing: a web app, an API, a database, a mobile app. Here are the two levels you'll draw most:
The whole system as one box — who uses it, what it depends on. For non-technical stakeholders.
Pop the lid: the deployable parts and how they talk. For engineers joining the team.
A context or container diagram shows structure — what exists. A sequence diagram shows behavior— the exact order of messages when one specific thing happens, like a user logging in. It's the single best diagram for explaining an API call or a flow that crosses several services.
Solid arrows are calls (going right); dashed arrows are returns (coming back). Time runs downward.
A box at the top — a person, a service, a database. Each owns the lifeline below it.
The dashed vertical line. Position down the line means "later in time".
A horizontal arrow. Solid for a synchronous call, dashed for the reply that comes back.
The thin bar on a lifeline showing the participant is busy doing work for that call.
Keep it to one scenario. A sequence diagram earns its keep by showing the happy path of a single flow, or one failure case — not every branch. If you find yourself adding a dozen loops and conditions, you want a flowchart or a BPMN diagram instead.
Some flows aren't about services calling each other — they're about a business process: a request comes in, someone reviews it, a decision splits the path, work happens, the process ends. BPMN is the standard for drawing these so that engineers, analysts and managers all read the same picture.
An access-request process: a start event, a task, an exclusive (either/or) gateway, two outcomes, and an end event.
A thin circle starts the process; a thick circle ends it. Events can also fire mid-flow (a timer, a message arriving).
One step a person or system performs — "Submit request", "Grant access". The verbs of the process.
An exclusive gateway (×) takes exactly one branch; a parallel one (+) runs branches at once. The decisions.
A solid arrow is the sequence — what happens next. Lanes (not shown) group tasks by who owns them.
Sequence diagram vs BPMN? Reach for a sequence diagramwhen the audience is engineers and the question is "what calls what, in what order". Reach for BPMNwhen the audience includes the business and the question is "what are the steps and decisions in this process".
Before a single table exists, an entity-relationship diagram lets you agree on what things you store, what facts you keep about each, and how they connect. Get the relationships and cardinality right on paper and you avoid the most expensive class of mistake — a schema you have to migrate under load.
The forked "crow's foot" end means "many"; the single bar means "one".
The common case. One customer placesmany orders; each order belongs to exactly one customer (a foreign key on the "many" side).
An order contains many products; a product appears in many orders. In a real schema this needs a join table in the middle.
A primary key uniquely identifies a row; a foreign key points at another table's primary key — that's the wire the relationship rides on.
Crow's-foot notationis the dialect you'll see most: the three-pronged "foot" marks the many side, a small bar marks the one side, and an extra circle means optional (zero is allowed). It reads left-to-right like a sentence — "one customer places zero-or-many orders".
The biggest tooling choice isn't which app — it's whether your diagrams are text you commit to the repo or pictures you draw by hand. Each wins a different job; mature teams use both deliberately.
Pro — renders straight inside GitHub, GitLab and Markdown; zero install.
Con — auto-layout can get awkward on big, dense diagrams.
Pro — broadest UML coverage and fine control; battle-tested.
Con — needs a render server/Java; syntax is heavier to learn.
Pro — fast, hand-drawn feel; perfect for live brainstorming.
Con— freeform, so it drifts from reality and isn't versioned in git.
Pro — free, huge shape libraries, stores as a file you can commit.
Con — manual layout means upkeep; diffs are unreadable XML.
Pro — slick collaboration, templates, great for exec-facing decks.
Con — paid SaaS; lives outside the repo, so it ages quietly.
Diagram that must stay true → diagram-as-code in git. A throwaway brainstorm → Excalidraw. A polished hand-off → Lucidchart or draw.io.
Every diagram in this deck answers a different question for a different audience. The skill is matching the two — and then drawing only as much as that question needs.
For stakeholders and new engineers — the boxes and the wires between them.
For engineers debugging or designing one flow across services, over time.
For business + engineering looking at a process with decisions and outcomes.
For anyone touching the schema — entities, attributes, and cardinality.
Five quick questions on C4, sequence diagrams, BPMN, ERDs, and tooling — instant feedback, no sign-in.
Navigate with ← → or scroll · back to library