Diagram Tools Reference

Overview

Text-based diagramming tools let you define diagrams in code, version control them, and generate images. This reference covers the major tools and when to use each.

Tool Comparison

Tool Output Best For Pros Cons

D2

SVG

Flowcharts, architecture

Animated lines, dark themes, modern syntax

Newer, smaller ecosystem

Mermaid

SVG

Flowcharts, sequences, Git graphs

Markdown integration, GitHub/GitLab native

Limited styling, no animation

PlantUML

PNG/SVG

UML, enterprise diagrams

Full UML support, extensive

Verbose syntax, Java dependency

Graphviz

SVG/PNG

Graph theory, dependency trees

Fast, foundational, widely supported

Minimal styling, dated look

Diagrams

PNG

Cloud architecture

Real cloud icons (AWS, GCP, K8s)

Python only, limited layouts

Structurizr

SVG/PNG

C4 architecture model

Structured approach, workspace model

Learning curve, specific use case

Excalidraw

SVG/PNG

Hand-drawn sketches

Collaborative, whiteboard feel

Not text-based (JSON export)

Kroki

Various

Unified rendering server

Supports 20+ formats via API

Requires server/container

When to Use What

Need animated flows?          -> D2
GitHub/GitLab README?         -> Mermaid
Enterprise UML?               -> PlantUML
Dependency graphs?            -> Graphviz
Cloud architecture?           -> Diagrams (Python)
C4 model?                     -> Structurizr
Quick whiteboard sketch?      -> Excalidraw
Render any format via API?    -> Kroki

Mermaid

Markdown-native diagrams. Renders in GitHub, GitLab, Notion, Obsidian.

Installation

# CLI (Node.js)
npm install -g @mermaid-js/mermaid-cli

# Generate SVG
mmdc -i diagram.mmd -o diagram.svg

# Generate PNG
mmdc -i diagram.mmd -o diagram.png

Flowchart

flowchart LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Process]
    B -->|No| D[Skip]
    C --> E[End]
    D --> E
Rendered
+---------+     +----------+     +---------+
| Start   |---->| Decision |---->| Process |----+
+---------+     +----------+     +---------+    |
                   |                            |
                   | No                         |
                   v                            v
              +--------+                  +-------+
              |  Skip  |----------------->|  End  |
              +--------+                  +-------+

Direction Options

flowchart TB    %% Top to Bottom
flowchart BT    %% Bottom to Top
flowchart LR    %% Left to Right
flowchart RL    %% Right to Left

Node Shapes

flowchart LR
    A[Rectangle]
    B(Rounded)
    C([Stadium])
    D[[Subroutine]]
    E[(Database)]
    F((Circle))
    G{Diamond}
    H{{Hexagon}}
    I[/Parallelogram/]
    J[\Parallelogram Alt\]
    K[/Trapezoid\]

Sequence Diagram

sequenceDiagram
    participant C as Client
    participant S as Server
    participant D as Database

    C->>S: HTTP Request
    activate S
    S->>D: Query
    activate D
    D-->>S: Results
    deactivate D
    S-->>C: Response
    deactivate S

Sequence Arrow Types

sequenceDiagram
    A->>B: Solid line, arrow
    A-->>B: Dotted line, arrow
    A-xB: Solid line, cross
    A--xB: Dotted line, cross
    A-)B: Solid line, open arrow
    A--)B: Dotted line, open arrow

Class Diagram

classDiagram
    class Animal {
        +String name
        +int age
        +makeSound()
    }
    class Dog {
        +String breed
        +bark()
    }
    Animal <|-- Dog

State Diagram

stateDiagram-v2
    [*] --> Idle
    Idle --> Processing: Start
    Processing --> Complete: Done
    Processing --> Error: Fail
    Complete --> [*]
    Error --> Idle: Retry

Entity Relationship

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains
    PRODUCT ||--o{ LINE-ITEM : "is in"

    CUSTOMER {
        int id PK
        string name
        string email
    }
    ORDER {
        int id PK
        int customer_id FK
        date created
    }

Git Graph

gitGraph
    commit
    commit
    branch develop
    checkout develop
    commit
    commit
    checkout main
    merge develop
    commit

Gantt Chart

gantt
    title Project Timeline
    dateFormat YYYY-MM-DD
    section Phase 1
    Research       :a1, 2026-01-01, 30d
    Design         :a2, after a1, 20d
    section Phase 2
    Development    :a3, after a2, 60d
    Testing        :a4, after a3, 20d

Pie Chart

pie title Traffic Sources
    "Organic" : 45
    "Direct" : 30
    "Referral" : 15
    "Social" : 10

Styling

flowchart LR
    A[Start]:::green --> B[Process]:::blue --> C[End]:::green

    classDef green fill:#50fa7b,stroke:#0d0d0d,color:#0d0d0d
    classDef blue fill:#89b4fa,stroke:#0d0d0d,color:#0d0d0d

Link Styling

flowchart LR
    A --> B
    B --> C

    linkStyle 0 stroke:#ff5555,stroke-width:2px
    linkStyle 1 stroke:#50fa7b,stroke-width:2px,stroke-dasharray:5

Subgraphs

flowchart TB
    subgraph Frontend
        A[React App]
        B[Next.js]
    end
    subgraph Backend
        C[API Server]
        D[Database]
    end
    A --> C
    B --> C
    C --> D

Mermaid in Markdown

```mermaid
flowchart LR
    A --> B --> C
```

Works natively in:

  • GitHub README/Issues/PRs

  • GitLab

  • Notion

  • Obsidian

  • VS Code (with extension)

PlantUML

Enterprise-grade UML diagrams. Verbose but comprehensive.

Installation

# Arch Linux
sudo pacman -S plantuml

# Or via Java JAR
java -jar plantuml.jar diagram.puml

# Generate PNG
plantuml diagram.puml

# Generate SVG
plantuml -tsvg diagram.puml

Sequence Diagram

@startuml
actor User
participant "Web App" as Web
participant "API Server" as API
database "PostgreSQL" as DB

User -> Web: Login Request
activate Web
Web -> API: POST /auth/login
activate API
API -> DB: SELECT user
activate DB
DB --> API: User data
deactivate DB
API --> Web: JWT Token
deactivate API
Web --> User: Redirect to Dashboard
deactivate Web
@enduml

Sequence Diagram Features

@startuml
' Arrows
A -> B: Solid
A --> B: Dashed
A ->> B: Thin
A -\ B: Half arrow
A ->x B: Lost message
A <-> B: Bidirectional

' Activation
activate A
A -> B: Call
activate B
B --> A: Return
deactivate B
deactivate A

' Notes
note left of A: Left note
note right of B: Right note
note over A,B: Spanning note

' Grouping
alt success
    A -> B: OK
else failure
    A -> B: Error
end

loop 10 times
    A -> B: Retry
end
@enduml

Class Diagram

@startuml
class User {
    -id: int
    -name: String
    -email: String
    +login(): boolean
    +logout(): void
}

class Order {
    -id: int
    -total: decimal
    +calculate(): decimal
}

class Product {
    -id: int
    -name: String
    -price: decimal
}

User "1" -- "*" Order: places
Order "*" -- "*" Product: contains
@enduml

Class Relationships

@startuml
' Extension (inheritance)
Parent <|-- Child

' Composition (strong ownership)
Company *-- Department

' Aggregation (weak ownership)
Team o-- Player

' Association
User -- Order

' Dependency
Client ..> Service

' Implementation
Interface <|.. Implementation
@enduml

Use Case Diagram

@startuml
left to right direction

actor Customer
actor Admin

rectangle "Online Store" {
    Customer -- (Browse Products)
    Customer -- (Add to Cart)
    Customer -- (Checkout)
    Admin -- (Manage Inventory)
    Admin -- (Process Orders)
    (Checkout) ..> (Payment) : <<include>>
}
@enduml

Activity Diagram

@startuml
start
:Receive Order;
if (In Stock?) then (yes)
    :Process Order;
    :Ship Order;
else (no)
    :Notify Customer;
    :Backorder;
endif
:Send Confirmation;
stop
@enduml

Component Diagram

@startuml
package "Frontend" {
    [React App] as React
    [Redux Store] as Redux
}

package "Backend" {
    [API Gateway] as Gateway
    [Auth Service] as Auth
    [Order Service] as Order
}

database "PostgreSQL" as DB

React --> Gateway : REST
Gateway --> Auth
Gateway --> Order
Order --> DB
@enduml

Deployment Diagram

@startuml
node "Web Server" {
    [Nginx]
    [Node.js App]
}

node "Database Server" {
    database "PostgreSQL"
}

node "Cache Server" {
    [Redis]
}

[Nginx] --> [Node.js App]
[Node.js App] --> [PostgreSQL]
[Node.js App] --> [Redis]
@enduml

State Diagram

@startuml
[*] --> Idle

Idle --> Processing : start
Processing --> Complete : success
Processing --> Error : failure
Complete --> [*]
Error --> Idle : retry
Error --> [*] : abort
@enduml

Styling

@startuml
skinparam backgroundColor #1e1e2e
skinparam defaultFontColor #cdd6f4
skinparam classFontColor #cdd6f4
skinparam classBackgroundColor #313244
skinparam classBorderColor #585b70
skinparam arrowColor #89b4fa
skinparam noteBackgroundColor #45475a
skinparam noteBorderColor #585b70

class Example {
    +method()
}
@enduml

Themes

@startuml
!theme cyborg
' Available themes: cerulean, cyborg, materia, minty, sandstone, etc.

class Example
@enduml

Graphviz (DOT)

The foundational graph visualization tool. Simple, fast, widely supported.

Installation

# Arch Linux
sudo pacman -S graphviz

# Generate SVG
dot -Tsvg graph.dot -o graph.svg

# Generate PNG
dot -Tpng graph.dot -o graph.png

# Different layout engines
dot -Tsvg graph.dot -o graph.svg      # Hierarchical (default)
neato -Tsvg graph.dot -o graph.svg    # Spring model
fdp -Tsvg graph.dot -o graph.svg      # Force-directed
circo -Tsvg graph.dot -o graph.svg    # Circular
twopi -Tsvg graph.dot -o graph.svg    # Radial

Basic Graph

digraph G {
    A -> B
    B -> C
    B -> D
    C -> E
    D -> E
}

Undirected Graph

graph G {
    A -- B
    B -- C
    B -- D
}

Node Attributes

digraph G {
    // Node shapes
    A [shape=box]
    B [shape=ellipse]
    C [shape=diamond]
    D [shape=circle]
    E [shape=cylinder]
    F [shape=hexagon]
    G [shape=parallelogram]
    H [shape=folder]

    // Styling
    I [shape=box, style=filled, fillcolor="#50fa7b", fontcolor="#0d0d0d"]
    J [shape=box, style="filled,rounded", fillcolor="#89b4fa"]
    K [shape=box, style=dashed]
    L [shape=box, penwidth=3, color="#ff5555"]
}

Edge Attributes

digraph G {
    A -> B [label="normal"]
    A -> C [style=dashed, label="dashed"]
    A -> D [style=dotted, label="dotted"]
    A -> E [style=bold, label="bold"]
    A -> F [color="#ff5555", penwidth=2, label="styled"]
    A -> G [arrowhead=none, label="no arrow"]
    A -> H [dir=both, label="bidirectional"]
}

Arrow Shapes

digraph G {
    A -> B [arrowhead=normal]
    A -> C [arrowhead=dot]
    A -> D [arrowhead=diamond]
    A -> E [arrowhead=box]
    A -> F [arrowhead=vee]
    A -> G [arrowhead=none]
    A -> H [arrowhead=crow]
}

Subgraphs (Clusters)

digraph G {
    subgraph cluster_frontend {
        label="Frontend"
        style=filled
        fillcolor="#313244"
        fontcolor="#cdd6f4"
        React
        Redux
    }

    subgraph cluster_backend {
        label="Backend"
        style=filled
        fillcolor="#313244"
        fontcolor="#cdd6f4"
        API
        Auth
        Database
    }

    React -> API
    API -> Auth
    API -> Database
}

Ranks (Alignment)

digraph G {
    rankdir=LR  // Left to Right

    // Force same rank (horizontal alignment)
    {rank=same; A; B; C}
    {rank=same; D; E; F}

    A -> D
    B -> E
    C -> F
}

Record Shapes (Tables)

digraph G {
    node [shape=record]

    User [label="{User|+id: int\l+name: string\l+email: string\l|+login()\l+logout()\l}"]
    Order [label="{Order|+id: int\l+total: decimal\l|+calculate()\l}"]

    User -> Order [label="places"]
}

HTML Labels

digraph G {
    node [shape=none]

    A [label=<
        <TABLE BORDER="0" CELLBORDER="1" CELLSPACING="0">
            <TR><TD BGCOLOR="#89b4fa"><B>Header</B></TD></TR>
            <TR><TD>Row 1</TD></TR>
            <TR><TD>Row 2</TD></TR>
        </TABLE>
    >]
}

Dark Theme

digraph G {
    bgcolor="#1e1e2e"
    node [
        shape=box,
        style="filled,rounded",
        fillcolor="#313244",
        fontcolor="#cdd6f4",
        color="#585b70"
    ]
    edge [
        color="#89b4fa",
        fontcolor="#a6adc8"
    ]

    A -> B -> C
}

Diagrams (Python)

Cloud architecture diagrams with real provider icons.

Installation

pip install diagrams

# Requires Graphviz
sudo pacman -S graphviz

Basic AWS Diagram

from diagrams import Diagram
from diagrams.aws.compute import EC2
from diagrams.aws.database import RDS
from diagrams.aws.network import ELB

with Diagram("AWS Architecture", show=False, filename="aws"):
    lb = ELB("Load Balancer")
    web1 = EC2("Web Server 1")
    web2 = EC2("Web Server 2")
    db = RDS("Database")

    lb >> [web1, web2] >> db

Kubernetes Diagram

from diagrams import Diagram, Cluster
from diagrams.k8s.compute import Pod, Deployment
from diagrams.k8s.network import Service, Ingress
from diagrams.k8s.storage import PersistentVolumeClaim

with Diagram("K8s Architecture", show=False, filename="k8s"):
    ingress = Ingress("ingress")

    with Cluster("Namespace: app"):
        svc = Service("service")
        with Cluster("Deployment"):
            pods = [Pod("pod-1"), Pod("pod-2"), Pod("pod-3")]
        pvc = PersistentVolumeClaim("storage")

    ingress >> svc >> pods
    pods >> pvc

Multi-Cloud

from diagrams import Diagram, Cluster
from diagrams.aws.compute import EC2
from diagrams.gcp.compute import GCE
from diagrams.azure.compute import VM

with Diagram("Multi-Cloud", show=False, filename="multicloud"):
    with Cluster("AWS"):
        aws = EC2("EC2")

    with Cluster("GCP"):
        gcp = GCE("GCE")

    with Cluster("Azure"):
        azure = VM("VM")

    aws - gcp - azure

Available Providers

from diagrams.aws import *        # AWS
from diagrams.gcp import *        # Google Cloud
from diagrams.azure import *      # Azure
from diagrams.k8s import *        # Kubernetes
from diagrams.onprem import *     # On-premises (Docker, Nginx, etc.)
from diagrams.generic import *    # Generic shapes
from diagrams.programming import *  # Languages
from diagrams.saas import *       # SaaS (Slack, GitHub, etc.)

Edge Labels

from diagrams import Diagram, Edge
from diagrams.aws.compute import EC2
from diagrams.aws.database import RDS

with Diagram("With Labels", show=False):
    web = EC2("Web")
    db = RDS("DB")

    web >> Edge(label="SQL", color="red") >> db

Structurizr (C4 Model)

Architecture diagrams using the C4 model (Context, Container, Component, Code).

DSL Syntax

workspace {
    model {
        user = person "User" "A user of the system"

        softwareSystem = softwareSystem "Software System" {
            webapp = container "Web Application" "Delivers content" "Next.js"
            api = container "API" "Backend services" "Node.js"
            db = container "Database" "Stores data" "PostgreSQL"
        }

        user -> webapp "Uses"
        webapp -> api "Calls"
        api -> db "Reads/Writes"
    }

    views {
        systemContext softwareSystem {
            include *
            autolayout lr
        }

        container softwareSystem {
            include *
            autolayout lr
        }
    }
}

Running Structurizr

# Structurizr Lite (Docker)
docker run -it --rm -p 8080:8080 \
    -v $(pwd):/usr/local/structurizr \
    structurizr/lite

# Then open http://localhost:8080

Kroki

Universal diagram server. Renders 20+ formats via HTTP API.

Running Kroki

# Docker
docker run -d -p 8000:8000 yuzutech/kroki

# Docker Compose (with all companions)
# kroki + mermaid + bpmn + excalidraw
docker-compose up -d

API Usage

# Encode diagram as base64
echo "digraph G { A -> B }" | base64

# GET request
curl "http://localhost:8000/graphviz/svg/ZGlncmFwaCBHIHsgQSAtPiBCIH0K"

# POST request
curl -X POST "http://localhost:8000/graphviz/svg" \
    -H "Content-Type: text/plain" \
    -d "digraph G { A -> B }"

Supported Formats

BlockDiag, SeqDiag, ActDiag, NwDiag, PacketDiag, RackDiag
BPMN
Bytefield
C4 (PlantUML)
D2
Ditaa
Erd
Excalidraw
GraphViz
Mermaid
Nomnoml
Pikchr
PlantUML
Structurizr
SvgBob
UMlet
Vega, Vega-Lite
WaveDrom
WireViz

Antora Integration

In antora-playbook.yml:

asciidoc:
  extensions:
    - asciidoctor-kroki
  attributes:
    kroki-server-url: http://localhost:8000

Then in AsciiDoc:

[mermaid]
....
flowchart LR
    A --> B --> C
....

Quick Reference Table

Task Best Tool Command

Flowchart with animation

D2

d2 --theme 200 flow.d2 flow.svg

GitHub README diagram

Mermaid

Native in markdown code block

UML sequence diagram

PlantUML

plantuml -tsvg seq.puml

Dependency graph

Graphviz

dot -Tsvg deps.dot -o deps.svg

AWS architecture

Diagrams

python diagram.py

C4 architecture

Structurizr

Docker + browser

Any format via API

Kroki

curl localhost:8000/…​;

File Extensions

Tool Extension

D2

.d2

Mermaid

.mmd, .mermaid

PlantUML

.puml, .plantuml

Graphviz

.dot, .gv

Diagrams (Python)

.py

Structurizr

.dsl

Recommendation

For most use cases in domus-*:

  1. D2 - Primary tool (animations, dark themes, modern)

  2. Mermaid - When you need GitHub/GitLab rendering

  3. PlantUML - When you need formal UML

  4. Diagrams - When showing cloud architecture with icons

Graphviz is foundational but dated. Use D2 instead for modern output.