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

Architecture Diagram (architecture-beta)

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

architecture-beta
    group onprem(server)[On-Premises]
    group cloud(cloud)[Azure Cloud]

    service ad(server)[Active Directory] in onprem
    service agent(server)[Sync Agent] in onprem
    service entra(cloud)[Entra ID] in cloud

    ad:R --> L:agent
    agent:R --> L:entra

• Groups define boundaries; services go inside groups
• Edge markers: L, R, T, B for left, right, top, bottom
• Icons: server, cloud, database, disk, internet
• Declare all services before referencing them in edges

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.