Most developers have sketched a system architecture on a whiteboard, snapped a photo, and lost it in a chat thread within a week. Diagrams built with mermaid code solve that problem they live inside your repository as plain text, version with your code, and render into readable visuals without any design tools. If you've been searching for mermaid code for system architecture diagram examples, this article covers what the syntax looks like, where it works well, and where it falls short.

What is Mermaid code, and why do developers use it for architecture diagrams?

Mermaid is a JavaScript-based diagramming tool that uses a text-based syntax to generate diagrams. You write simple markup, and it renders flowcharts, sequence diagrams, class diagrams, and more. For system architecture, developers typically use the graph (flowchart) or C4Context diagram types to represent components, services, databases, and how they connect.

The reason it shows up so often in engineering workflows is straightforward: diagrams-as-code means your architecture visuals are stored alongside your source code. They go through pull requests like everything else. No one has to hunt for the "latest version" in a Confluence page or a Figma file that's three months stale.

What does basic mermaid code for a system architecture diagram look like?

A simple architecture diagram in mermaid uses the graph or flowchart keyword. Here's a basic example showing a web application with a frontend, API, database, and cache:

graph TD
  Client[Web Browser] -->|HTTP| LB[Load Balancer]
  LB --> API1[API Server 1]
  LB --> API2[API Server 2]
  API1 --> DB[(PostgreSQL)]
  API2 --> DB
  API1 --> Cache[(Redis)]
  API2 --> Cache
  API1 --> MQ[Message Queue]
  API2 --> MQ
  MQ --> Worker[Background Worker]
  Worker --> DB

This produces a top-down diagram with labeled nodes and directional arrows. The [(PostgreSQL)] syntax creates a cylinder shape, which most people read as a database. The |HTTP| text on the arrow adds an edge label. It's minimal, but it communicates the structure clearly.

How do you represent different infrastructure components?

Mermaid's flowchart syntax lets you control node shapes to distinguish between component types. Here are the shapes commonly used in architecture diagrams:

  • Rectangles Node[Label] used for services, APIs, and general components
  • Cylinders Node[(Label)] used for databases and storage
  • Rounded rectangles Node(Label) sometimes used for external services or user-facing components
  • Diamonds Node{Label} useful for decision points or gateways
  • Subgraphs group related components into logical boundaries (VPCs, namespaces, zones)

Subgraphs are especially useful for architecture work. They let you draw a box around components that belong together:

graph TD
  subgraph "Production VPC"
    subgraph "Public Subnet"
      LB[Load Balancer]
    end
    subgraph "Private Subnet"
      API[API Server]
      DB[(Database)]
    end
  end
  Client[Browser] --> LB --> API --> DB

This mirrors how you'd think about network boundaries in a real deployment. It reads like infrastructure, which is the whole point.

When does mermaid work well for architecture diagrams, and when doesn't it?

Mermaid shines in a few specific situations:

  • Documentation in Markdown files GitHub, GitLab, and many docs platforms render mermaid natively. Your architecture diagram sits right next to the code it describes.
  • Lightweight system overviews When you need to show how 5–15 components connect, mermaid is fast to write and easy to maintain.
  • Version-controlled diagrams Because the source is text, you get diff-friendly changes. You can see exactly what changed in an architecture diagram between commits.
  • Onboarding docs New team members can read the diagram source and the rendered output. No proprietary tools needed.

Where it starts to struggle:

  • Very large systems Once you cross 20–30 nodes, the rendered diagram becomes crowded and hard to read. Mermaid's automatic layout engine has limits.
  • Exact layout control You can choose top-down (TD), left-right (LR), and a few other directions, but you can't pin nodes to specific positions. If the auto-layout puts two nodes in a confusing spot, your options to fix it are limited.
  • Detailed infrastructure specs If you need to show port numbers, protocol details, security groups, and IAM roles on every connection, the syntax gets verbose and the visual gets cluttered.

For complex enterprise systems, the C4 model DSL notation might be a better fit since it's designed specifically for layered architecture views at different zoom levels.

How do you diagram a real microservices architecture in mermaid?

Here's a more realistic example an e-commerce system with multiple services, an event bus, and external integrations:

graph TD
  subgraph "Client Layer"
    Web[Web App]
    Mobile[Mobile App]
  end
  subgraph "API Gateway"
    GW[Kong Gateway]
  end
  subgraph "Services"
    Auth[Auth Service]
    Catalog[Catalog Service]
    Order[Order Service]
    Payment[Payment Service]
    Notification[Notification Service]
  end
  subgraph "Data Stores"
    AuthDB[(Auth DB)]
    CatalogDB[(Catalog DB)]
    OrderDB[(Order DB)]
  end
  subgraph "Infrastructure"
    EventBus[Event Bus / Kafka]
  end
  
  Web --> GW
  Mobile --> GW
  GW --> Auth
  GW --> Catalog
  GW --> Order
  Auth --> AuthDB
  Catalog --> CatalogDB
  Order --> OrderDB
  Order -->|payment.requested| EventBus
  Payment -->|subscribes| EventBus
  EventBus -->|payment.completed| Notification
  Payment -->|API call| Stripe[Stripe API]

This communicates service ownership, data boundaries, async communication patterns, and external dependencies. It's not a deployment diagram, but for a high-level system overview it tells a clear story.

What are common mistakes people make with mermaid architecture diagrams?

1. Trying to put everything on one diagram. Real systems have dozens of services, databases, queues, caches, cron jobs, and third-party integrations. Don't try to show all of them. Create separate diagrams for different subsystems or use the C4 model's approach of drilling down from context to container to component.

2. Using vague labels. "Service A" and "Service B" tell nobody anything. Use the actual service name or at minimum its function: "Order Service," "Payment Processor," "Inventory Cache."

3. Forgetting to show data flow direction. Arrows matter. An arrow from Service A to Database B means A writes to B. If the read path is different, show it. If data flows both ways, label the arrows with what moves in each direction.

4. Ignoring the rendering context. Mermaid diagrams render differently depending on where you view them GitHub Markdown preview, VS Code extension, the Mermaid Live Editor, or a static site generator. Test your diagram in the environment where your team will actually see it.

5. Not using link text on edges. Unlabeled arrows in a system with many connections become a mess of spaghetti lines. Even short labels like "REST," "gRPC," "async," or "SQL" make the diagram significantly more readable.

How does mermaid compare to other diagram-as-code tools?

Mermaid isn't the only option. D2 language is another diagram DSL that gives more layout control and handles larger diagrams better. PlantUML has been around longer and supports more diagram types but uses a heavier syntax. Structurizr is purpose-built for C4 models.

Mermaid's main advantage is adoption. It's built into GitHub, GitLab, Notion, Obsidian, and many other tools your team already uses. That lower friction for viewing diagrams matters the best architecture diagram is worthless if people can't easily see it.

What tips help you write cleaner mermaid architecture diagrams?

  1. Start with the flow, not the syntax. Sketch the architecture on paper first. Identify the main components and how they connect. Then translate to mermaid code.
  2. Use subgraphs to group logically related components. This creates visual boundaries that help readers understand which pieces belong together.
  3. Pick LR (left-right) for wide systems and TD (top-down) for layered ones. Most web architectures with an API gateway pattern read better left-right. Layered stack diagrams read better top-down.
  4. Keep a consistent style. If you use cylinders for databases in one diagram, do it everywhere. Inconsistent shapes confuse readers.
  5. Add a title or legend. Mermaid supports a %% comment syntax for notes. If your diagram represents a specific environment (staging, production), note that clearly.
  6. Store diagrams close to the code they describe. Put the mermaid source in a /docs folder or directly in a README file next to the service it documents.

Practical checklist for your next architecture diagram

  • ☐ List all components you need to show and group them by layer or boundary
  • ☐ Choose TD or LR direction based on your system's structure
  • ☐ Use subgraphs for logical groupings (network zones, service layers, data tiers)
  • ☐ Label every arrow with the protocol, data type, or communication pattern
  • ☐ Use consistent shapes: rectangles for services, cylinders for databases, rounded for external systems
  • ☐ Keep node count under 20–25 per diagram split into multiple diagrams if needed
  • ☐ Render the diagram in your target platform (GitHub, GitLab, docs site) to verify it looks correct
  • ☐ Commit the .md or .mmd source file to version control alongside the code
  • ☐ Add a short text description above or below the diagram explaining what it shows and its scope
  • ☐ Review and update the diagram whenever the architecture changes stale diagrams are worse than no diagrams