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.

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.