Mermaid Network Diagram: Topology, Subnets & Firewall Rules

# Mermaid Network Diagram: Topology, Subnets & Firewall Rules

Network engineers and cloud architects often reach for Visio or draw.io for topology diagrams, but Mermaid.js is a solid alternative: text-based, version-controllable, and free. You can store your network diagrams alongside Terraform in the same repo and review changes in pull requests.

This guide covers using Mermaid flowchart and graph syntax for network topology: VPC layouts, subnet routing, firewall rule flows, and DMZ architectures.

Why Mermaid for Network Diagrams?

• Git-friendly. Network diagrams change when your infra does. Keep them in the same PR.
• No drag-and-drop. Define nodes and edges with text, regenerate instantly.
• Live preview. Paste Mermaid code into any editor and see the diagram render.
• Lightweight. No desktop app, no license, no export step for docs.

For most network diagrams, flowchart LR (left-to-right) or flowchart TD (top-down) works. Group subnets with subgraph and use icons or shapes to distinguish servers, load balancers, and firewalls.

Basic AWS VPC Topology

A standard VPC layout with public and private subnets, NAT gateway, and internet gateway:

flowchart LR
    Internet((Internet))

    subgraph VPC["AWS VPC 10.0.0.0/16"]
        IGW["Internet Gateway"]

        subgraph Public["Public Subnet 10.0.1.0/24"]
            ALB["Application LB"]
            Bastion["Bastion Host"]
        end

        subgraph Private["Private Subnet 10.0.2.0/24"]
            App1["App Server 1"]
            App2["App Server 2"]
        end

        subgraph Data["Data Subnet 10.0.3.0/24"]
            RDS[("RDS Primary")]
            Cache[("ElastiCache")]
        end

        NAT["NAT Gateway"]
    end

    Internet --> IGW
    IGW --> ALB
    IGW --> Bastion
    ALB --> App1
    ALB --> App2
    App1 --> RDS
    App2 --> RDS
    App1 --> Cache
    App2 --> Cache
    Private -->|Outbound| NAT
    NAT -->|Internet| IGW

This diagram communicates subnet isolation, traffic flow, and the NAT path in a single view. Swap node labels for your actual instance names and CIDR ranges.

Hub-and-Spoke Network Architecture

For multi-account or multi-region setups, a hub-and-spoke model keeps shared services central:

flowchart TD
    subgraph Hub["Hub VPC (Shared Services)"]
        NGFW["Next-Gen Firewall"]
        VPN["VPN Gateway"]
        DNS["Route 53 Resolver"]
    end

    subgraph Spoke1["Spoke VPC — Dev"]
        DevApp["Dev App"]
        DevDB[("Dev DB")]
    end

    subgraph Spoke2["Spoke VPC — Prod"]
        ProdApp["Prod App"]
        ProdDB[("Prod DB")]
    end

    Spoke1 <-->|TGW| Hub
    Spoke2 <-->|TGW| Hub
    NGFW -->|Inspection| Spoke1
    NGFW -->|Inspection| Spoke2
    VPN -->|On-prem| NGFW

The Transit Gateway (TGW) attachment is a single line. For larger environments, add more spoke VPCs and label each TGW route table.

Firewall Rule Flow Diagram

Firewall rules are easier to review as a flow diagram than a table. This shows a typical inbound HTTPS flow:

flowchart LR
    Client["End User"] -->|HTTPS 443| WAF["AWS WAF"]
    WAF -->|Pass| ALB["Application LB"]
    WAF -->|Block| Drop[("Dropped")]
    ALB -->|Forward| FW["Network Firewall"]
    FW -->|Allow 443| AppSV["App Servers :443"]
    FW -->|Deny All Else| Drop
    AppSV -->|5432| DB[("Postgres")]

Each rule is an edge, and rejected traffic hits the Drop node. This makes it obvious which ports are open and where inspection happens.

DMZ (Demilitarized Zone) Diagram

A classic three-zone architecture: external, DMZ, and internal:

flowchart LR
    Ext["External Users"] -->|HTTPS| FW1["External Firewall"]

    subgraph DMZ["DMZ"]
        WebLb["Web Load Balancer"]
        Web1["Web Server 1"]
        Web2["Web Server 2"]
    end

    FW1 --> WebLb
    WebLb --> Web1
    WebLb --> Web2

    DMZ -->|Restricted| FW2["Internal Firewall"]

    subgraph Internal["Internal Network"]
        AppLb["App Load Balancer"]
        App1["App Server"]
        DB[("Database")]
    end

    FW2 --> AppLb
    AppLb --> App1
    App1 --> DB

The double-firewall pattern is clear: external traffic stops at the DMZ, internal services are behind a second firewall.

Subnet-Level Traffic Matrix

For micro-segmentation or zero-trust, show allowed paths between subnets:

flowchart TD
    subgraph Web["Web Tier 10.0.1.0/24"]
        W1["web-01"]
        W2["web-02"]
    end

    subgraph App["App Tier 10.0.2.0/24"]
        A1["app-01"]
        A2["app-02"]
    end

    subgraph DB["DB Tier 10.0.3.0/24"]
        D1[("db-primary")]
        D2[("db-replica")]
    end

    W1 -->|TCP:443| A1
    W2 -->|TCP:443| A2
    A1 -->|TCP:5432| D1
    A2 -->|TCP:5432| D1
    D1 -.->|Replication TCP:5432| D2

Add port numbers on edge labels for security review. The dotted line for replication distinguishes control traffic from client traffic.

Tips for Network Diagrams in Mermaid

1. Use subgraphs for zones. Subnets, VPCs, and trust boundaries are subgraphs.
2. Label edges with protocols and ports. -->|HTTPS 443| B tells reviewers what's allowed.
3. Distinguish node types. Use round brackets for databases, square for servers, circle for external entities.
4. Keep it one page. If your network has 50+ nodes, split by layer or zone into multiple diagrams.
5. Store with infra code. Keep .mmd or .md files in the same repo as Terraform or CloudFormation.
6. Don't duplicate reality. Show the logical architecture and trust boundaries — not every patch cable.

When NOT to Use Mermaid

Mermaid network diagrams work best for logical topology, but they have limits:

• No auto-layout for physical racks. Use NetBox or draw.io for rack elevations.
• No real-time discovery. Mermaid is static; pair it with infrastructure-as-code docs.
• Complex peering meshes. A fully meshed BGP topology with 20+ peers is hard to read. Consider an adjacency matrix instead.

For cloud architecture docs, architecture decision records (ADRs), and security review diagrams, Mermaid is the sweet spot: fast, readable, and always in sync with your repo.