Mermaid Diagram Generation

What Is Mermaid?

Mermaid is a text-based diagram language. Simple syntax, real diagrams -- flowcharts, sequence diagrams, class diagrams, you name it. Paired with AI, you can visualize code architecture fast.

Common Diagram Types

1. Entity Relationship Diagrams

Great for database design and data models:

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains
    PRODUCT ||--o{ LINE-ITEM : includes
    CUSTOMER {
        string name
        string email
    }
    ORDER {
        int orderNumber
        date created
    }

2. Flow Charts

Great for process and logic flows:

flowchart TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Process]
    B -->|No| D[End]
    C --> E{Another Decision}
    E -->|Option 1| F[Action 1]
    E -->|Option 2| G[Action 2]
    F --> D
    G --> D

3. Sequence Diagrams

Great for interaction flows:

sequenceDiagram
    participant Client
    participant Server
    participant Database

    Client->>Server: HTTP Request
    Server->>Database: Query
    Database-->>Server: Result
    Server-->>Client: JSON Response

4. Class Diagrams

Great for object-oriented design:

classDiagram
    class Animal {
        +name: string
        +age: int
        +makeSound()
    }
    class Dog {
        +breed: string
        +bark()
    }
    class Cat {
        +color: string
        +meow()
    }
    Animal <|-- Dog
    Animal <|-- Cat

Process for Generating Diagrams

1. Analyze source files (SQL, code, docs)
2. Extract entities and relationships
3. Generate appropriate diagram type
4. Include relevant properties/methods
5. Validate syntax with mermaid compiler
6. Save to specified location

Validation

npx -p @mermaid-js/mermaid-cli mmdc -i <input>.md -o test.md

Best Practices

• Keep diagrams focused and readable
• Use consistent naming conventions
• Group related entities
• Add labels to relationships
• Include cardinality where relevant
• Use subgraphs for organization
• Add styling for clarity

Having AI Generate Diagrams

In Cursor or Claude Code, you can prompt like this:

Analyze all model files under src/models/
and generate a Mermaid ER diagram showing entity relationships.

AI will:

1. Read model files
2. Analyze fields and relationships
3. Generate Mermaid syntax
4. Output renderable diagram code

Using Diagrams in Docs

Most Markdown renderers (GitHub, GitLab, Notion, etc.) support Mermaid. Just specify mermaid as the code block language:

```mermaid
flowchart LR
    A --> B --> C
```

Advanced Styling

flowchart TD
    subgraph Frontend
        A[React App]
        B[State Management]
    end

    subgraph Backend
        C[API Server]
        D[Database]
    end

    A --> C
    B --> A
    C --> D

    style A fill:#f9f,stroke:#333
    style C fill:#bbf,stroke:#333

Next Steps

Check out Task Implementation Methodology for systematic planning and execution.