Mermaid graph diagrams for data structure visualization and algorithms

When you're documenting algorithms, explaining data structure relationships, or teaching graph theory, a plain-text diagram beats a hand-drawn sketch or a static image. Mermaid's graph syntax lets you visualize nodes, edges, and complex relationships—perfect for visualizing trees, directed acyclic graphs (DAGs), linked lists, and network topologies. This guide shows how to use Mermaid to document the data structures that drive your code.

Why visualize data structures

Data structures live in code, but their relationships are invisible. A graph diagram reveals:

• Node relationships — which data points connect to which others
• Traversal paths — how algorithms walk through the structure
• Cycles and trees — whether the graph is acyclic or has circular references
• Levels and hierarchies — parent-child relationships in trees or organizational structures
• Dependencies — which nodes depend on others (useful for topological sorting)

Instead of reading code to understand "how does a binary search tree connect?", a diagram shows it instantly.

Basic graph syntax in Mermaid

Mermaid represents graphs using a simple node-and-edge syntax:

graph TD
    A["Root"]
    B["Left Child"]
    C["Right Child"]
    D["Left-Left"]
    E["Left-Right"]
    
    A --> B
    A --> C
    B --> D
    B --> E

Each --> creates a directed edge. Use --- for undirected edges. Node labels go in square brackets and quotes.

Example: Binary search tree structure

Here's a complete binary search tree with values:

graph TD
    A["50"]
    B["30"]
    C["70"]
    D["20"]
    E["40"]
    F["60"]
    G["80"]
    
    A --> B
    A --> C
    B --> D
    B --> E
    C --> F
    C --> G

This is a standard BST where left children are smaller, right children are larger. A developer reading this immediately understands the structure—no need to trace through code.

Real-world example: dependency graph

In a software system, some components depend on others. Here's a module dependency graph:

graph LR
    Auth["Auth Module"]
    DB["Database"]
    API["API Layer"]
    Cache["Cache"]
    Logging["Logging"]
    
    API --> Auth
    API --> DB
    API --> Cache
    Auth --> DB
    Auth --> Logging
    DB --> Logging
    Cache --> Logging

The arrows show "depends on." This reveals:

• The API depends on auth, database, and cache (three concerns to test).
• Auth depends on the database (coupling point).
• Logging is a leaf—nothing else depends on it, so it can be tested in isolation.

A developer reviewing this knows where to mock, where to integrate, and where bottlenecks may hide.

Advanced: labeled edges and colors

For complex graphs, add labels to edges and color nodes by type:

graph TD
    A["User Service"]:::service
    B["Order Service"]:::service
    C["Payment Service"]:::service
    D["Database"]:::storage
    E["Cache"]:::storage
    F["Queue"]:::storage
    
    A -->|reads/writes| D
    A -->|caches| E
    B -->|reads/writes| D
    B -->|enqueues| F
    C -->|consumes| F
    C -->|calls| A
    
    classDef service fill:#4CAF50,stroke:#2E7D32,color:#fff
    classDef storage fill:#2196F3,stroke:#1565C0,color:#fff

Colors group nodes by type (service vs. storage). Edge labels clarify the relationship. This is much more readable than a wall of text describing "Service A talks to Database B."

Graph algorithms: breadth-first search (BFS)

Visualizing a BFS traversal helps explain the algorithm:

graph TD
    A["Start: A"]
    B["Visit B"]
    C["Visit C"]
    D["Visit D"]
    E["Visit E"]
    F["Visit F"]
    
    A -->|Queue: B, C| B
    B -->|Queue: D, E| C
    C -->|Queue: F| D
    D -->|Dequeue| E
    E -->|Dequeue| F
    F -->|Done|G["Visited: A-B-C-D-E-F"]

The diagram shows the order: level 0 (A), level 1 (B, C), level 2 (D, E, F). The queue order is explicit, making the algorithm easier to follow.

Linked list visualization

Linked lists are a classic data structure; here's how to show them:

graph LR
    A["Node 1<br/>data: 10<br/>next: →"]
    B["Node 2<br/>data: 20<br/>next: →"]
    C["Node 3<br/>data: 30<br/>next: →"]
    D["None<br/>end"]
    
    A --> B
    B --> C
    C --> D

Each node shows its data and a pointer to the next. This is how a developer reads a linked list implementation.

Forest: multiple trees

Some algorithms work on forests (multiple disconnected trees). Here's an example with three trees:

graph TD
    subgraph Tree1["Tree 1"]
        A["1"]
        B["2"]
        C["3"]
        A --> B
        A --> C
    end
    
    subgraph Tree2["Tree 2"]
        D["4"]
        E["5"]
        D --> E
    end
    
    subgraph Tree3["Tree 3"]
        F["6"]
    end

Subgraphs group each tree. A union-find algorithm, for example, merges trees by connecting root nodes—this diagram makes that clear.

Comparison table: when to use graph diagrams

Use case	Why a graph diagram helps
Teaching binary search trees	Show the structure; students see insert/delete balance visually
Documenting API dependencies	Reveal coupling; identify services that should be decoupled
Explaining a pathfinding algorithm (A*, Dijkstra)	Trace the traversal order step-by-step
Visualizing inheritance hierarchies	Show which classes inherit from which
Modeling a state machine with many states	Show transitions between states and cycles
Documenting a database schema with foreign keys	Show which tables reference which (like an ER diagram)

Best practices for graph visualization

1. Keep nodes labeled simply — use variable names or brief descriptions, not full function signatures.
2. Use consistent edge directions — all arrows should point the same semantic way (e.g., "depends on" always points left-to-right).
3. Avoid crossing edges when possible — reorder nodes to minimize visual clutter.
4. Color by category — use colors to group node types (services, storage, data structures).
5. Annotate edges for complex relationships — label edges to clarify the nature of the connection.
6. Break large graphs into subgraphs — if you have 20+ nodes, split by layer, module, or type.
7. Test readability — can someone unfamiliar with the code understand the structure?

FAQ

Can Mermaid handle very large graphs (100+ nodes)?
Mermaid can render large graphs, but they become hard to read. Split into multiple diagrams by layer, module, or concern. Use a tool like Graphviz or a specialized graph database visualization for truly massive graphs.

How do I show weights on edges (for weighted graphs)?
Use edge labels: A -->|weight:5| B. This works for algorithm documentation; if you need to show weights visually (thicker lines), Mermaid doesn't support it—use a dedicated visualization library.

Can I show a cycle in Mermaid?
Yes. Use directed edges that point back: A --> B --> C --> A. Mermaid will lay it out (though the rendering may be cluttered). For clarity, add a comment like "⚠️ Cycle: A→B→C→A" above the diagram.

What's the difference between a graph diagram and a flowchart in Mermaid?
Flowcharts are sequential and human-readable (start, step, decision, end). Graph diagrams are structural (nodes and edges, no inherent order). Use flowcharts for processes; use graphs for structures.

Visualize your data structures in the MermaidCreator editor. Clear structure diagrams make algorithms, dependencies, and hierarchies easier to understand and communicate.