Skip to content
MermaidViewer

Software diagram · beta

Mermaid architecture diagram

Mermaid architecture diagram syntax for groups, services and edges, with a cloud layout you can edit.

By MermaidViewer editorsPublished Updated

Basic architecture diagram example

Basic architecture diagram example diagram
mermaid
architecture-beta
    group cloud(cloud)[Production]
    service lb(internet)[Load balancer] in cloud
    service app(server)[App servers] in cloud
    service db(database)[PostgreSQL] in cloud
    service files(disk)[Object storage] in cloud
    lb:R --> L:app
    app:R --> L:db
    app:B --> T:files
Open in the live editor

Architecture diagrams show services and resources — servers, databases, storage, queues — and how they connect, grouped by network or cloud boundary. Mermaid's architecture diagram uses icons and edge directions to create tidy infrastructure pictures.

Use it for deployment overviews, cloud architecture docs and incident write-ups.

When to use a architecture diagram

  • Cloud deployment overviews
  • Infrastructure documentation
  • Network topology
  • Incident and post-mortem diagrams

Architecture Diagram syntax reference

SyntaxWhat it does
architecture-betaStart an architecture diagram.
group id(icon)[Label]A group/boundary; can be nested with in parent.
service id(icon)[Label] in groupA service with an icon, optionally inside a group.
Icons: cloud, database, disk, internet, serverBuilt-in icons (more via icon packs).
a:R -- L:bEdge from the right side of a to the left side of b (T, B, L, R).
a:R --> L:bEdge with an arrow.
junction idA junction point to split edges.

Architecture Diagram examples

Services, a boundary around them, and a single arrow are the picture. A mermaid architecture diagram is a deployment sketch with icons. architecture-beta is the keyword. The icons and the in keyword do the real work.

Groups, services, and edges

group cloud(cloud)[Cloud] draws a boundary. cloud before the label is the icon. service api(server)[API] in cloud puts a service inside that boundary. The id is api, the icon is server, and the label is API. in cloud is the membership. Forget it and the service sits outside the box you thought it was in.

Stick to icons you know render: cloud, database, disk, internet, and server. An unknown icon name may leave you with a blank mark. If you need a specific vendor logo, this simple form is the wrong place to reach for it.

An edge names the sides it leaves and enters. api:R --> L:db leaves the right of the API and arrives at the left of the database. T, B, L, and R are the four sides. One arrow is a claim that this is the path you want to talk about. Arrows between every pair hide the group.

The group label should be a boundary a person can point at: a cloud account, a cluster, a region. "Backend" is vague. "Cloud" is fine for a sketch and weak for a design review. Rename it when you know the real boundary.

Worked example

An API and a database sit in one cloud group. The API talks to the database.

Mermaid diagram
mermaid
architecture-beta
    group cloud(cloud)[Cloud]
    service api(server)[API] in cloud
    service db(database)[Database] in cloud
    api:R --> L:db
Open in the live editor

The group is the boundary. Both services say in cloud, so both are inside it. The API uses the server icon and the database uses the database icon, which is the whole legend. The edge says the API initiates the path toward the database. It doesn't say which query, which port, or which network. Those facts belong in a sentence under the figure or on a sequence diagram.

If the database were managed outside the account, you would omit in cloud on that service, or give it a second group. Leaving it inside because the icon looked nicer is how these diagrams fib. Membership is the in clause, not the visual you hope for.

A load balancer would be another service, often with the internet icon, and a second edge into the API. Add it when the audience needs it. A context meeting often needs the group and these two boxes and nothing else. If you can't say which side of the group a new box belongs on, you're not ready to add it. Put the unknown in the paragraph under the figure and keep the drawing to the boxes you can place.

When this is the wrong diagram

A C4 diagram is the better picture when you're naming people and system boundaries without deployment icons. A flowchart is the better picture of request decisions. Use an architecture diagram when the group is a real boundary and the icons distinguish servers from data stores.

Common mistakes

  1. Forgetting in cloud on a service that should sit inside the group. The service renders outside the boundary, and the picture denies the membership.
  2. An icon name outside the small built-in set. Prefer cloud, database, disk, internet, and server so the mark is one readers can decode.
  3. An edge that names the wrong side, such as L when you meant the arrow to leave on the right. api:R --> L:db leaves the API's right side.
  4. A group called "Backend" that contains the entire company. The group should be a boundary you can deploy or revoke.

Where to go next

The AI architecture generator will place services from a short infrastructure note. Confirm each in clause in the editor, and the cheat sheet lists the icon names. The Kubernetes architecture template is a denser deployment if this two-service sketch is only the start.

Groups are deployables

An architecture diagram groups services that ship together. A group named "Backend" that contains the database, the queue, and three APIs is a sketch. A group named after the process that actually runs is a diagram you can use in an incident. Edges are calls or data movement, labeled with the thing that moves (orders, metrics), not with "uses".

Icons are optional. A missing icon with a clear label beats a cloud icon on a box that is really a cron job. The architecture guide talks about which picture to draw first, and this page is the syntax for the cloud layout. The Kubernetes template is a worked set of groups.

System rows without icons are the schematic diagram creator and the text to schematic diagram posts. Cloud sketches that stay honest about missing vendor icons are Mermaid AWS diagrams.

Tips and best practices

  • Edge sides (T, B, L, R) control layout — plan the flow left to right.
  • Use groups for VPCs, regions or clusters.
  • Keep it high level; use C4 container diagrams for application detail.

Generate a architecture diagram with AI

Not sure where to start? Describe what you need and the AI architecture diagram generator writes the Mermaid code for you. Try prompts like:

  • “AWS serverless architecture with API Gateway, Lambda and DynamoDB”
  • “Kubernetes deployment with ingress and database”
  • “Static site with CDN and object storage”

Architecture Diagram templates

Architecture Diagram FAQ

Which icons are available in Mermaid architecture diagrams?

Built in: cloud, database, disk, internet and server. Additional icon packs (for example logos from Iconify) can be registered by the host application.