Mermaid packet diagrams: visualize network topology and data flows

Network infrastructure is invisible until something breaks—then it's critical. Packet diagrams help teams visualize how data moves through routers, servers, firewalls, and cloud services. Mermaid's packet diagram syntax lets you model network flows, packet transformations, and routing rules in plain text, making it easy to document and version your infrastructure alongside your code.

Why packet diagrams matter for infrastructure

Packet diagrams serve multiple audiences:

• Network engineers can document the actual traffic flow for troubleshooting
• DevOps teams can visualize where traffic gets routed, filtered, or transformed
• Security teams can see attack surface and enforce rules at each layer
• New team members get a clear map of your infrastructure without asking
• Architects can iterate on infrastructure changes before committing resources

Unlike static images, Mermaid packet diagrams live in your repo, versioned alongside your IaC (Terraform, CloudFormation) or architecture decisions (ADRs).

Packet diagram syntax in Mermaid

A packet diagram shows the structure of network packets or data frames as they traverse your network. Nodes represent packet fields or layers; edges show the hierarchy.

packet-beta
    title Network Packet Structure
    65 : Source IP
    65 : Dest IP
    32 : Protocol
    16 : Source Port
    16 : Dest Port
    128 : Payload

This represents a simplified packet with IP addresses, protocol type, ports, and payload. The numbers represent bit-widths.

For network topology, we use flowcharts instead to show how devices connect:

graph LR
    Internet["🌍 Internet"]
    Firewall["🔥 Firewall<br/>Border Protection"]
    LoadBalancer["⚖️ Load Balancer<br/>nginx"]
    
    Web1["🖥️ Web Server 1<br/>Ubuntu + Node.js"]
    Web2["🖥️ Web Server 2<br/>Ubuntu + Node.js"]
    
    DBPrimary["🗄️ Database Primary<br/>PostgreSQL"]
    DBReplica["🗄️ Database Replica<br/>PostgreSQL"]
    
    Cache["💾 Cache<br/>Redis Cluster"]
    
    Monitoring["📊 Monitoring<br/>Prometheus + Grafana"]
    
    Internet --> Firewall
    Firewall --> LoadBalancer
    LoadBalancer --> Web1
    LoadBalancer --> Web2
    
    Web1 --> DBPrimary
    Web2 --> DBPrimary
    DBPrimary --> DBReplica
    
    Web1 --> Cache
    Web2 --> Cache
    
    Web1 --> Monitoring
    Web2 --> Monitoring
    DBPrimary --> Monitoring

This diagram shows:

• Internet connects to the firewall (entry point)
• Firewall routes to load balancer
• Load balancer distributes to two web servers (horizontal scaling)
• Both web servers talk to the primary database
• Primary database replicates to a replica
• Web servers cache frequently used data in Redis
• All nodes report metrics to monitoring

Real-world example: AWS cloud architecture

Here's a typical cloud deployment with multiple availability zones:

graph TD
    Users["👥 Users<br/>Global"]
    CDN["📡 CloudFront<br/>CDN"]
    
    subgraph AZ1["🏢 Availability Zone 1"]
        ALB1["ALB<br/>us-east-1a"]
        EC2_1["EC2 Instance<br/>t3.medium"]
        RDS_1["RDS Read Replica<br/>PostgreSQL"]
    end
    
    subgraph AZ2["🏢 Availability Zone 2"]
        ALB2["ALB<br/>us-east-1b"]
        EC2_2["EC2 Instance<br/>t3.medium"]
        RDS_2["RDS Read Replica<br/>PostgreSQL"]
    end
    
    RDSPrimary["🗄️ RDS Primary<br/>us-east-1a"]
    S3["☁️ S3<br/>Static Assets + Backups"]
    ElastiCache["⚡ ElastiCache<br/>Redis"]
    
    Users --> CDN
    CDN --> ALB1
    CDN --> ALB2
    
    ALB1 --> EC2_1
    ALB2 --> EC2_2
    
    EC2_1 --> RDSPrimary
    EC2_2 --> RDSPrimary
    
    RDSPrimary --> RDS_1
    RDSPrimary --> RDS_2
    
    EC2_1 --> ElastiCache
    EC2_2 --> ElastiCache
    
    EC2_1 --> S3
    EC2_2 --> S3

This architecture provides:

• High availability — Two AZs, each with compute and read replicas
• Redundancy — If one AZ fails, traffic routes to the other
• Scalability — Load balancers distribute requests
• Performance — Cache layer for hot data; CDN for static assets
• Data durability — Primary DB with replicas; S3 backups

Packet flow in a request cycle

Here's how a user request flows through the infrastructure:

sequenceDiagram
    participant Browser as 🌐 Browser
    participant CDN as 📡 CDN
    participant ALB as ⚖️ ALB
    participant App as 🖥️ App Server
    participant Cache as 💾 Cache
    participant DB as 🗄️ Database
    
    Browser->>CDN: GET /api/user (HTTPS)
    alt Cache Hit
        CDN-->>Browser: Cached response
    else Cache Miss
        CDN->>ALB: Forward to Origin
        ALB->>App: Route request
        App->>Cache: Check cache
        alt Cache Hit
            Cache-->>App: Return data
        else Cache Miss
            App->>DB: Query user
            DB-->>App: User data
            App->>Cache: Store in cache
        end
        App-->>ALB: JSON response
        ALB-->>CDN: Return to origin
        CDN->>CDN: Cache response (TTL: 300s)
        CDN-->>Browser: Return response
    end
    Browser->>Browser: Render page

This shows:

• Browser hits CDN first (fastest path)
• CDN checks its cache; if miss, routes to origin (ALB)
• App checks application cache (Redis) before querying database
• Multiple levels of caching reduce database load
• Response flows back through each layer, caching along the way

Security: firewall and network segmentation

Here's how network segmentation and firewall rules protect your infrastructure:

graph LR
    Internet["🌍 Internet"]
    
    subgraph DMZ["DMZ<br/>Public Subnet"]
        FW["🔥 Firewall<br/>Stateful Inspection"]
        WAF["🛡️ WAF<br/>Web Application Firewall"]
    end
    
    subgraph Public["Public Tier<br/>Application Subnet"]
        LB["⚖️ Load Balancer"]
        Web1["Web Server 1"]
        Web2["Web Server 2"]
    end
    
    subgraph Private["Private Tier<br/>Database Subnet"]
        DB["🔒 Database<br/>No direct internet"]
        Vault["🔐 Secrets Manager"]
    end
    
    Internet -->|TCP 443| FW
    FW -->|Inspect HTTPS| WAF
    WAF -->|Allow HTTP/HTTPS| LB
    LB --> Web1
    LB --> Web2
    
    Web1 -->|TCP 5432| DB
    Web2 -->|TCP 5432| DB
    
    Web1 -->|API call| Vault
    Web2 -->|API call| Vault
    
    style DMZ fill:#ff9999
    style Public fill:#ffcc99
    style Private fill:#99ccff

This architecture shows:

• DMZ handles inbound traffic with firewalls and WAF
• Public tier runs the application (unrestricted outbound for updates, logs)
• Private tier runs the database (accepts only from public tier)
• Color coding shows security zones: red (high risk) → yellow (medium) → blue (protected)

Troubleshooting network issues with diagrams

When debugging network problems, draw the packet's path:

1. Request enters → Which IP/port?
2. Firewall rules → Is it allowed? (check security group, NSG, firewall policy)
3. Routing → Does the packet reach the right server? (check route tables)
4. Application → Does the app handle it? (check logs)
5. Response exits → Does it find its way back? (check return route)

Example: "My app can't reach the database."

graph LR
    App["App Server<br/>10.0.1.10"]
    SG1["Security Group<br/>App"]
    Route["Route Table<br/>10.0.0.0/16 → local"]
    SG2["Security Group<br/>Database"]
    DB["Database<br/>10.0.2.10<br/>Port 5432"]
    
    App -->|Outbound rule| SG1
    SG1 -->|Allow TCP 5432| Route
    Route -->|Local route| SG2
    SG2 -->|Inbound rule?| DB
    
    style SG2 fill:#ff9999

If the database's security group doesn't allow inbound traffic from the app's security group, the connection fails. This diagram makes the issue obvious.

Best practices for packet and network diagrams

1. Use consistent colors — Blue for private/secure zones, orange for public, red for security-sensitive
2. Label all ports and protocols — "TCP 443" is clearer than just an arrow
3. Show trust boundaries — Dashed lines for internet-facing, solid for internal
4. Separate concerns — One diagram for topology, another for packet flow, another for security rules
5. Keep it current — Update when you change infrastructure; version with your IaC
6. Avoid too many nodes — If your diagram has 20+ components, split into layers (frontend, app, data)
7. Test your story — Trace a request from user to database; does the path make sense?

When to use different diagram types

Goal	Diagram type	Example
Show network topology	Flowchart or graph	This post's examples
Show packet structure	Packet diagram	TCP/IP header breakdown
Show message flow over time	Sequence diagram	Request from browser to DB
Show deployment architecture	Block diagram	Kubernetes cluster nodes
Show infrastructure layers	C4 model	System context and containers
Show data flow	Sankey diagram	Traffic distribution across servers

FAQ

How do I handle bidirectional traffic?
Draw two arrows (A → B and B → A), or use a thicker/dashed line to indicate "both directions." Label clearly: "TCP 443 ↔" makes it obvious.

Should I include every network security group or firewall rule?
No. Show the critical paths and trust boundaries. Too many rules clutter the diagram. Create a separate document for detailed firewall policies.

How do I show multi-region infrastructure?
Use subgraphs for each region (AWS us-east-1, us-west-2, eu-west-1). Draw connections between regions for data replication or failover. Keep regions visually separated.

Can I use Mermaid for SDN (software-defined networking)?
Yes. Draw the controller, virtual switches, and host connections. Packet diagrams in Mermaid don't show OpenFlow rules, but flowcharts can model the data plane topology clearly.

What about IPv6 or advanced protocols?
Mermaid diagrams are logical, not protocol-specific. Label nodes with IPv6 addresses or protocol names as needed. The structure stays the same.

Document your network infrastructure with packet diagrams in the MermaidCreator editor. Clear network diagrams reduce troubleshooting time and prevent misconfiguration.