Mermaid Diagramming

Create professional software diagrams using Mermaid's text-based syntax. Mermaid renders diagrams from simple text definitions, making diagrams version-controllable, easy to update, and maintainable alongside code.

Core Syntax Structure

All Mermaid diagrams follow this pattern:

diagramType
  definition content

Key principles:

• First line declares diagram type (e.g., classDiagram, sequenceDiagram, flowchart)
• Use %% for comments
• Line breaks and indentation improve readability but aren't required
• Unknown words break diagrams; parameters fail silently

Diagram Type Selection Guide

Choose the right diagram type:

1. Class Diagrams - Domain modeling, OOP design, entity relationships

   • Domain-driven design documentation
   • Object-oriented class structures
   • Entity relationships and dependencies

2. Sequence Diagrams - Temporal interactions, message flows

   • API request/response flows
   • User authentication flows
   • System component interactions
   • Method call sequences

3. Flowcharts - Processes, algorithms, decision trees

   • User journeys and workflows
   • Business processes
   • Algorithm logic
   • Deployment pipelines

4. Entity Relationship Diagrams (ERD) - Database schemas

   • Table relationships
   • Data modeling
   • Schema design

5. C4 Diagrams - Software architecture at multiple levels

   • System Context (systems and users)
   • Container (applications, databases, services)
   • Component (internal structure)
   • Code (class/interface level)

6. State Diagrams - State machines, lifecycle states

7. Git Graphs - Version control branching strategies

8. Gantt Charts - Project timelines, scheduling

9. Pie/Bar Charts - Data visualization

For detailed guidelines and examples, see reference.md.