If you're building software, documenting systems, or explaining infrastructure to your team, you've probably needed a quick way to draw architecture diagrams without firing up a heavy diagramming tool. Mermaid's architecture diagram markup language lets you describe your system components and their connections in plain text, then renders them automatically. This reference covers the syntax, practical examples, and real pitfalls so you can start using it immediately.

What Is the Mermaid Architecture Diagram Markup Language?

Mermaid is a JavaScript-based diagramming tool that turns text descriptions into visual diagrams. Its architecture diagram feature introduced in version 10.3 lets you define nodes (representing services, databases, servers, or any component) and groups (to cluster related components) using a simple text-based syntax. You write the markup; Mermaid renders the visual output.

Unlike drag-and-drop tools, this text-based approach keeps diagrams version-controllable. You can store them in Git alongside your code, review changes in pull requests, and regenerate visuals any time.

How Does the Architecture Diagram Syntax Work?

An architecture diagram in Mermaid starts with the architecture-beta keyword. From there, you define groups and nodes using a structured format.

Defining Groups

Groups let you organize related components into logical clusters like putting all your API services inside one boundary and all your databases inside another.

The syntax follows this pattern:

group api(cloud)[API Layer]

Breaking this down:

  • api the unique ID you assign to this group
  • cloud the icon (optional; Mermaid supports a set of built-in icon packs)
  • API Layer the display label shown in the rendered diagram

Defining Nodes

Nodes represent individual components like servers, databases, or client apps:

node db(database)[Users Database]

Here:

  • db the unique ID
  • database the icon type
  • Users Database the label

Adding Edges (Connections)

Edges define how components connect to each other:

api:L -- R:db

The L and R specify the direction of the connection (Left and Right). You can also use T (Top) and B (Bottom) to control where the edge attaches to each node.

For a deeper look at how architecture diagram syntax works across different tools, our architecture diagram syntax guide for software engineers covers the broader patterns you'll encounter.

What Does a Full Mermaid Architecture Diagram Look Like?

Here's a practical example of a web application architecture:

architecture-beta
 group api(cloud)[API]

 service web(internet)[Web App] in api
 service server(server)[API Server] in api
 service cache(database)[Cache] in api

 group data(cloud)[Data]

 db users(database)[Users DB] in data
 db logs(database)[Logs DB] in data

 web:L -- R:server
 server:B -- T:cache
 server:L -- R:users
 server:B -- T:logs

This produces a diagram showing a web app talking to an API server, which connects to a cache and two databases. The groups visually separate the API layer from the data layer.

Which Icon Packs Does Mermaid Support for Architecture Diagrams?

Mermaid includes icon support through specific packs. Commonly used icon categories include:

  • cloud for cloud-related groupings
  • database for data stores
  • server for compute nodes
  • internet for web-facing components
  • node generic node representations

You reference these icons directly in the node or group definition. If you need custom or unsupported icons, you may need to work within Mermaid's current limitations or use alternative tools for that specific diagram.

When Should You Use Mermaid Architecture Diagrams Instead of Other Tools?

Mermaid architecture diagrams fit well when:

  • You want diagrams stored as text in a repository
  • Your documentation platform supports Mermaid natively (GitHub, GitLab, Notion, Obsidian, and many others do)
  • You need fast iteration without switching tools
  • You want non-designers on your team to contribute to diagrams

They work less well when you need pixel-perfect layouts, complex custom styling, or very large diagrams with 50+ components where automatic layout algorithms struggle to keep things readable.

If you're comparing approaches across markup languages, our comparison of PlantUML and Mermaid for system architecture notation breaks down the trade-offs in detail.

What Common Mistakes Do People Make with Mermaid Architecture Diagrams?

  1. Using duplicate IDs. Every node and group needs a unique identifier. Reusing an ID causes rendering errors or unexpected behavior.
  2. Forgetting the beta keyword. The architecture diagram type uses architecture-beta, not just architecture. If your diagram doesn't render, check this first.
  3. Mismatched edge directions. The directional labels (L, R, T, B) must match the actual spatial relationship you want. Putting L on both sides of an edge doesn't produce a clean layout.
  4. Skipping the group definition when placing nodes. If you reference a group ID in a node's in clause but never defined that group, the diagram fails silently or renders incorrectly.
  5. Overloading a single diagram. Cramming too many nodes into one diagram makes it unreadable. Split complex systems into multiple focused diagrams instead.

How Do Mermaid Architecture Diagrams Compare to UML Component Diagrams?

Mermaid architecture diagrams are not UML. They don't follow UML specification rules, and they don't support stereotypes, interfaces, or the full range of UML relationships. They're a lighter-weight notation aimed at showing system structure quickly.

If you need formal UML component diagrams especially for microservices documentation where you want to show ports, interfaces, and dependency directions our UML component diagram syntax reference for microservices covers that in detail.

For most team discussions, architecture reviews, and README documentation, Mermaid's simplified approach is enough. For formal design documents or compliance-heavy environments, you might need something closer to UML.

Where Can You Render Mermaid Architecture Diagrams?

You have several options:

  • Mermaid Live Editor test and preview diagrams in your browser without installing anything
  • GitHub and GitLab both render Mermaid code blocks in Markdown files automatically
  • VS Code the Mermaid extension previews diagrams directly in your editor
  • Static site generators tools like MkDocs, Docusaurus, and Astro have Mermaid plugins
  • Mermaid CLI generate SVG or PNG output from the command line for CI/CD pipelines

Tips for Writing Cleaner Mermaid Architecture Diagrams

  • Name your IDs with intent. Use auth-service instead of s1. Readable IDs make the source text easier to maintain.
  • Keep related components in groups. Groups aren't just visual they help your teammates understand system boundaries at a glance.
  • Use directional edges deliberately. Think about which side of each node the connection should attach to before writing the edge. Sketch it on paper first if needed.
  • Version your diagrams. Since they're text files, commit them to Git. When your architecture changes, the diagram change shows up in the same pull request as the code change.
  • Test rendering early. Don't write 40 lines of markup and then check. Render after every few lines to catch syntax issues while they're easy to find.

Quick Reference Checklist for Mermaid Architecture Diagrams

  • Start with architecture-beta as the first line
  • Define groups with group id(icon)[Label]
  • Define nodes with node id(icon)[Label] or service id(icon)[Label]
  • Place nodes inside groups using in group-id
  • Connect components with id1:Direction -- Direction:id2
  • Use L, R, T, B to control edge attachment points
  • Give every element a unique, descriptive ID
  • Render and preview after every few lines of markup
  • Store diagram source files in version control alongside your code
  • Split large diagrams into smaller, focused views for readability