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.

• 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.

• 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.

• 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.

• 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.

• 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.