How to Draw Architecture Diagrams in Mermaid

2026-03-05 · MermZen Tutorial

Architecture diagrams visualize system architectures, component relationships, and deployment patterns. They are ideal for system design, architecture reviews, and technical documentation. Mermaid uses architecture-beta keyword for architecture diagrams.

Why Use Architecture Diagrams?

Architecture diagrams are core tools for system design and documentation:

• Visualize system structure — See at a glance what components make up the system and how they interact
• Architecture review essential — Identify potential issues during design phase, avoid rework later
• Team communication bridge — Help new members quickly understand the system landscape
• Technical documentation core — Visual representation of architecture design documents

Use Cases

✅ Suitable:

• System design phase — Plan overall architecture
• Architecture review — Discuss design decisions with team
• Technical documentation — Record system structure
• New member onboarding — Quick overview of system

❌ Not Suitable:

• Showing code logic flow → Use flowchart
• Showing time sequence → Use sequence diagram
• Showing single module internals → Use class diagram

Comparison with Other Diagrams

Selection Guide:

• Show "what components exist, how they connect" → Architecture diagram
• Show "module nesting structure" → Block diagram
• Show "operation flow and decision branches" → Flowchart

Declaring a Chart

Use architecture-beta keyword:

architecture-beta
    title System Architecture Diagram

Component Definition

Define system components including services, databases, external systems:

architecture-beta
    title Basic Architecture Components
    container "Frontend Application" {
        component "User Interface"
        component "API Calls"
    }
    container "Backend Services" {
        component "Business Logic"
        component "Data Access"
    }
    database "Database" {
        component "User Data"
        component "Business Data"
    }
    system "External Payment System"

Connection Relationships

Define connections and dependencies between components:

architecture-beta
    title Component Relationship Diagram
    container "Frontend Application" {
        component "User Interface"
        component "API Calls"
    }
    container "Backend Services" {
        component "Business Logic"
        component "Data Access"
    }
    database "Database" {
        component "User Data"
        component "Business Data"
    }
    system "External Payment System"

    "User Interface" --> "API Calls"
    "API Calls" --> "Business Logic"
    "Business Logic" --> "Data Access"
    "Data Access" --> "User Data"
    "Data Access" --> "Business Data"
    "Business Logic" --> "External Payment System"

Full Example: Microservices Architecture

architecture-beta
    title E-Commerce System Microservices Architecture
    container "User Interface Layer" {
        component "Web Interface"
        component "Mobile App"
        component "Admin Console"
    }
    container "API Gateway" {
        component "Request Routing"
        component "Authentication"
        component "Rate Limiting & Circuit Breaking"
    }
    container "Business Services Layer" {
        component "User Service"
        component "Product Service"
        component "Order Service"
        component "Payment Service"
        component "Inventory Service"
    }
    database "Data Storage" {
        component "MySQL Primary"
        component "MySQL Replica"
        component "Redis Cache"
    }
    system "External Systems" {
        component "Alipay"
        component "WeChat Pay"
        component "Logistics System"
    }

    "Web Interface" --> "API Gateway"
    "Mobile App" --> "API Gateway"
    "Admin Console" --> "API Gateway"

    "API Gateway" --> "User Service"
    "API Gateway" --> "Product Service"
    "API Gateway" --> "Order Service"
    "API Gateway" --> "Payment Service"
    "API Gateway" --> "Inventory Service"

    "User Service" --> "MySQL Primary"
    "User Service" --> "Redis Cache"
    "Product Service" --> "MySQL Primary"
    "Product Service" --> "Redis Cache"
    "Order Service" --> "MySQL Primary"
    "Inventory Service" --> "MySQL Primary"

    "Payment Service" --> "Alipay"
    "Payment Service" --> "WeChat Pay"
    "Order Service" --> "Logistics System"

Best Practices

Component Organization Principles

• Organize by layers: User Interface Layer → API Gateway → Business Services Layer → Data Storage
• Keep component granularity consistent: Components at the same level should be at the same abstraction level
• Distinguish internal vs external: Use container for internal components, system for external systems

Connection Guidelines

• Avoid over-connection: Single component connections should not exceed 5
• Clear direction: Use --> to clearly indicate data/call flow direction
• Hierarchical clarity: Define high-level connections first, then internal connections

Naming Conventions

Common Mistakes

Mistake 1: Too Many Connections Creating Clutter

❌ Problem: Drawing connections between all components creates a "spaghetti" diagram

✅ Solution: Only draw major call relationships, document minor ones in text or split into multiple diagrams

Mistake 2: Inconsistent Abstraction Levels

❌ Problem: Mixing "User Service" and "getUser API" at the same level

✅ Solution: Keep components at the same level at the same abstraction level

Mistake 3: Ignoring Data Flow Direction

❌ Problem: Only drawing components without showing data/call flow direction

✅ Solution: Use --> to clearly mark call direction, making the architecture diagram reflect actual system interactions

Quick Reference

Next Step

After mastering architecture diagrams, continue learning Mermaid Block Diagrams for complex system architecture and process flow visualization.

To try the above code in MermZen, click Open Editor and paste the code there.