CorriDraw for Engineering Teams: Architecture, ER Diagrams, and Incident Timelines on One Canvas

Architecture decisions live in an ADR folder nobody reads. The schema lives in migrations. The runbook is a 14-month-old wiki page. New engineers are told to "poke around". Here are the four diagrams every service should have on one canvas — and the two habits that keep them current.

The four canonical diagrams

Every service board in our setup has these four, in the same layout, so any engineer can find them the same way on every board:

• C4 context/container diagram — the 30-second overview.
• Crow's-foot ER diagram — the persistent data model.
• Sequence diagram — for whichever interaction keeps breaking.
• Incident lane — a ledger of every page, in order.

Activity diagrams, state machines, deployment diagrams live in drawers on the same board, out of the way until they're relevant.

1. C4 context — the 30-second stranger test

Every service board starts with a C4 Level-1 context diagram. Our product in one box, the humans who use it, and the external systems it talks to. Arrows labelled with the protocol — "HTTPS/JSON", "webhook", "nightly CSV drop". Nothing else.

The pass/fail test: a new hire who has never seen the code reads this diagram for 30 seconds and can answer "what does this service do, and who calls it?" If they can't, the diagram is wrong. Level 1 + Level 2 (containers) is almost always enough; Level 3 lives in a drawer for refactor sessions. Full walkthrough in C4 Model 101.

2. ER diagram — the shape of your world

You can swap services and rewrite languages, but you can't casually replace the schema. The shape of your data shapes the product for years. Four habits make the ER diagram useful instead of decorative:

1. Persistent domain only. No view models, no DTOs, no caches — just the nouns in the database.
2. Crow's-foot cardinality is mandatory. "user 1 — * order" vs "user 1 — 1 order" is a product decision, not a technical one. Pin it.
3. Keys + 2–3 attributes per entity, not every column. Migrations hold the full truth; the diagram holds the idea.
4. Generate from migrations, not the reverse. A small script parses Rails/Prisma migrations into Mermaid. CI fails the PR if the export drifts from the board. The diagram never wins against the DB.

If you need a refresher on crow's-foot notation, see ER Diagrams 101.

3. Sequence diagram — only for the breakage-prone interaction

Drawing sequence diagrams for every interaction is how documentation gardens die. Pick the one interaction that keeps breaking and pin its sequence diagram. For us it was "save-and-share a new board" — client → API → queue → worker → DB, with four failure modes. Every debug session now starts there.

When a new bug-class shows up — say, a webhook retry storm — draw a second sequence and pin it next to the first. Dead sequences move to an archive drawer (not deleted; postmortems three years later sometimes need the old picture). Notation reference: Sequence Diagrams 101.

4. Incident lane — a ledger, not a wiki

Most incident docs are a PDF per incident in a folder. The corpus is invisible, so when the same DB-connection-storm hits for the fourth time, nobody knows it's the fourth time. The fix is putting the ledger on the board where everyone walks past it.

• One card per incident: ID, severity, date, one-sentence root cause, owner, link to the writeup.
• Colour by system: red for DB, orange for API, blue for worker. Patterns become visible in seconds — "four red cards this quarter, three same root cause" is a project, not a postmortem.
• First stop on a page: "has something like this happened before?" is usually answered in under a minute because 18 months of pages are visible at once.

Arrows are decisions — write what they carry

The worst habit in engineering diagrams is the unlabelled arrow. Two boxes connected by a line tell you almost nothing. Label every arrow with the verb and the payload:

• POST /orders with cart_id
• emits order.created
• reads session cookie

Same on the ER diagram: an unlabelled arrow between Customer and Order leaves the most important question open. Is it places, billed_for, or owns? Name it. The name constrains the code.

How the board stays current

Documentation rot is real. Two habits keep ours honest:

1. Robots maintain the things robots can. The ER diagram is generated from migrations; CI fails the PR on drift. The incident lane is appended by an on-call hook when an incident closes in Linear.
2. The PR is incomplete until the diagram is updated. A PR touching the "save-and-share" flow doesn't ship until the sequence diagram matches. Reviewers check the board the same way they check the tests. Fifteen minutes per PR; an hour saved next month.

Try this on your next service

1. Pick one service. Open a fresh board.
2. Draw the four quadrants in 30 minutes: C4 context top-left, ER top-right, sequence bottom-left, incident ledger bottom-right.
3. Don't aim for completeness. Aim for a picture a new hire could read in 5 minutes and be useful by lunchtime.
4. Next PR you write that touches the service, update the board as part of the PR.

A month from now the board will be the first place engineering looks. A quarter from now you'll wonder why it took you so long.