Mermaid Graph Diagram Guide: Network Topology, Dependencies, and More

# Mermaid Graph Diagram Guide: Network Topology, Dependencies, and More

The graph keyword is one of Mermaid's oldest and most versatile diagram types. It is the foundation for flowcharts, but it also handles network topology maps, dependency graphs, data lineage diagrams, and system architecture models that go beyond what a flowchart typically describes.

This guide focuses on using Mermaid graph syntax for practical engineering diagrams — network layouts, service dependencies, data pipelines, and directed acyclic graphs.

What Is a Mermaid Graph Diagram?

A Mermaid graph is a node-and-edge diagram where you declare nodes and connect them with directional links. Mermaid's layout engine handles positioning so you can focus on the relationships.

The simplest graph:

graph LR
    A[Load Balancer] --> B[Web Server]
    B --> C[Database]

Paste that into MermaidEditor.lol to see it rendered instantly.

Graph Direction Options

Mermaid supports four layout directions:

Node Shapes

Mermaid gives you a rich set of node shapes directly in graph syntax:

graph LR
    A[Rectangle: standard node]
    B(Rounded: process node)
    C([Stadium: terminal])
    D[[Subroutine]]
    E[(Database: cylinder)]
    F((Circle))
    G>Asymmetric: input]
    H{Diamond: decision}
    I{{Hexagon}}

For system diagrams, rectangles for services, cylinders for databases, and hexagons for external systems is a common pattern.

Network Topology Diagram

Network topology is one of the best uses for Mermaid graph diagrams. Here is a multi-tier web application topology:

graph TB
    Internet((Internet))
    
    subgraph DMZ
        LB[Load Balancer]
        WAF[Web Application Firewall]
    end
    
    subgraph App_Tier["Application Tier"]
        Web1[Web Server 1]
        Web2[Web Server 2]
        API[API Server]
    end
    
    subgraph Data_Tier["Data Tier"]
        Primary[(Primary DB)]
        Replica[(Read Replica)]
        Cache[(Redis Cache)]
    end
    
    Internet --> WAF
    WAF --> LB
    LB --> Web1
    LB --> Web2
    Web1 --> API
    Web2 --> API
    API --> Primary
    API --> Cache
    Primary --> Replica

Subgraphs create visual boundaries around logical groups. This makes it easy to show network zones, microservice clusters, or organizational boundaries.

Service Dependency Graph

For microservices, a dependency graph shows which services call which:

graph LR
    Gateway[API Gateway]
    
    Auth[Auth Service]
    Users[Users Service]
    Orders[Orders Service]
    Payments[Payments Service]
    Notifications[Notifications Service]
    
    Gateway --> Auth
    Gateway --> Users
    Gateway --> Orders
    Orders --> Payments
    Orders --> Users
    Payments --> Notifications
    Users --> Notifications

This is useful for onboarding documentation, architecture decision records, and incident response. When an alert fires on Payments, the graph immediately shows upstream callers (Orders) and downstream dependencies.

Data Pipeline and Lineage

Graph diagrams work well for data engineering. Here is an ETL pipeline:

graph LR
    S3[(S3 Raw Bucket)] --> Glue[AWS Glue ETL]
    Kafka[Kafka Stream] --> Glue
    Glue --> DW[(Redshift Warehouse)]
    DW --> DBT[dbt Transforms]
    DBT --> BI[BI Dashboard]
    DBT --> ML[ML Feature Store]

This gives your data team a single diagram that explains where data comes from, how it moves, and where it lands.

Build Pipeline and CI/CD Dependencies

Graph diagrams can also represent build dependencies in monorepos:

graph TB
    SharedLib[shared-lib]
    
    AuthPkg[auth-package] --> SharedLib
    UIPkg[ui-components] --> SharedLib
    APIPkg[api-client] --> SharedLib
    
    WebApp[web-app] --> AuthPkg
    WebApp --> UIPkg
    WebApp --> APIPkg
    
    MobileApp[mobile-app] --> AuthPkg
    MobileApp --> UIPkg
    MobileApp --> APIPkg
    
    Admin[admin-panel] --> AuthPkg
    Admin --> UIPkg
    Admin --> APIPkg

This helps teams understand the blast radius of changes. If shared-lib changes, everything rebuilds. If ui-components changes, only the UI-facing apps are affected.

Styling Graph Diagrams

You can apply CSS-like styles to nodes and edges:

graph LR
    A[Healthy Service]:::ok
    B[Degraded]:::warn
    C[Down]:::critical
    A -->|"200 OK"| B
    B -->|"503"| C
    
    classDef ok fill:#4caf50,stroke:#2e7d32,color:white
    classDef warn fill:#ff9800,stroke:#e65100,color:white
    classDef critical fill:#f44336,stroke:#b71c1c,color:white

Use classDef to define reusable styles and apply them with ::: notation. This is great for status dashboards, health checks, or differentiating environment tiers.

Graph vs Flowchart: When to Use Which

Both use the graph keyword, but the intent differs:

For most system documentation, you will use both. Start with a graph showing the architecture, then add flowcharts for critical processes within that architecture.

Best Practices

Use subgraphs for logical grouping. They make complex diagrams readable by creating visual boundaries around related components.

Pick the right direction. Use TB for hierarchies, LR for data flows and timelines. Mixing directions within subgraphs is allowed in some renderers but can confuse the layout engine.

Label edges for clarity. A -->|HTTP POST| B is better than A --> B when the relationship is not obvious.

Keep diagrams focused. A graph with 50 nodes is hard to read. Split large diagrams into smaller focused ones — one for network topology, one for service dependencies, one for data lineage.

Use MermaidEditor.lol for live preview. Paste your code, tweak the layout, and export when it looks right.

Final Thoughts

Mermaid graph diagrams are the most flexible tool in the Mermaid ecosystem. They handle everything from simple dependency maps to full network topologies, and the text-based format means diagrams stay in version control alongside your code.

Next time you need to document architecture, reach for a Mermaid graph instead of a screenshot. Your future self — and your teammates — will thank you.