How does Mermaid architecture-beta syntax work? A complete reference

What are the building blocks of an architecture-beta diagram?

Every architecture-beta diagram is assembled from exactly four kinds of declaration:

The diagram begins with the keyword architecture-beta on its own line. After that, you declare groups, services, edges, and junctions in any order — with one rule: an id must be declared before another line references it. In practice that means declare your groups first, then the services inside them, then the edges between those services.

Icons go inside parentheses () and labels go inside square brackets []. Both are optional in raw Mermaid, but for a readable AWS diagram you will almost always supply both.

How do you declare a group?

A group is a container. The syntax is:

group {id}({icon})[{label}] (in {parent})?

So a VPC declared at the top level looks like this:

architecture-beta
    group vpc(aws:virtual-private-cloud-vpc)[VPC]

The id (vpc) is how you reference the group elsewhere. The icon slug sits in parentheses, the human-readable label in brackets. The trailing in {parent} clause is optional and is what lets you nest one group inside another.

How do you nest groups and services?

Nesting is done with the in keyword, and it is the same for both groups and services. A subnet inside a VPC, with an EC2 instance inside that subnet:

architecture-beta
    group vpc(aws:virtual-private-cloud-vpc)[VPC]
    group public_subnet(aws:public-subnet)[Public Subnet] in vpc

    service web(aws:arch-amazon-ec2)[Web Server] in public_subnet

The containment is purely textual — in vpc places public_subnet inside vpc, and in public_subnet places web inside the subnet. There is no limit that bites in practice: region inside account, VPC inside region, subnet inside VPC, service inside subnet is a perfectly normal four-level nesting.

This containment is also what a validator reads to catch mistakes — a managed service like S3 drawn inside a subnet is a modeling error, because S3 lives outside the VPC boundary. See common AWS architecture mistakes for the full list of placement rules.

How do you connect services with edges?

This is the part that trips everyone up, because it does not look like a flowchart arrow. The full grammar is:

{serviceId}{group}?:{T|B|L|R} {<}?--{>}? {T|B|L|R}:{serviceId}{group}?

Read left to right, an edge is: a source service, the side it leaves from, the connector, the side it arrives at, and the target service. The simplest form connects the right side of one service to the left side of another:

db:R -- L:server

Two things are doing work here. The :R and :L are ports — they say which side of each node the line attaches to. The -- in the middle is the connector, and it controls the arrowheads.

Arrowheads are optional. You add < before the left port and/or > after the right port:

All four forms describe the same connection between the same two nodes — the arrowheads are presentational. A validator that reasons about your architecture treats the graph as undirected, so igw:L -- R:internet and igw:L <--> R:internet are equivalent for the purpose of "is the gateway connected to the internet."

What do the L, R, T, and B ports mean?

The port after each colon is one of four values — Left, Right, Top, Bottom — and it chooses which side of the node the edge attaches to:

Matching opposite ports on the same axis gives a straight line; mixing axes gives a right-angle elbow. Ports are a layout hint — they are how you nudge architecture-beta's automatic layout into the shape you want without a manual coordinate system.

How do you draw an edge between two groups?

By default an edge connects two services. To route a connection out of a group boundary instead — group-to-group, or service-in-one-group to service-in-another — add the {group} modifier after the service id:

service server(aws:arch-amazon-ec2)[Server] in group_one
service subnet(aws:arch-amazon-ec2)[Subnet] in group_two

server{group}:B --> T:subnet{group}

This makes the edge leave group_one (next to server) and enter group_two (next to subnet). Two rules matter here:

• You cannot use a group's own id as an edge endpoint. Edges connect services and junctions, never groups directly.
• The {group} modifier only works on a service that actually sits inside a group.

What is a junction, and when do you need one?

A junction is a special node that acts as a four-way split point. It has no icon and no label — it exists so several edges can meet at a single clean intersection instead of crossing awkwardly.

architecture-beta
    service left_disk(disk)[Disk]
    service top_disk(disk)[Disk]
    service bottom_disk(disk)[Disk]
    junction center

    left_disk:R -- L:center
    top_disk:B -- T:center
    bottom_disk:T -- B:center

Declare it with junction {id} (in {parent})? — like services, junctions can be placed inside a group with in. Reach for one when three or more services share a common connection point, such as several private-subnet resources routing through a single NAT path.

How do you use AWS icons instead of the five built-ins?

Out of the box, architecture-beta ships only five generic icons: cloud, database, disk, internet, and server. They take no prefix:

service db(database)[Database]

Real AWS icons come from an icon pack referenced by a provider:slug name. AWS slugs use the aws: prefix:

Note the pattern: top-level products use an arch- prefix and sub-components (gateways, endpoints) use a res- prefix. The intuitive guesses — aws:s3, aws:lambda, aws:ec2 — do not exist. This is precisely why LLMs hallucinate slugs: the short form a developer expects is not the real name. The fix is to ground the model in the real catalog, which we cover in getting LLMs to generate valid Mermaid AWS diagrams.

Stock Mermaid will not render any aws: slug unless an AWS icon pack is registered in that environment. LatixEngine registers all 856 AWS icons (plus 626 Azure and 216 GCP) into architecture-beta automatically, and publishes the full slug list at latixengine.com/icons.json so you can look up or paste the real names.

How do you keep the layout deterministic?

By default, architecture-beta produces a deterministic layout — the same source always renders with the same node positions, because the randomize option defaults to false. That is what you want for documentation that lives in version control: the diagram does not reshuffle every time you re-render it.

If you would rather let the layout engine try varied, potentially better-spaced arrangements, enable randomization via frontmatter:

%%{init: {"architecture": {"randomize": true}}}%%
architecture-beta
    group api(cloud)[API]
    service db(aws:arch-amazon-rds)[Database] in api
    service server(aws:arch-amazon-ec2)[Server] in api
    db:R --> L:server

What does a complete AWS diagram look like?

Putting every block together — account, region, VPC, public and private subnets, an Internet Gateway, a NAT, and EC2 instances connected with port-based edges:

architecture-beta
    service internet(aws:res-internet-alt1-light)[Internet]
    group account(aws:aws-account)[AWS Account]
    group region(aws:region)[Region] in account
    group vpc(aws:virtual-private-cloud-vpc)[VPC] in region

    group public_subnet(aws:public-subnet)[Public Subnet] in vpc
    service igw(aws:res-amazon-vpc-internet-gateway)[Internet Gateway] in vpc
    service nat(aws:res-amazon-vpc-nat-gateway)[NAT Gateway] in public_subnet
    service web(aws:arch-amazon-ec2)[Web Server] in public_subnet

    group private_subnet(aws:private-subnet)[Private Subnet] in vpc
    service app(aws:arch-amazon-ec2)[App Server] in private_subnet

    internet:L <--> R:igw
    igw:B <--> T:web
    igw:L <--> R:nat
    nat:B <--> T:app

Notice the internet service is declared at the top level — it sits outside the account, because the public internet is not part of your AWS account. The Internet Gateway lives at the VPC level, and the NAT sits in the public subnet. Those placements are not cosmetic; they are the difference between a diagram that models a correct architecture and one that quietly encodes a mistake.

Where does architecture-beta still trip people up?

Three recurring issues are worth keeping in mind:

• The -beta suffix is real. The syntax can change between Mermaid releases. Pin your version, and re-check diagrams after upgrading. For anything published, export to SVG so the image is frozen.
• Icon packs are environment-specific. A diagram that renders perfectly in one tool shows broken placeholders in another that has no AWS pack registered. This is the single most common reason "my diagram works locally but not in GitHub" — see rendering and embedding.
• Syntactically valid is not architecturally valid. The parser will happily accept a database in a public subnet or a NAT with no route to the internet. Catching those needs rules, not grammar — paste the diagram into the editor at latixengine.com/editor to validate both the syntax and the architecture in one pass.

architecture-beta is a compact language: four blocks, four ports, four connector forms. Once the edge grammar clicks, the rest is just nesting services into the right groups — and that structure is exactly what makes these diagrams checkable, not just drawable.