Basic architecture diagram example
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:filesArchitecture 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
| Syntax | What it does |
|---|---|
architecture-beta | Start an architecture diagram. |
group id(icon)[Label] | A group/boundary; can be nested with in parent. |
service id(icon)[Label] in group | A service with an icon, optionally inside a group. |
Icons: cloud, database, disk, internet, server | Built-in icons (more via icon packs). |
a:R -- L:b | Edge from the right side of a to the left side of b (T, B, L, R). |
a:R --> L:b | Edge with an arrow. |
junction id | A 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.
architecture-beta
group cloud(cloud)[Cloud]
service api(server)[API] in cloud
service db(database)[Database] in cloud
api:R --> L:dbThe 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
- Forgetting
in cloudon a service that should sit inside the group. The service renders outside the boundary, and the picture denies the membership. - An icon name outside the small built-in set. Prefer
cloud,database,disk,internet, andserverso the mark is one readers can decode. - An edge that names the wrong side, such as
Lwhen you meant the arrow to leave on the right.api:R --> L:dbleaves the API's right side. - 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.