Building a sequence diagram you can trust

The problem with docs

Every architecture diagram I've inherited on a client engagement has been wrong by the time I opened it. Not maliciously — just quietly out of date, drawn in a tool nobody on the delivery team has a licence for, exported once as a PNG, and never touched again. The system moved on. The picture didn't.

On the Kindergarten Arrival Funding platform, the prefill flow touches four services, two queues, and an external IBM ODM integration. A diagram that goes stale here doesn't just look bad in a wiki — it costs a new team member a day of tracing logs to rebuild a mental model that used to be free.

If a diagram can't be reviewed in the same pull request as the code it describes, it will eventually lie to you.

Diagrams as code

The fix is boring: write the diagram in text, check it into the same directory as the service it documents, and render it at build time. Mermaid is the format I've settled on — it's supported natively by GitHub and GitLab previews, and it renders identically whether you're looking at a PR or the published docs site.

Here's the flow definition that documents the prefill sequence. It lives at docs/prefill-sequence.mmd, next to the handler it describes:

import { PrefillClient } from './odm-client';
import { QueueProducer } from './queue';

// Triggered when a guardian submits the arrival funding form.
// Runs the ODM ruleset, then queues the funding decision.
export async function handlePrefillRequest(applicationId: string) {
  const application = await getApplication(applicationId);
  const decision = await PrefillClient.evaluate(application);

  if (decision.status === 'approved') {
    await QueueProducer.publish('funding.approved', {
      applicationId,
      amount: decision.amount,
    });
  }

  return decision;
}

And the sequence diagram sitting right beside it, rendered from source rather than pasted as an image:

A worked example

The same approach works for state and flow diagrams. Here's the funding application's lifecycle — useful for onboarding, and honest about the one state most diagrams quietly omit: the dead end.

A short clip from the internal walkthrough I recorded for the delivery team when this pattern was rolled out:

The pattern got a bit of attention when I wrote it up publicly:

And a look at the whiteboard session where the sequence above started life:

Where this breaks down

Text-based diagrams aren't free. Mermaid's auto-layout struggles past roughly a dozen participants — beyond that, hand-tuned tools still win on readability. And a diagram checked into a repo is only as trustworthy as the review discipline around it; nothing stops it from going stale, it's just now a code review problem instead of a wiki problem, which in my experience is a discipline most engineering teams already have.

Takeaways

• Keep diagrams as text, in the same repo as the code they describe.
• Review diagram changes in the same pull request as the behaviour change.
• Reserve diagrams for service boundaries and external integrations — not every function call.
• Mermaid renders natively in GitHub/GitLab previews, so there's no extra tooling tax for reviewers.