Mermaid AWS Architecture Diagram Guide

# Mermaid AWS Architecture Diagram Guide

AWS architecture diagrams are usually treated like presentation assets: opened in a drawing tool, adjusted by hand, exported as an image, and forgotten until the next migration. Mermaid gives engineering teams a lighter alternative. You can describe the cloud architecture as text, review it in a pull request, and keep it beside the README, runbook, or architecture decision record it supports.

This guide shows practical Mermaid patterns for AWS diagrams: VPC boundaries, public and private subnets, ECS services, Lambda functions, queues, databases, and deployment flows. The examples are intentionally simple so you can copy them into your own docs and customize the labels.

When Mermaid Works Well for AWS Diagrams

Mermaid is best for explaining relationships and flows, not for recreating every official AWS icon. Use it when you need to show:

- How traffic enters a system

- Which services live inside a VPC

- What is public versus private

- How asynchronous jobs move through queues

- Which datastore owns which data

- How a deployment or failover process works

If you need a boardroom-ready image with branded service icons, use a dedicated cloud diagramming tool. If you need maintainable engineering documentation, Mermaid is often faster and easier to keep current.

Basic AWS Web App Architecture

Start with a small flowchart that shows the request path. This is often enough for a README or service overview page.

flowchart LR
    User["User"] --> DNS["Route 53"]
    DNS --> CDN["CloudFront"]
    CDN --> ALB["Application Load Balancer"]
    ALB --> App["ECS Service"]
    App --> DB[("RDS PostgreSQL")]
    App --> Cache[("ElastiCache Redis")]

The diagram avoids decorative detail and focuses on the question a reader actually has: what happens after a request reaches the product?

Show VPC and Subnet Boundaries

Mermaid subgraphs are perfect for cloud boundaries. Use them for VPCs, availability zones, subnet groups, or team ownership areas.

flowchart TB
    Internet["Internet"] --> ALB["Public ALB"]

    subgraph VPC["AWS VPC"]
        subgraph Public["Public subnets"]
            ALB
            NAT["NAT Gateway"]
        end

        subgraph PrivateApp["Private app subnets"]
            API["ECS API tasks"]
            Worker["ECS worker tasks"]
        end

        subgraph PrivateData["Private data subnets"]
            DB[("RDS primary")]
            Redis[("Redis cache")]
        end
    end

    ALB --> API
    API --> DB
    API --> Redis
    API --> SQS["SQS queue"]
    SQS --> Worker
    Worker --> DB
    API --> NAT

A useful rule: make boundaries meaningful. A subgraph should tell the reader something about network access, blast radius, security ownership, or operational responsibility.

Serverless AWS Architecture

For Lambda-heavy systems, show triggers and event destinations. Direction matters more than exact iconography.

flowchart LR
    Client["Web or mobile client"] --> APIGW["API Gateway"]
    APIGW --> LambdaA["Lambda: create order"]
    LambdaA --> Orders[("DynamoDB orders")]
    LambdaA --> EventBridge["EventBridge"]
    EventBridge --> LambdaB["Lambda: send receipt"]
    EventBridge --> LambdaC["Lambda: update analytics"]
    LambdaB --> SES["Amazon SES"]
    LambdaC --> Warehouse[("Data warehouse")]

This style is helpful in incident docs because it makes fan-out obvious. If one event creates three downstream actions, the diagram should show all three.

Queue-Based Background Jobs

SQS, SNS, EventBridge, Kinesis, and Step Functions often become invisible in prose. Mermaid makes the async path explicit.

flowchart TD
    API["API service"] -->|enqueue job| SQS["SQS: image-jobs"]
    SQS --> Worker["Worker service"]
    Worker --> S3[("S3 uploads bucket")]
    Worker --> DB[("PostgreSQL metadata")]

    Worker --> Choice{"Processing succeeded?"}
    Choice -->|yes| Done["Mark image ready"]
    Choice -->|no| DLQ["Dead-letter queue"]
    DLQ --> Alarm["CloudWatch alarm"]

Include failure paths when they change operations. A dead-letter queue, retry policy, or alarm is not a footnote; it is part of the architecture.

Deployment Flow for AWS Services

Architecture docs should also explain how changes reach production. A sequence diagram works well for CI/CD flows.

sequenceDiagram
    actor Dev as Developer
    participant Git as GitHub
    participant CI as CI Pipeline
    participant ECR as Amazon ECR
    participant ECS as Amazon ECS
    participant CW as CloudWatch

    Dev->>Git: Push to main
    Git->>CI: Trigger build
    CI->>CI: Run tests and type checks
    CI->>ECR: Push Docker image
    CI->>ECS: Update service task definition
    ECS-->>CI: Deployment started
    ECS->>CW: Emit health metrics
    CW-->>CI: Alarms remain healthy
    CI-->>Dev: Deployment succeeded

This kind of diagram belongs in a runbook or onboarding page. New developers can understand the release path without asking which service owns which deployment step.

Naming Tips for AWS Mermaid Diagrams

Use short node IDs and human labels:

- ALB["Application Load Balancer"]

- DB[("RDS PostgreSQL")]

- Queue["SQS order-events"]

- Fn["Lambda: resize image"]

Avoid putting full ARNs, account IDs, or region-specific names in diagrams unless the page is a runbook that needs those details. For most documentation, readers need the architecture concept first and the exact resource identifier second.

What to Include and What to Leave Out

A strong AWS Mermaid diagram is selective. Include components that affect the reader's understanding:

- Entry points such as Route 53, CloudFront, API Gateway, or an ALB

- Compute layers such as ECS, EKS, Lambda, or EC2

- Data stores such as RDS, DynamoDB, S3, OpenSearch, or Redis

- Async infrastructure such as SQS, SNS, EventBridge, or Kinesis

- Security or network boundaries when they explain access

- Operational paths such as alarms, dead-letter queues, and deploys

Leave out details that will go stale quickly: every security group, every IAM policy, every subnet ID, or every generated resource name. Link to Terraform, CloudFormation, or CDK for exact infrastructure definitions.

AWS Diagram Checklist

Before publishing, ask:

1. Can a new engineer explain the request path after reading it?
2. Are public and private boundaries clear?
3. Are async queues and event buses visible?
4. Are databases and buckets labeled by purpose?
5. Does the diagram avoid secrets, account IDs, and unnecessary ARNs?
6. Will this be updated in the same pull request as infrastructure changes?

If the answer is yes, the diagram is doing its job.

Final Recommendation

Use Mermaid for AWS architecture diagrams that need to live with engineering docs: service overviews, onboarding guides, ADRs, incident reviews, and deployment runbooks. Keep each diagram focused on one question, use subgraphs for meaningful boundaries, and prefer clear labels over decorative cloud icons.

When a cloud diagram is stored as text, it can be reviewed, versioned, searched, and fixed like the rest of your codebase. That is the real advantage of Mermaid for AWS architecture documentation.