← All Articles
Gagan Thakur·

Mermaid.js for Microservices Architecture Diagrams (2026 Guide)

Learn how to diagram microservices architectures with Mermaid.js. Covers service maps, API gateways, event flows, and deployment topologies with copy-paste examples.

# Mermaid.js for Microservices Architecture Diagrams

Microservices architectures are notoriously hard to communicate. Dozens of services, multiple teams, async event flows, and cloud infrastructure — none of it fits neatly into a single diagram. Mermaid.js gives you a text-based, version-controlled way to visualise it without opening a drawing tool.

Why Mermaid for Microservices?

- Diagrams live in the repo as plain text — next to the service they describe

- Changes are reviewable in pull requests just like code

- Renders natively on GitHub, GitLab, Notion, and Confluence with no plugins

- Fast to create — a 10-service map takes 5 minutes, not 50

High-Level Service Map

Start with a bird's-eye view. Group services by domain using subgraphs:

graph TB
    subgraph Client Layer
        Web[Web App]
        Mobile[Mobile App]
    end
    subgraph API Gateway
        GW[Kong / API Gateway]
        Auth[Auth Service]
    end
    subgraph Core Services
        Users[User Service]
        Orders[Order Service]
        Products[Product Service]
        Payments[Payment Service]
    end
    subgraph Data Stores
        UserDB[(User DB)]
        OrderDB[(Order DB)]
        Cache[(Redis Cache)]
    end
    Web & Mobile --> GW
    GW --> Auth
    GW --> Users & Orders & Products & Payments
    Users --> UserDB
    Orders --> OrderDB
    GW --> Cache
Try in Editor →

API Gateway Routing

graph LR
    Client[Client] --> GW[API Gateway]
    GW -->|GET /users| UserSvc[User Service :3001]
    GW -->|POST /orders| OrderSvc[Order Service :3002]
    GW -->|GET /products| ProdSvc[Product Service :3003]
    GW -->|POST /payments| PaySvc[Payment Service :3004]
    UserSvc --> UserDB[(users)]
    OrderSvc --> OrderDB[(orders)]
    ProdSvc --> ProductDB[(products)]
    PaySvc --> StripeAPI[Stripe API]
Try in Editor →

Sync vs Async Communication

Mermaid arrow styles distinguish synchronous HTTP and async messaging:

graph LR
    OrderSvc[Order Service]
    PaySvc[Payment Service]
    InventorySvc[Inventory Service]
    EmailSvc[Email Service]
    MQ[Message Broker RabbitMQ]

    OrderSvc -->|HTTP charge| PaySvc
    OrderSvc -.->|event order.created| MQ
    MQ -.->|order.created| InventorySvc
    MQ -.->|order.created| EmailSvc
Try in Editor →

Solid arrows = synchronous calls. Dashed arrows = async messages.

Event-Driven Flow

sequenceDiagram
    autonumber
    actor Customer
    participant GW as API Gateway
    participant OS as Order Service
    participant PS as Payment Service
    participant MQ as Message Broker
    participant IS as Inventory Service
    participant ES as Email Service

    Customer->>GW: POST /orders
    GW->>+OS: Create order
    OS->>+PS: Charge card
    PS-->>-OS: Payment confirmed
    OS->>MQ: publish order.confirmed
    OS-->>-GW: 201 Created
    GW-->>Customer: Order ID

    par Async handlers
        MQ-->>IS: order.confirmed
        IS->>IS: Reserve stock
        and
        MQ-->>ES: order.confirmed
        ES->>ES: Send confirmation email
    end
Try in Editor →

CQRS Pattern

graph TB
    subgraph Write Side
        CMD[Command Handler]
        EventStore[Event Store]
        Agg[Aggregate Root]
    end
    subgraph Message Bus
        MQ[Event Bus]
    end
    subgraph Read Side
        Proj[Projector]
        ReadDB[(Read Model DB)]
        QH[Query Handler]
    end
    Client[Client] -->|Command| CMD
    CMD --> Agg
    Agg -->|Event| EventStore
    EventStore -->|Publish| MQ
    MQ -->|Subscribe| Proj
    Proj --> ReadDB
    Client -->|Query| QH
    QH --> ReadDB
Try in Editor →

Service Health State Machine

Document circuit breaker behaviour for reliability runbooks:

stateDiagram-v2
    [*] --> Healthy
    Healthy --> Degraded : Error rate greater than 1 percent
    Degraded --> Healthy : Error rate below 0.1 percent
    Degraded --> CircuitOpen : Error rate greater than 10 percent
    CircuitOpen --> HalfOpen : After 30 seconds
    HalfOpen --> Healthy : Probe success
    HalfOpen --> CircuitOpen : Probe failed
Try in Editor →

Domain Ownership Map

graph TB
    subgraph Identity Team
        AuthSvc[Auth Service]
        UserSvc[User Service]
    end
    subgraph Commerce Team
        OrderSvc[Order Service]
        CartSvc[Cart Service]
        CheckoutSvc[Checkout Service]
    end
    subgraph Payments Team
        PaySvc[Payment Service]
        FraudSvc[Fraud Detection]
    end
    subgraph Platform Team
        GW[API Gateway]
        MQ[Message Broker]
    end
    GW --> AuthSvc
    GW --> OrderSvc
    GW --> CartSvc
    CheckoutSvc --> PaySvc
    PaySvc --> FraudSvc
    OrderSvc --> MQ
Try in Editor →

Best Practices

One diagram per audience. Your infrastructure topology is not the same document as the PM's feature flow.

Use consistent naming. If the service is called user-service in Kubernetes, use the same name in the diagram.

Put diagrams in the service repo. A docs/architecture.md in each repo keeps documentation with the team that owns the code.

Show failure paths. Use alt blocks in sequence diagrams or dashed fallback arrows to document what happens when a service is down.

Version your diagrams. A Changelog section tracks how the system evolved — invaluable for post-mortems.

A Complete Microservices Doc Needs Four Diagrams

  1. Service Map (flowchart) — all services and relationships at a glance
  2. Event Flow (sequence diagram) — a critical user journey documented end-to-end
  3. State Machine (state diagram) — service health or circuit breaker lifecycle
  4. Domain Ownership (subgraph flowchart) — which team owns what

All four live as plain text in your repo, render on GitHub and GitLab natively, and update in the same pull request as the code they describe. No PNG exports, no stale diagrams.

Try these examples in the free Mermaid Editor →

Try it now in our free Mermaid Live Editor →
← All Articles