Mermaid Diagramming Style Guide

Standards for creating consistent, readable Mermaid diagrams in documentation.

General Principles

MUST follow these principles for every diagram:

Principle	Rule	Example
One concern per diagram	NEVER show everything in one diagram	Split architecture from data flow
Consistent naming	MUST use actual resource/service names	userService not service1
Clear flow direction	ALWAYS use LR or TD consistently	Left-to-right for pipelines
Logical grouping	MUST use subgraphs for related components	Group by layer or domain
Descriptive labels	ALWAYS label every connection	"HTTPS/REST" not empty

Diagram Type Selection

C4 Container Diagrams

MUST use for: System architecture, microservices topology, cloud infrastructure

C4Container
    title System Architecture

    Person(user, "User", "Description")
    Container(service, "Service Name", "Technology", "Purpose")
    ContainerDb(db, "Database", "Type", "What it stores")

    Rel(user, service, "Action", "Protocol")
    Rel(service, db, "Action", "Protocol")

Flowcharts

MUST use for: Processes, workflows, decision trees, deployment pipelines

flowchart TD
    Start([Start]) --> Process[Process Step]
    Process --> Decision{Decision Point?}
    Decision -->|Yes| Action1[Action 1]
    Decision -->|No| Action2[Action 2]
    Action1 --> End([End])
    Action2 --> End

Sequence Diagrams

MUST use for: API interactions, user flows, service-to-service communication

sequenceDiagram
    participant Client
    participant API
    participant Database

    Client->>API: GET /resource
    API->>Database: SELECT query
    Database-->>API: Result set
    API-->>Client: 200 OK + data

Entity Relationship Diagrams

MUST use for: Data models, database schemas

erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains
    PRODUCT ||--o{ LINE-ITEM : "ordered in"

Naming Conventions

Node IDs

MUST follow these rules:

Pattern	Example	Rule
camelCase	userService	PREFER for service names
snake_case	user_service	Acceptable alternative
Descriptive	authAPI	NEVER use api alone
Match code	PostgreSQL	MUST match actual names

Display Names

• MUST use proper capitalization: "User Service" not "user service"
• SHOULD include technology: "API Gateway (Node.js)"
• MUST keep under 50 characters

Connection Labels

• MUST use verb phrases: "Authenticates via", "Queries", "Publishes to"
• MUST include protocol/method: "HTTPS/REST", "gRPC", "PostgreSQL"
• NEVER use vague labels: "reads" → "Reads user data"

Subgraph Usage

MUST group related components logically:

flowchart TD
    subgraph Frontend
        web[Web App]
        mobile[Mobile App]
    end

    subgraph Backend
        api[API Gateway]
        auth[Auth Service]
    end

    subgraph Data
        db[(Database)]
        cache[(Redis)]
    end

    web --> api
    mobile --> api
    api --> auth
    api --> db
    auth --> cache

Subgraph Rules

Rule	Guidance
Naming	MUST use nouns: "Frontend", "Data Layer"
Count	NEVER exceed 5 subgraphs per diagram
Abstraction	MUST keep same abstraction level

Color and Styling

MUST use sparingly and consistently:

flowchart TD
    A[Normal]
    B[Warning]:::warning
    C[Error]:::error
    D[Success]:::success

    classDef warning fill:#ff9,stroke:#333
    classDef error fill:#f99,stroke:#333
    classDef success fill:#9f9,stroke:#333

Color Rules

• ONLY use color to highlight important states
• NEVER rely on color alone (also use shapes/labels)
• MUST use colorblind-friendly palettes

Azure/Cloud Resources

MUST follow these standards for Azure diagrams:

C4Container
    title Azure Infrastructure

    System_Boundary(vnet, "Virtual Network") {
        Container(app, "App Service", "Web App", "Application tier")
        ContainerDb(db, "PostgreSQL", "Flexible Server", "Data tier")
    }

    Container_Ext(keyvault, "Key Vault", "Azure Key Vault", "Secrets")
    Container_Ext(storage, "Storage Account", "Blob Storage", "Files")

    Rel(app, db, "Connects via", "Private Endpoint")
    Rel(app, keyvault, "Retrieves secrets", "Managed Identity")
    Rel(app, storage, "Stores files", "HTTPS")

Azure Standards

Element	Rule
Service names	MUST use official Azure names
Private endpoints	MUST show where applicable
Managed identities	MUST indicate authentication method
Resource groups	SHOULD show as system boundaries
VNets/subnets	MUST label network boundaries

Diagram Size Guidelines

Size	Nodes	Use Case
Small	5-10	Single system, simple flow
Medium	10-20	Multi-service architecture
Large	20+	AVOID - split into multiple diagrams

Documentation Integration

In Runbooks

MUST place diagrams strategically:

Section	Diagram Type
System Overview	Architecture diagram
Deployment Procedure	Deployment flow
Data Pipeline	Data flow diagram
Troubleshooting	Decision tree

In README Files

• MUST place system architecture near the top
• SHOULD include setup/installation as flowchart
• SHOULD add contributing workflow for open source

In ADRs

• MUST include "Before" and "After" architecture diagrams
• SHOULD show decision tree of options considered
• SHOULD include impact diagram showing affected systems

Testing Diagrams

MUST validate every diagram:

1. Syntax check: Render in Mermaid Live Editor
2. Clarity check: Can someone unfamiliar understand it?
3. Accuracy check: Does it match actual implementation?
4. Completeness check: Are all critical components shown?
5. Maintenance check: Will this be easy to update?

Common Mistakes

❌ Don't	✅ Do
Too much detail in one diagram	Split into multiple focused diagrams
Unlabeled connections	ALWAYS label every arrow
Inconsistent direction (LR/TD mix)	Pick one direction, stick with it
Generic names ("Service 1")	Use actual names ("Auth Service")
Missing context (no title)	MUST add title and description

Example: Well-Styled Diagram

flowchart LR
    subgraph External
        user[User]
        idp[Optum SSO]
    end

    subgraph "Azure East US"
        subgraph "App Service"
            webapp[Web Application<br/>Node.js]
        end

        subgraph "Data Layer"
            postgres[(PostgreSQL<br/>Flexible Server)]
            redis[(Redis Cache)]
        end

        subgraph "Security"
            keyvault[Key Vault]
        end
    end

    user -->|HTTPS| webapp
    webapp -->|Authenticates| idp
    webapp -->|Connection string| keyvault
    webapp -->|Queries| postgres
    webapp -->|Caches sessions| redis

Why this works:

• Clear subgraph hierarchy
• Consistent direction (LR)
• All connections labeled
• Technology stack shown
• Actual service names used
• External dependencies clearly marked

Constraints

• ALWAYS use renderMermaidDiagram tool when available
• ALWAYS validate syntax before presenting
• NEVER include sensitive data in diagram examples
• PREFER standard Mermaid syntax over experimental features
• MUST follow these standards for maintainable documentation