MermanDraw
Open Editor

Mermaid guide

Mermaid Architecture Diagram: Services, Groups, Icons, and Edge Directions

The architecture diagram draws cloud-style topologies: services with icons, grouped into labelled boxes, connected by edges that attach to a chosen side of each node. It was added in Mermaid 11 to replace the hand-drawn infrastructure diagrams that drift out of date.

Edges are explicit about which side they leave and enter, which gives you more layout control than a flowchart at the cost of a little more typing.

  • cloud-architecture diagrams
  • deployment topologies
  • microservice maps
  • infrastructure overviews

Example

Mermaid Architecture exampleCDNPagesWorker APID1 DatabaseKV StoreR2 StorageCloudflare
architecture-beta
    group cloud(cloud)[Cloudflare]

    service cdn(internet)[CDN] in cloud
    service pages(server)[Pages] in cloud
    service worker(server)[Worker API] in cloud
    service db(database)[D1 Database] in cloud
    service kv(disk)[KV Store] in cloud
    service r2(disk)[R2 Storage] in cloud

    cdn:R --> L:pages
    pages:R --> L:worker
    worker:R --> L:db
    worker:T --> B:kv
    worker:B --> T:r2
Open in editor → Cheatsheet →

Syntax

Groups and services

architecture-beta
    group vpc(cloud)[Production VPC]
    service lb(internet)[Load balancer] in vpc
    service app(server)[App] in vpc
    service db(database)[Postgres] in vpc
    service bucket(disk)[Object storage]
    lb:R --> L:app
    app:R --> L:db
    app:B --> T:bucket
Groups and services — Mermaid architectureLoad balancerAppPostgresObject storageProduction VPC

Built-in icons: cloud, database, disk, internet, server. in groupId nests a service. Edge: id:SIDE --> SIDE:id with sides T, B, L, R.

Try this snippet →

Nested groups and junctions

architecture-beta
    group cloud(cloud)[Cloud]
    group region(cloud)[Region A] in cloud
    service a(server)[Service A] in region
    service b(server)[Service B] in region
    junction j in cloud
    a:R -- L:j
    j:R --> L:b
Nested groups and junctions — Mermaid architectureService AService BCloudRegion A

Junctions are invisible nodes for routing edges around groups. -- draws a line without an arrowhead.

Try this snippet →

Common mistakes

These are the parse errors that come up most, including in code written by ChatGPT and Claude. Paste any failing diagram into the editor and it marks the offending line.

  • Edges without side anchors (a --> b).

    Fix: Architecture edges need sides: a:R --> L:b.

  • Icon names outside the built-in set (service x(kafka)[Kafka]).

    Fix: Only cloud, database, disk, internet, and server ship by default. Extra icon packs can be registered in a custom renderer but not in GitHub or the share page.

  • Spaces in service IDs.

    Fix: IDs are identifiers; the readable name goes in the square brackets.

Real-world examples

Complete, copy-ready architectures for common situations. Each one opens in the editor with a click.

Browse all examples →

FAQ

Can I draw a multi-region or multi-cloud setup?

Yes. Make one top-level group per cloud or region and nest services inside. Use junctions to route cross-group edges cleanly.

How does it compare with the C4 diagram?

Mermaid's C4 syntax is older and more verbose. The architecture diagram is lighter and has icons, so it is the better default for infrastructure overviews.