How do you draw AWS architecture diagrams in Mermaid?

What is Mermaid's architecture-beta and why does it not ship AWS icons?

Mermaid supports several diagram types — flowchart, sequenceDiagram, classDiagram, stateDiagram, erDiagram, gantt, mindmap — each with its own syntax. architecture-beta is the type built specifically for cloud and system architecture diagrams. It introduced two new primitives: service (a leaf node with an icon and label) and group (a container that can hold services and other groups).

The architecture-beta type ships a small built-in icon set: internet, cloud, database, disk, and server. That is enough for a generic three-tier diagram, but not enough to draw a real AWS architecture. AWS alone has hundreds of services with distinct iconography that engineers and reviewers expect to see in a diagram.

The fix is provider icon packs. Mermaid exposes an iconPacks option that lets renderers register additional icon collections. LatixEngine ships 856 official AWS icons preregistered, so every aws:<icon-name> slug just works in the editor and in any Mermaid renderer bundled with the same icon pack.

How do you add AWS icons to a Mermaid diagram?

Inside the LatixEngine editor there is nothing to install or configure — every AWS icon is already registered. You reference an icon by its slug inside the parentheses of a service or group declaration.

architecture-beta
    service ec2(aws:ec2-instance-contents)[EC2 Instance]
    service s3(aws:arch-amazon-simple-storage-service)[S3 Bucket]
    ec2:R <--> L:s3

If you are self-hosting Mermaid and want to register the AWS icon pack yourself, fetch the catalog at latixengine.com/icons.json and pass it to mermaid.registerIconPacks during initialization. Each entry in the catalog has a provider, a slug, and a human-readable name.

What does the syntax look like for an AWS VPC diagram?

Here is a complete diagram of a VPC with a public subnet (Internet Gateway, EC2 web server, NAT) and a private subnet (EC2 application server). This is the canonical AWS web-app reference architecture, written as Mermaid source.

architecture-beta
    service internet(internet)[Internet]

    group region(aws:region)[AWS Region]
        group vpc(aws:virtual-private-cloud-vpc)[VPC] in region
            service igw(aws:res-amazon-vpc-internet-gateway)[Internet Gateway] in vpc

            group public_subnet(aws:public-subnet)[Public Subnet] in vpc
                service ec2_public(aws:ec2-instance-contents)[EC2 Instance] in public_subnet
                service nat(aws:res-amazon-vpc-nat-gateway)[NAT Instance] in public_subnet

            group private_subnet(aws:private-subnet)[Private Subnet] in vpc
                service ec2_private(aws:ec2-instance-contents)[EC2 Instance] in private_subnet

    internet:L <--> R:igw
    igw:T <--> R:ec2_public
    igw:L <--> R:nat
    nat:B <--> T:ec2_private

Read it top to bottom: the diagram declares the internet as a free-standing service, opens an AWS Region group, nests a VPC inside it, then a public and a private subnet inside the VPC. Services live inside the relevant subnet via the in group-id clause. The four edge lines at the bottom describe the traffic flow.

Which AWS slugs map to the most common services?

These are the slugs you will reach for most often when drawing AWS architecture in Mermaid. The full catalog of 856 AWS slugs is available at latixengine.com/icons.json.

The two prefixes you will see most are arch- (architectural product icons used at the service level) and res- (resource icons used for sub-components like gateways, endpoints, and access points). When in doubt, pick the arch- variant for top-level services and the res- variant for plumbing inside a VPC.

How do you connect AWS services with edges and ports?

Mermaid architecture-beta uses port-anchored edges. Each edge specifies which side of the source node the line leaves and which side of the target node it enters. Ports are single letters: L (left), R (right), T (top), B (bottom).

igw:T <--> R:ec2_public

That line says: connect the Internet Gateway from its top port to the EC2 instance on its right port. Port choice controls layout — pick L/R for horizontal flows (request paths) and T/B for vertical ones (data flowing into storage). Avoid mixing the same source port twice; the renderer will overlap the lines.

Can you draw multi-AZ or multi-region diagrams in Mermaid?

Yes. Groups nest arbitrarily, so a multi-AZ layout is just two subnet groups inside the same VPC, each containing their own services.

architecture-beta
    group region(aws:region)[us-east-1]
        group vpc(aws:virtual-private-cloud-vpc)[VPC] in region
            group az1(aws:public-subnet)[AZ a · Public] in vpc
                service ec2a(aws:ec2-instance-contents)[Web a] in az1
            group az2(aws:public-subnet)[AZ b · Public] in vpc
                service ec2b(aws:ec2-instance-contents)[Web b] in az2

For multi-region, declare two separate region groups at the top level and put a peering or replication line between the inner resources.

How does Mermaid for AWS compare to draw.io, Lucidchart, and Cloudcraft?

Each tool optimises for a different workflow. Mermaid wins when diagrams need to live inside markdown, version control, or documentation pipelines. The GUI tools win when stakeholders want to drag-and-drop in a browser. Here is the honest comparison.

If your diagrams live next to code in a README, a Markdown ADR, or a Notion page, the markdown-native flow wins on every long-running maintenance metric. If your diagrams live in a slide deck for executives, a GUI tool will be faster.

Which AWS diagramming tool should you actually choose — Mermaid, draw.io/diagrams.net, Lucidchart, or Cloudcraft?

The capability matrix above tells you what each tool can do. This one is about which to reach for — and it clears up the name people get stuck on first: draw.io and diagrams.net are the same product. JGraph rebranded draw.io to diagrams.net in 2020, and the Confluence and Jira app, the web editor at app.diagrams.net, and the offline drawio-desktop build all run the same engine. So "draw.io or diagrams.net" is not a real decision. The real decision is the rows below.

None of these is wrong. Pick Mermaid when the diagram's home is a repository, an ADR, or a README and it has to survive refactors and code review. Pick a GUI tool when the diagram's home is a slide, a shared canvas, or a live AWS account. If you are weighing the code-native approach against AWS's own tooling, see Mermaid vs AWS Application Composer; if you want to generate diagrams from infrastructure you already have, see turning Terraform into a Mermaid AWS diagram.

What does a complete load-balanced three-tier AWS architecture look like in Mermaid?

The VPC example earlier in this post is deliberately minimal. Here is the diagram most teams actually need to document: a public load balancer, a private application tier that reaches the internet only through NAT, a private database, and object storage that sits at the region level rather than inside any subnet. Every placement here follows a real AWS constraint, which is what makes it a safe template to copy.

architecture-beta
    service users(aws:res-users-light)[Users]
    service internet(aws:res-internet-light)[Internet]

    group region(aws:region)[AWS Region us-east-1]
        service s3(aws:arch-amazon-simple-storage-service)[S3 Static Assets] in region

        group vpc(aws:virtual-private-cloud-vpc)[VPC 10.0.0.0/16] in region
            service igw(aws:res-amazon-vpc-internet-gateway)[Internet Gateway] in vpc

            group public(aws:public-subnet)[Public Subnet] in vpc
                service alb(aws:res-elastic-load-balancing-application-load-balancer)[Application Load Balancer] in public
                service nat(aws:res-amazon-vpc-nat-gateway)[NAT Gateway] in public

            group appsub(aws:private-subnet)[Private Subnet App] in vpc
                service app(aws:ec2-instance-contents)[EC2 App Server] in appsub

            group datasub(aws:private-subnet)[Private Subnet Data] in vpc
                service rds(aws:arch-amazon-rds)[RDS Primary] in datasub

    users:R --> L:internet
    internet:R --> L:igw
    igw:B --> T:alb
    alb:B --> T:app
    app:R --> L:rds
    app:B --> T:nat
    nat:R --> T:igw
    app:L --> R:s3

Read the placements, because each one is a rule:

• The Application Load Balancer is the only internet-facing compute, so it sits in the public subnet.
• The EC2 app server sits in a private subnet and has no route to the Internet Gateway. Its outbound traffic goes app to NAT to IGW. Drawing a line straight from a private instance to the IGW is the single most common invalidity — see common AWS architecture mistakes.
• RDS lives in its own private subnet, never a public one.
• S3 is declared inside the region group, not inside the VPC, because it is a regional service reached over the AWS network rather than a resident of any subnet.
• The edges use directed arrows (-->) instead of the bidirectional <--> used earlier in this post, so the diagram also communicates request direction. It is a small habit that makes diagram diffs easier to read in review.

For a fuller catalogue of ready-made layouts — fan-out, event-driven, static site — see the AWS architecture patterns gallery; for the networking layer in depth, see the VPC architecture diagram guide.

How do you draw a multi-account or shared-services AWS layout in Mermaid?

Larger organisations do not run everything in one account, and a landing-zone or multi-account setup is easy to express: an account is just another group. Use the aws:aws-account icon as the outermost container and nest a region, VPC, and subnets inside it exactly as before. Edges may cross account boundaries, which is how you show a workload account writing to a central logging bucket owned by a shared-services account.

architecture-beta
    group workload(aws:aws-account)[Workload Account 1111-2222]
        group region1(aws:region)[us-east-1] in workload
            group vpc1(aws:virtual-private-cloud-vpc)[App VPC] in region1
                service igw1(aws:res-amazon-vpc-internet-gateway)[Internet Gateway] in vpc1
                group pub1(aws:public-subnet)[Public Subnet] in vpc1
                    service nat1(aws:res-amazon-vpc-nat-gateway)[NAT Gateway] in pub1
                group priv1(aws:private-subnet)[Private Subnet] in vpc1
                    service worker(aws:ec2-instance-contents)[EC2 Worker] in priv1

    group shared(aws:aws-account)[Shared Services Account 3333-4444]
        group region2(aws:region)[us-east-1] in shared
            service logs(aws:arch-amazon-simple-storage-service)[S3 Central Logs] in region2

    worker:B --> T:nat1
    nat1:R --> L:igw1
    worker:R --> L:logs

Two top-level aws:aws-account groups do the whole job. The workload account keeps its own egress path — private EC2 to NAT to IGW — and the cross-account arrow from the worker to the shared S3 bucket shows centralised logging without duplicating the networking. The same shape scales to a networking account that owns a Transit Gateway or a security account that owns central findings: add one aws:aws-account group per account and connect only the services that carry a real dependency. A diagram that wires every service to every account becomes unreadable fast.

What are the most common gotchas when authoring AWS diagrams in Mermaid?

These are the snags that surface in review — not architectural mistakes, which have their own guide, but Mermaid-authoring ones that make a diagram render wrong or not at all.

• Prefix confusion. arch- slugs are the coloured product tiles for a whole service (aws:arch-amazon-rds); res- slugs are the smaller resource icons for sub-components (aws:res-amazon-vpc-nat-gateway); group containers usually take an un-prefixed slug (aws:region, aws:public-subnet). Guessing the wrong prefix is the top cause of a missing-icon box. Confirm every slug against the icon catalog, and check the grammar in the architecture-beta syntax reference.
• Forgetting the in clause. Every nested service or group needs an in parent-id clause. Omit it and the node silently jumps to the top level instead of raising an error, so a subnet resource ends up floating outside the VPC.
• Reusing a port. Each side of a node — L, R, T, B — should carry at most one edge. Two lines entering or leaving the same side overlap into an unreadable smear. Spread them across sides, or merge them through a junction: a node with no icon whose only job is to route edges cleanly.

architecture-beta
    group vpc(aws:virtual-private-cloud-vpc)[VPC]
        service nat(aws:res-amazon-vpc-nat-gateway)[NAT Gateway] in vpc
        service appa(aws:ec2-instance-contents)[App A] in vpc
        service appb(aws:ec2-instance-contents)[App B] in vpc
        junction j in vpc
    appa:R --> L:j
    appb:B --> T:j
    j:R --> L:nat

• Edges attach to services, not groups. You cannot point a line at a group; connect to a service inside it (or a junction) instead. This trips up people who try to draw an arrow at a whole VPC.
• IGW attaches to the VPC, NAT to a public subnet. Declare the Internet Gateway in vpc and the NAT Gateway in the public subnet, then route private egress through the NAT — never straight to the IGW.
• architecture-beta is still beta. Renderer support is uneven — GitHub and some wikis will not render custom icon packs reliably yet — so the durable docs-as-code workflow is: keep the .mmd source in the repo next to the code it documents, export an SVG, commit the SVG beside the source, and let reviewers diff the plain text in the pull request. The full rendering-and-embedding matrix is in rendering and embedding Mermaid AWS diagrams.

Can you export the Mermaid AWS diagram to SVG, PNG, or markdown?

Yes. LatixEngine exports three formats directly from the editor toolbar:

• SVG — vector format, scales for prints and high-DPI displays, embed in static documentation.
• PNG — raster format, paste into Slack, Notion, Confluence, or any tool that does not parse SVG.
• Markdown — the raw mermaid code fence, drop into a README or wiki where Mermaid rendering is supported.

For documentation that lives in GitHub, the safest path today is SVG export and commit the SVG alongside the .mmd source. That way the diagram renders identically everywhere, and the source is still diffable.

What if my Mermaid renderer does not have the AWS icon pack?

Three options, ranked by effort:

• Use the LatixEngine editor directly at latixengine.com/editor and export SVG or PNG when you need to embed the diagram somewhere.
• Self-host the icons. Fetch the catalog at latixengine.com/icons.json, then register the pack with Mermaid's mermaid.registerIconPacks API during initialization.
• Fall back to the generic Mermaid icons (cloud, server, database) and treat the diagram as schematic. Loss of fidelity, but works in any vanilla Mermaid renderer.