Mermaid for Analysts: The Six Diagram Types You Actually Need

Mermaid is a plain text diagram syntax that renders to SVG in GitHub, GitLab, Notion, Obsidian, and VS Code with no plugin. Six of its diagram types cover almost everything an analyst draws: sequenceDiagram for flows across services, flowchart for decision logic, stateDiagram-v2 for lifecycles, erDiagram for data, C4Context for boundaries, and gantt for plans.

I stopped drawing diagrams in a graphical tool about three years ago and have not gone back. Not because Mermaid is prettier, it is not, but because a Mermaid diagram sits in the same repository as the specification, shows up in the pull request that changed the behavior, and takes fifteen seconds to update. A diagram that takes fifteen seconds to update is a diagram that stays true.

This is the reference I actually use. Six types, the syntax worth memorizing, and the judgment call about which one answers your question. The system around it, generating and maintaining these with AI, is in diagrams as code with AI.

Which Mermaid diagram type answers which question?

Picking the type is picking the question. Get this wrong and the diagram is technically correct and useless.

Question	Type	Typical analyst use
Who calls whom, in what order?	sequenceDiagram	An API flow across services, an incident timeline
What decides what, inside one process?	flowchart	Validation logic, a routing decision, a business rule
What can legally happen next?	stateDiagram-v2	Payment status lifecycle, order or case states
How is the data related?	erDiagram	Table relationships, cardinality, a data dictionary
What is inside and outside the boundary?	C4Context	System context before a design discussion
When does what happen, and what blocks it?	gantt	Migration phases, release dependencies

If you cannot name the question in one sentence, the diagram is not ready to draw yet. That is not a Mermaid problem.

sequenceDiagram: the one you will use most

A sequence diagram reads top to bottom as time, with a lifeline per participant and an arrow per message. For anything that crosses more than one service, this is the default.

sequenceDiagram
    autonumber
    participant C as Channel
    participant I as Ingestion API
    participant K as Kafka
    participant P as Processor
    participant N as Network

    C->>I: POST /payments {uetr}
    I-->>C: 202 Accepted (RCVD)
    I->>K: publish payment.received
    K->>P: consume payment.received
    P->>N: pacs.008
    alt accepted
        N-->>P: pacs.002 ACSP
        P->>P: status = ACSP
    else rejected
        N-->>P: pacs.002 RJCT (AC04)
        P->>P: status = RJCT
    end
    C->>I: GET /payments/{uetr}
    I-->>C: 200 {status}

The syntax worth knowing:

• autonumber numbers every message, which makes a diagram citable in a ticket (“step 6 is where it fails”).
• ->> is a solid arrow, a request. -->> is dashed, a response. Keep that convention and readers stop having to ask.
• alt ... else ... end is the branch. opt ... end is an optional step. loop ... end is repetition, for polling or retries.
• Note over P,N: waits up to 30s annotates a hop. Use it for observed latency and for anything asynchronous.
• participant I as Ingestion API gives a short alias for the arrows and a readable label for the reader.
• activate P and deactivate P draw the processing bar if you want it. Most of the time you do not.

The discipline, not the syntax, is what makes these good: never ship one with only a happy path. The full method is in sequence diagrams for business analysts, and drawing one from real production evidence is in sequence diagrams from Splunk and Datadog logs.

flowchart: decision logic inside one process

Use a flowchart when the interesting thing is the branching, not the handoffs. Direction is TD (top down) or LR (left to right); LR reads better for anything with more than four steps.

flowchart TD
    A[pain.001 received] --> B{Schema valid?}
    B -->|No| R1[Reject: FF01]
    B -->|Yes| C{IBAN check digits ok?}
    C -->|No| R2[Reject: AC01]
    C -->|Yes| D{Amount within limit?}
    D -->|No| R3[Refer to manual review]
    D -->|Yes| E{Sanctions hit?}
    E -->|Yes| R4[Hold for investigation]
    E -->|No| F[Accept: ACCP]

Node shapes carry meaning, so use them consistently: [square] for a step, {diamond} for a decision, ([rounded]) for a start or end, [(cylinder)] for a datastore. Edge labels go in pipes: -->|No|.

Two things to watch. First, a flowchart with more than a dozen nodes becomes a maze; split it and link the pieces. Second, a flowchart hides who does the work, which is exactly why it is the wrong choice for a distributed transaction. When the reader needs to know which service rejected the payment, you need a sequence diagram.

For a business audience, flowchart LR with five boxes and no jargon is often the single most useful artifact you can produce, and it takes a minute. Decision tables cover the same ground with more rigour when the combinations get dense, which I cover in decision tables.

stateDiagram-v2: what can happen next

A state diagram answers a different question from a flowchart: not “what does the system decide” but “what states can this entity be in, and which transitions are legal.” For anything with a status field, this is the diagram that finds bugs.

stateDiagram-v2
    [*] --> RCVD: payment submitted
    RCVD --> ACCP: validation passed
    RCVD --> RJCT: validation failed
    ACCP --> ACSP: sent to network
    ACSP --> ACSC: settlement confirmed
    ACSP --> RJCT: network rejected
    ACSC --> RTRN: return received
    RJCT --> [*]
    RTRN --> [*]
    ACSC --> [*]

Draw this for any status field in your domain and then ask the two questions that matter: which transitions are missing, and which ones are possible in the code but should not be. On one migration this exact exercise surfaced a path from ACSC back to ACCP that existed only because a retry job re-read a stale row. Nobody had noticed because no prose document had ever listed the legal transitions. The longer treatment is in state machines for payments.

erDiagram: structure and cardinality

When the conversation is about data rather than behavior, the entity relationship diagram settles arguments about cardinality faster than any table.

erDiagram
    CUSTOMER ||--o{ ACCOUNT : holds
    ACCOUNT ||--o{ PAYMENT : originates
    PAYMENT ||--|| PAYMENT_STATUS : has
    PAYMENT ||--o{ STATUS_HISTORY : records
    PAYMENT {
        uuid uetr PK
        string debtor_iban
        decimal amount
        string currency
        string status FK
    }

The cardinality notation is the point: || is exactly one, o{ is zero or more, |{ is one or more. Written on both sides of the relationship it forces the question everyone avoids, can a payment exist without an account, and the answer usually reveals a requirement. Pair it with a data dictionary and you have the full data specification.

C4Context and gantt: the two that round it out

C4Context draws the system boundary: your system in the middle, the people and external systems around it, and nothing about the internals. It is the right first diagram on any new project, because arguing about what is outside the boundary is how scope gets agreed.

C4Context
    Person(customer, "Customer", "Initiates payments")
    System(pay, "Northline Pay", "Payment processing platform")
    System_Ext(network, "Clearing Network", "ISO 20022 over SWIFT")
    System_Ext(sanctions, "Sanctions Screening", "Third party provider")

    Rel(customer, pay, "Submits payment", "HTTPS")
    Rel(pay, sanctions, "Screens party", "REST")
    Rel(pay, network, "Sends pacs.008", "SWIFT")

The method behind it, and why the boundary matters more than the boxes, is in system context diagrams.

gantt is the one non technical diagram in the set, and it is genuinely useful for a migration plan because dependencies are explicit:

gantt
    title ISO 20022 migration
    dateFormat YYYY-MM-DD
    section Analysis
    Message mapping      :done, map, 2026-01-06, 30d
    Gap register         :done, gap, after map, 15d
    section Build
    Translator service   :active, tr, after gap, 45d
    section Test
    Coexistence testing  :test, after tr, 30d

Where does Mermaid render?

This is the practical question that decides whether your team adopts it.

Platform	Support
GitHub: Markdown, issues, PRs, wikis	Native
GitLab and Azure DevOps wikis	Native
Notion, Obsidian, Slack canvases	Native
VS Code	Built in preview plus a Mermaid extension
Confluence	Needs a Mermaid macro app from the marketplace
Anything else (slides, PDF, email)	Render to SVG or PNG with the mmdc command line tool

For the last row, the Mermaid CLI turns a .mmd file into an image in one command, which is what you want in a build pipeline or when a stakeholder needs it in a deck.

The rules that keep Mermaid diagrams readable

Auto layout is a trade. You give up control, you get speed and diffs. These five rules keep the trade worth it.

1. One question per diagram. If you are tempted to add a second flow, make a second diagram and link them.
2. Seven participants maximum, a dozen nodes maximum. Past that the auto layout tangles and no amount of fiddling fixes it.
3. Name participants from a fixed vocabulary. The same service must have the same name in every diagram, or search stops working and readers stop trusting.
4. Always draw the failure branch. An alt with an else, or a rejection node. A happy path drawn alone is a specification with a hole in it.
5. Put the diagram where the change happens. In the repo, next to the code or the spec, so it gets reviewed when the behavior changes.

Follow those and the diagrams stay legible without any manual layout work, which is the entire reason to use text in the first place. Templates for these alongside the rest of an analyst’s deliverables are in Real-World BA Deliverables.

The takeaway

Six Mermaid types cover the analyst’s working set: sequenceDiagram for who calls whom, flowchart for what decides what, stateDiagram-v2 for what can happen next, erDiagram for how data relates, C4Context for the boundary, and gantt for the plan. Choosing the type is choosing the question, and that is the only genuinely hard part.

Because it is text, it diffs in a pull request and a model can write and rewrite it in one pass, which is what makes the diagrams maintainable rather than archaeological. Next, see how to generate and maintain these with AI, how to build one from production logs, or how to generate one from a Bruno or Postman run. Templates and prompts are 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, Documentation, Mermaid, Systems Analysis, Diagrams