MermaidBlock DiagramsSystem ArchitectureSoftware DesignDocumentation

Block diagrams for system architecture: boxes and flows in Mermaid

June 15, 20265 min readThe MermaidCreator team

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 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
    columns 3
    block:col1
        space
    block:col2
        A["User Interface"]
    block:col3
        space
    
    space
    B["API Gateway"]
    C["Auth Service"]
    
    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
    columns 3
    block:web
        A["Web Browser"]
        B["Mobile App"]
    block:api
        C["API Gateway"]
        D["Load Balancer"]
    block:services
        E["User Service"]
        F["Order Service"]
        G["Notification Service"]
    
    block:data
        H["PostgreSQL"]
        I["Redis Cache"]
        J["Message Queue"]
    
    block:external
        K["Stripe"]
        L["SendGrid"]
    
    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
    columns 4
    space
    space
    space
    space
    
    block:frontend
        A["React App"]
        B["Next.js Server"]
    block:middleware
        C["API Gateway"]
        D["Service Mesh"]
    block:backend
        E["Auth Service"]
        F["Core API"]
        G["Search Service"]
    block:data
        H["Primary DB"]
        I["Search Index"]
        J["Cache"]
    
    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
    columns 3
    block:events
        A["Event Producer"]
    block:routing
        B["Message Broker<br/>(RabbitMQ)"]
    block:consumers
        C["Email Notifier"]
        D["Analytics Engine"]
        E["Sync Service"]
    
    block:persistence
        F["Event Log"]
        G["Data Warehouse"]
        H["Integration DB"]
    
    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:

Design review: Present the diagram in a PR or design doc. Ask for feedback on boundaries, data flows, and scalability.
Onboarding: New engineers read the diagram first, then dive into code. It provides a mental model.
Decision history: Keep the diagram in your repo (e.g., docs/architecture/system-diagram.md). When it changes, the PR explains why.
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.

Mermaid