Diagram Types

Choosing the right diagram type is the most important decision. Pick wrong and the diagram fights the content instead of clarifying it.

Flowchart

Use for: Processes, decision trees, branching logic, data pipelines, anything with steps and conditions.

flowchart TD
    A[Start] --> B{Is user provisioned?}
    B -->|Yes| C[Update attributes]
    B -->|No| D[Create user]
    C --> E[Done]
    D --> E

• Direction: TD (top-down), LR (left-right), RL, BT
• Node shapes: [rectangle], {diamond/decision}, ([stadium]), [[subroutine]], [(cylinder/database)]
• Edge labels: -->|label text|

Sequence Diagram

Use for: Request/response flows, actor interactions, protocol exchanges, multi-system communication.

sequenceDiagram
    participant C as Client
    participant S as Server
    participant DB as Database
    C->>S: POST /users
    S->>DB: INSERT user
    DB-->>S: OK
    S-->>C: 201 Created

• Declare participants explicitly for stable ordering
• Solid arrows (->>) for requests, dashed (-->>) for responses
• activate/deactivate or +/- suffixes for lifelines
• Note over A,B: text for annotations

Service Topology (flowchart with subgraph)

Use for: Service topology, system boundaries, infrastructure layout, deployment architecture.

Note: Mermaid has an architecture-beta diagram type designed for this use case, but it has limited renderer support (fails in many client-side and SSG environments). Use flowchart with subgraph instead for reliable rendering.

flowchart LR
    subgraph onprem["On-Premises"]
        ad[Active Directory]
        agent[Sync Agent]
    end

    subgraph cloud["Azure Cloud"]
        entra[Entra ID]
    end

    ad --> agent
    agent --> entra

• Use subgraph name["Label"] to define boundaries
• Direction: LR (left-right) works best for topology diagrams
• Node shapes: [rectangle], [(cylinder/database)], ([stadium])
• Close each subgraph with end

State Diagram

Use for: Lifecycle states, status transitions, sync states.

stateDiagram-v2
    [*] --> Pending
    Pending --> InProgress: Start sync
    InProgress --> Completed: Success
    InProgress --> Failed: Error
    Failed --> InProgress: Retry
    Completed --> [*]

• Use stateDiagram-v2 (not v1)
• [*] for start and end states
• Keep flat before introducing nested states

ER Diagram

Use for: Data models, entity relationships, schema documentation.

erDiagram
    USER ||--o{ GROUP_MEMBERSHIP : "belongs to"
    GROUP ||--o{ GROUP_MEMBERSHIP : "contains"
    USER {
        string objectId PK
        string displayName
        string mail
    }

• Relationship operators must be exact: ||, o{, }o, |{, }|
• Keep entity definitions minimal; add attributes only when they clarify the model

Quick Selection Guide

When in doubt, start with flowchart. It handles the widest range of scenarios.