Mermaid block diagrams for system architecture

When designing a system—or explaining how it works—you need a shared picture: "Where does the data flow? Which services talk to each other? What are the boundaries?" Block diagrams answer that question in seconds without the overhead of formal architecture languages.

Mermaid's block-beta diagram type (a simpler cousin of C4 models) lets engineers and non-engineers alike sketch architectures in text, review them in pull requests, and keep them in sync with the actual system.

Block diagram basics

A block diagram has blocks (rectangles representing components), columns (swim lanes for ownership or layers), and arrows (connections and data flows):

block-beta
    columns 3
    space A["User Interface"] space
    B["API Gateway"] C["Auth Service"] space
    D["Order Service"] E["Payment Service"] F["Inventory Service"]
    space G["Database"] space
    A --> B
    B --> D
    B --> E
    B --> F
    D --> G
    E --> C
    F --> G

Blocks are simple rectangles. Connections show data flow or dependency. The columns directive organizes blocks into layers (useful for showing API tier, service tier, data tier, etc.).

Real-world example: microservices architecture

Here's a typical three-tier microservices stack:

block-beta
    columns 3
    block:web:3
        A["Web Browser"]
        B["Mobile App"]
    end
    block:gateway:3
        C["API Gateway"]
        D["Load Balancer"]
    end
    block:services:3
        E["User Service"]
        F["Order Service"]
        G["Notification Service"]
    end
    block:data:3
        H["PostgreSQL"]
        I["Redis Cache"]
        J["Message Queue"]
    end
    block:external:3
        K["Stripe"]
        L["SendGrid"]
    end
    A --> D
    B --> D
    D --> C
    C --> E
    C --> F
    C --> G
    E --> H
    E --> I
    F --> H
    F --> J
    G --> J
    G --> L
    J --> K

This diagram makes it immediately clear:

• Clients (web, mobile) route through a load balancer
• The API gateway fans out to multiple services
• Services share a database and cache
• Async work flows through a message queue
• External services (Stripe, SendGrid) are called on demand

Layered architecture with swim lanes

Organize blocks by team ownership or architectural tier:

block-beta
    columns 4
    block:frontend:4
        A["React App"]
        B["Next.js Server"]
    end
    block:middleware:4
        C["API Gateway"]
        D["Service Mesh"]
    end
    block:backend:4
        E["Auth Service"]
        F["Core API"]
        G["Search Service"]
    end
    block:data:4
        H["Primary DB"]
        I["Search Index"]
        J["Cache"]
    end
    A --> B
    B --> C
    C --> D
    D --> E
    D --> F
    D --> G
    E --> H
    F --> H
    F --> I
    F --> J
    G --> I

Readers see at a glance which team owns which tier, what the service boundaries are, and where data lives.

Event-driven architecture

Block diagrams work well for showing event flows:

block-beta
    columns 3
    block:events:3
        A["Event Producer"]
    end
    block:routing:3
        B["Message Broker<br/>(RabbitMQ)"]
    end
    block:consumers:3
        C["Email Notifier"]
        D["Analytics Engine"]
        E["Sync Service"]
    end
    block:persistence:3
        F["Event Log"]
        G["Data Warehouse"]
        H["Integration DB"]
    end
    A --> B
    B --> C
    B --> D
    B --> E
    B --> F
    C --> H
    D --> G
    E --> H

The diagram shows:

• One producer publishes events to a broker
• Multiple independent consumers listen and react
• Events are logged for audit and replay
• Each consumer writes to its own persistence layer

Tips for effective architecture diagrams

Show only what matters:
A block diagram doesn't need to include every internal class or function. Include services, databases, external APIs, and major data stores. Leave out implementation details.

Use clear, specific names:
"Auth Service" is better than "Auth" or "Service A". "PostgreSQL (Orders DB)" is more useful than "DB".

Show data flow direction:
Use arrows to show which component calls which. Request/response flows left-to-right or top-to-bottom. Make causality visible.

Separate concerns by column:
Put presentation in the left column, business logic in the middle, data in the right. Put external services in a separate column. This layering helps readers understand boundaries.

Include external systems:
Don't hide dependencies on third-party services (Stripe, AWS, SendGrid, etc.). It helps new team members understand the full system and security/compliance reviewers see integration points.

Keep it current:
The moment your architecture changes, update the diagram. A diagram that's three months stale is worse than no diagram—it spreads misinformation.

Block diagrams vs. C4 models vs. ER diagrams

Each serves a different purpose:

Diagram	Shows	Best for
Block diagram	Components, connections, layers	System overview, architecture review
C4 diagram	System context, containers, components, code	Detailed architecture drilling-down
ER diagram	Tables, columns, relationships	Database schema, data modeling
Flowchart	Logic, decisions, branches	Business processes, algorithms

Use block diagrams for high-level architecture; C4 models for drilling into detail; ER diagrams for the database layer; flowcharts for process logic.

From sketch to documentation

Block diagrams are perfect for design documents:

1. Design review: Present the diagram in a PR or design doc. Ask for feedback on boundaries, data flows, and scalability.
2. Onboarding: New engineers read the diagram first, then dive into code. It provides a mental model.
3. Decision history: Keep the diagram in your repo (e.g., docs/architecture/system-diagram.md). When it changes, the PR explains why.
4. Architecture Decision Records (ADRs): When you decide to add a service or change a flow, include the updated block diagram in the ADR.

FAQ

Should I include test infrastructure and CI/CD?
Only if it's essential to understanding the production system. Keep diagrams focused on runtime architecture. CI/CD gets its own diagram if needed.

Can I show multiple versions of the same diagram?
Yes. Create separate documents for "current architecture" and "proposed migration." The comparison helps stakeholders understand the change.

What if the system is too complex for one diagram?
Break it into multiple diagrams: one for overall system, one for the API tier, one for data processing, etc. Or use a C4 model that lets you zoom into detail.

How do I decide when to update the diagram?
When a new service is added, when services are merged, or when the data flow significantly changes. Don't update for internal refactors or bug fixes—those don't change the architecture as external observers see it.

Start sketching your architecture in the MermaidCreator editor—block diagrams are powerful for communicating design without heavy tooling.