Diagrams as Code with AI: The Analyst's System for Mermaid, BPMN, and Sequence Diagrams

AI does not make you a better diagrammer by drawing for you. It makes diagrams cheap enough to keep current. Feed a model real artifacts, an OpenAPI contract, a log export, a Bruno run, and it hands back valid Mermaid or BPMN in seconds, which changes the economics of documentation from “redraw it next quarter” to “regenerate it this afternoon.”

Every team I have worked on has the same diagram problem. There is a Visio file from the original project, it is two years old, three services have been added since, and nobody trusts it enough to open it during an incident. The problem was never drawing ability. The problem was that updating a diagram cost an afternoon and nobody had an afternoon.

Large language models remove that cost, but only if you change two things at once: what you draw with, and what you draw from. Draw with plain text formats that live in git, and draw from artifacts rather than memory. Do both and the diagram stops being documentation and becomes a build output, the same as a test report. This article is the system. The Mermaid syntax reference, the BPMN workflow, the logs pipeline, and the test run pipeline are the four pieces that hang off it. If you want the prompt library I use for this and the rest of the analyst workflow, it is in The Tech BA Prompt Toolkit.

Why does diagrams as code matter more than the AI part?

Because a diagram in a binary file cannot be reviewed, diffed, or regenerated, and a diagram that cannot be reviewed will be wrong within a quarter.

A Mermaid block is text. That single property gives you everything:

• It diffs. A reviewer sees Processor ->> Network: pacs.008 appear in a pull request and knows the integration changed.
• It reviews. The diagram change and the code change land in the same PR, in front of the same people, at the same time.
• It regenerates. A script can rebuild it from a log export nightly and fail a check if the committed version no longer matches.
• It renders everywhere. GitHub, GitLab, Notion, Obsidian, VS Code, and most modern wikis render Mermaid with no plugin, so the diagram is visible where people already are.
• It is a model’s native input and output. Text in, text out, with no round trip through an image.

That last point is what makes AI useful here. A model cannot open your Visio file, reason about it, and hand you a corrected version. It can take four hundred lines of correlated log output and hand you a twenty line sequence diagram that is right, because both ends of that transformation are text.

What do you actually feed the model?

Feed it evidence, not prose. A diagram generated from a paragraph inherits every ambiguity and every wishful assumption in that paragraph. A diagram generated from an artifact inherits the artifact’s accuracy.

Ranked by how much I trust the output:

Input	What you get	Trust
Correlated log export (Splunk, Datadog)	The flow as it actually ran in production	Highest
API test run output (Bruno, Postman, newman)	The flow as it runs in the tested environment	High
OpenAPI contract plus event catalogue	The flow as designed and published	High
Source of the orchestrating service	The flow as implemented, minus runtime branches	Medium
A requirements document	The flow as someone once intended it	Low
A description typed from memory	A plausible fiction	None

The two highest rows are the interesting ones, and both are available to any analyst with read access to a log tool or a collection runner. They get their own articles, drawing from Splunk and Datadog and drawing from Bruno and Postman runs, because they are what turns a diagram from an opinion into a piece of evidence.

Before any of it goes into a model, classify it. Endpoint paths, service names, event names, HTTP status codes, and ISO 20022 message types are shape, and shape is safe. Payload values, customer names, IBANs, live tokens, and internal hostnames are content, and content gets redacted first. Diagrams survive redaction almost perfectly, because a diagram needs the shape of the flow and not the values inside it. The wider version of that judgment call is in AI guardrails for analysts.

The two files that make AI diagramming repeatable

One off prompting gives you one off quality. Two small files turn it into a process you can hand to a colleague.

The context pack

A short Markdown file describing the system in the model’s terms: the participants and their canonical names, the identifier that correlates a transaction end to end, the transport between each pair, and the status vocabulary. Mine for a payments platform runs about forty lines:

# Northline Pay: diagram context

## Participants (use these exact names)
Channel, Ingestion API, Kafka, Processor, Ledger DB, Sanctions, Network

## Correlation
Every transaction carries a `uetr` (UUID v4). Logs, events, and API
responses all include it. Correlate on `uetr`, never on timestamp.

## Transports
Channel -> Ingestion API      HTTPS/JSON
Ingestion API -> Kafka        event `payment.received`
Kafka -> Processor            consume
Processor -> Network          ISO 20022 pacs.008 over SWIFT
Network -> Processor          pacs.002 status report

## Status vocabulary
RCVD accepted for processing, ACCP validated, ACSP in settlement,
ACSC settled, RJCT rejected with a reason code.

Paste that above any diagram request and the model stops inventing a “PaymentService” that does not exist, and stops labelling your Kafka publish as an HTTP call. The technique generalises well past diagrams, and I cover it properly in context engineering for analysts.

The house style file

Every team draws differently, and a model has no way to guess yours. Write the rules down once:

# Diagram house style

- Mermaid `sequenceDiagram` for flows, `flowchart TD` for decisions,
  `stateDiagram-v2` for lifecycles. No other types without a reason.
- `autonumber` on every sequence diagram.
- Solid arrows `->>` for requests, dashed `-->>` for responses.
- Every failure path in an `alt` block. Never draw a happy path alone.
- Async hops get a `Note over` with the observed p95 latency.
- Participant names come from the context pack, verbatim.
- Max 7 participants. If it needs more, split the diagram.

These two files are the difference between AI that produces a diagram and AI that produces your team’s diagram. Keep them in the repo next to the diagrams.

The generation and review loop

Four steps, and the third one is the one people skip.

1. Choose the participants yourself. This is the authorship step and it does not delegate. A model given a log export will happily draw every service that appears, including the config sidecar and the metrics agent. You decide which six matter to this audience. An operations runbook diagram and a steering committee diagram describe the same system with different participants, and choosing wrong is the most common reason a diagram gets ignored.

2. Generate. Context pack, house style, evidence, and one instruction: transcribe this into a Mermaid sequence diagram, do not infer any call that is not present in the evidence, and list separately anything ambiguous.

That last clause matters more than it looks. Without it the model fills gaps silently. With it you get a diagram plus a short list like “the retry at 10:42:03 has no matching outbound call in the export; it may be an internal retry or a missing log line.” That list is an analyst’s work queue.

3. Verify against the evidence, not against your intuition. Read the diagram back arrow by arrow and find each one in the source. This takes four minutes and it is the entire quality gate. Models reverse the direction of a response arrow, collapse two retries into one call, and occasionally invent a database write that is implied but never logged. A diagram that survives this check is trustworthy in a way a hand drawn one usually is not, because every arrow has a receipt.

4. Commit it next to what it describes. docs/diagrams/payment-flow.md, in the same repo as the service. Not a wiki page. The wiki can embed it; the source of truth lives with the code.

How do you maintain diagrams instead of redrawing them?

You make drift visible automatically. Two mechanisms, both cheap.

Regenerate and diff. A scheduled job pulls yesterday’s successful transactions from your log tool, regenerates the sequence diagram, and diffs it against the committed file. A clean diff means the documented flow is still the real flow. A diff means one of two things, and both are worth knowing: either the system changed and nobody updated the diagram, or something is happening in production that is not supposed to happen. I have found an undocumented retry loop and a fallback path that was never decommissioned this way, both real findings dressed up as documentation drift.

Review the diagram in the PR. Add the diagram file to the code owners rule for the service. Now a developer who adds a call to a new service sees the diagram file flagged as unchanged and has to justify it. This is the same discipline as keeping a traceability matrix honest, applied to pictures.

There is a third habit worth building. When an incident review produces a timeline, regenerate the diagram from the incident window and attach it to the postmortem. It takes five minutes, it is exact, and it explains the failure to non technical stakeholders better than any paragraph. Turning raw log output into that picture is the technique in drawing sequence diagrams from Splunk and Datadog.

Drawing for the audience that cannot read a sequence diagram

A sequence diagram is a technical artifact. Half the people who need to understand the flow will not read one, and that is not their failing.

The move is to generate two diagrams from one source. Keep the evidence and the context pack; change only the instruction:

• For the delivery team: a sequenceDiagram with every service, every status code, every alt branch, and latency notes.
• For the business: a flowchart LR with five boxes, no protocol names, no status codes, and failure branches labelled in business language (“payment rejected, customer notified”) rather than RJCT AC04.

Same underlying truth, two abstractions, both regenerated when the system changes. This is where AI earns its place most obviously, because producing the second diagram by hand always felt like duplicated effort and so it never got done. For a business audience that needs swimlanes and handoffs rather than arrows, the right format is BPMN, which is its own workflow.

What the model is genuinely bad at

Worth knowing before you trust it further than you should.

• Choosing the level of abstraction. It has no idea who the reader is. You decide.
• Layout on anything large. Past roughly a dozen nodes, generated flowchart layout gets tangled. Split the diagram instead of fighting it.
• Silent gap filling. If the evidence is incomplete it produces a complete diagram anyway. This is why the “list anything ambiguous” instruction is not optional.
• Holding the whole system at once. Ask for one flow at a time. A single request for “the full architecture” produces something that looks authoritative and is subtly wrong throughout.
• Knowing what changed. It cannot tell you the diagram is stale. Only the regenerate and diff job can.

None of these are reasons to skip the tooling. They are the reasons the analyst stays in the loop, and they map cleanly onto the skills that make a technical business analyst useful in the first place: choosing the boundary, demanding evidence, and noticing the missing branch. The wider set of those skills is mapped in The Technical Skills Guide for BAs.

The takeaway

The value of AI in diagramming is not the drawing. It is that regenerating a diagram now costs a few minutes, which finally makes “keep the diagram current” a realistic policy rather than an aspiration. Store diagrams as text in git, generate them from artifacts rather than prose, verify every arrow against the evidence, and add a job that regenerates and diffs on a schedule.

Do that and your diagrams become the most reliable documentation your team has, because they are the only documentation rebuilt from what the system actually did. Start with the Mermaid types an analyst actually needs, then pick your evidence source: logs or test runs. For the prompt library behind all of it, see The Tech BA Prompt Toolkit, or browse everything at The Tech BA Toolkit.

Ahmed is a Senior Technical Business Analyst with 10+ years in banking and payments. He builds practical guides and tools for analysts at The Tech BA Toolkit.

Tags: Business Analysis, AI, Documentation, Systems Analysis, Mermaid