Mermaid Diagram Guide for Technical Documentation

Status: Complete
Purpose: Standardize technical diagram creation using Mermaid format across all documentation
Application: NudgeCampaign and general software architecture documentation

Overview

This guide establishes standards for creating technical diagrams using Mermaid, a text-based diagramming tool that integrates seamlessly with markdown documentation. Mermaid diagrams are version-control friendly, render natively in GitHub, and maintain consistency across all technical documentation.

Why Mermaid?

Benefits

• Version Control: Text-based format tracks changes in Git
• Native Rendering: GitHub, GitLab, and most markdown viewers render Mermaid automatically
• No Special Tools: Edit diagrams directly in any text editor
• Consistency: Unified styling across all documentation
• Accessibility: Screen reader compatible as text-based format
• Maintainability: Easy updates without proprietary software
• Export Options: Convert to SVG, PNG, or PDF as needed

When to Use Mermaid

• Architecture diagrams (C4 model)
• API sequence flows
• Process flowcharts
• Database schemas (ERD)
• State machines
• User journey maps
• System integration diagrams
• Deployment pipelines

Quick Start

Basic Syntax

      
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Process]
    B -->|No| D[End]
    

Renders as:

Diagram Types for NudgeCampaign

1. C4 Model Architecture Diagrams

System Context (Level 1)

Container Diagram (Level 2)

Component Diagram (Level 3)

2. Sequence Diagrams for API Flows

Email Campaign Send Flow

Authentication Flow with RLS

3. Flow Charts for Process Documentation

Contact Import Process

Maya AI Conversation Flow

4. Entity Relationship Diagrams

Core Database Schema

5. State Diagrams for Workflows

Campaign Lifecycle

Subscription States

6. User Journey Diagrams

New User Onboarding Journey

7. Deployment Pipeline Diagram

8. Integration Architecture

NudgeCampaign Specific Examples

Multi-Tenant Architecture with RLS

Email Campaign Flow with Maya AI

Styling Guidelines

Color Palette

Node Types and Styling

Best Practices

1. Consistency Rules

• Direction: Use TB (top-bottom) for hierarchical, LR (left-right) for process flows
• Naming: Use descriptive labels, avoid abbreviations
• Colors: Follow the established color palette
• Spacing: Maintain visual balance with subgraphs
• Arrows: Use solid for primary flow, dashed for optional/conditional

2. Documentation Integration

## Architecture Overview

The following diagram shows the high-level system architecture:


      
graph TB
    A[Component A] --> B[Component B]
    

**Key Points:**
- Component A handles user requests
- Component B processes data

3. Accessibility Considerations

• Always provide text description before/after diagrams
• Use high contrast colors
• Include alternative text representations for complex diagrams
• Ensure logical flow direction (top-to-bottom or left-to-right)

4. Version Control

• Keep diagrams close to related documentation
• Use meaningful commit messages when updating diagrams
• Consider diagram versioning for major architectural changes

5. Performance

• Limit diagram complexity (max 20-30 nodes per diagram)
• Split large diagrams into multiple focused diagrams
• Use subgraphs to organize related components

Export and Rendering Options

GitHub Rendering

• Mermaid diagrams render automatically in GitHub markdown files
• No additional configuration required
• Preview in PR reviews shows rendered diagrams

Export to Image Formats

# Using Mermaid CLI
npm install -g @mermaid-js/mermaid-cli
mmdc -i diagram.mmd -o diagram.svg
mmdc -i diagram.mmd -o diagram.png -t dark

# Using online editor
# Visit: https://mermaid.live
# Paste diagram code and export as SVG/PNG

PDF Generation

• Include diagrams in markdown documentation
• Use pandoc or similar tools to convert to PDF with rendered diagrams

Integration with Documentation Tools

• Docusaurus: Native Mermaid support with plugin
• MkDocs: Material theme includes Mermaid support
• Gatsby: Various Mermaid plugins available
• VuePress: Built-in Mermaid support

Common Patterns for NudgeCampaign

API Endpoint Documentation

Error Handling Flow

Troubleshooting

Common Issues and Solutions

1. Diagram Not Rendering

   • Check for syntax errors (missing quotes, brackets)
   • Ensure proper markdown fence (```)
   • Verify 'mermaid' identifier after opening fence

2. Layout Problems

   • Adjust graph direction (TB, LR, RL, BT)
   • Use subgraphs to group related nodes
   • Add invisible nodes for spacing

3. Text Overflow

   • Use <br/> for line breaks in nodes
   • Shorten labels and add details in documentation
   • Consider splitting into multiple diagrams

4. Color Not Applying

   • Check style syntax: style NodeID fill:#color,color:#textcolor
   • Ensure node ID matches exactly
   • Use quotes for IDs with special characters

Resources

Official Documentation

• Mermaid Official Docs
• Mermaid Live Editor
• GitHub Mermaid Support

Tools and Extensions

• VS Code: Mermaid Preview extension
• IntelliJ: Mermaid plugin
• Chrome: GitHub + Mermaid extension
• CLI: @mermaid-js/mermaid-cli

Examples Repository

• Store complex diagram examples in /docs/private/diagrams/
• Maintain a library of reusable diagram patterns
• Document any custom styling or themes

Conclusion

Mermaid provides a powerful, maintainable solution for technical documentation diagrams. By following these standards, NudgeCampaign documentation maintains consistency, accessibility, and version control compatibility across all technical diagrams.

Remember: The goal is clear communication. If a diagram becomes too complex, split it into multiple focused diagrams with accompanying documentation.