mermaid-diagram-generator

$27

1. Flowcharts (Default)

Best for: workflow sequences, decision trees, process flows, module relationships

flowchart TD

    A[Start] --> B{Decision}

    B -->|Yes| C[Action A]

    B -->|No| D[Action B]

    C --> E[End]

    D --> E

2. Sequence Diagrams

Best for: agent interactions, API calls, multi-step processes, request/response patterns

sequenceDiagram

    participant User

    participant API

    participant Service

    User->>API: Request

    API->>Service: Process

    Service-->>API: Response

    API-->>User: Result

3. Class Diagrams

Best for: module structure, inheritance hierarchies, data models, component relationships

classDiagram

    class Brick {

        +String responsibility

        +PublicContract studs

    }

    class Module {

        +init()

        +process()

    }

    Brick <|-- Module

4. State Diagrams

Best for: workflow states, state machines, workflow phases, condition-based transitions

stateDiagram-v2

    [*] --> Planning

    Planning --> Design

    Design --> Implementation

    Implementation --> Testing

    Testing --> [*]

5. Entity Relationship Diagrams

Best for: data models, database schemas, entity relationships

erDiagram

    MODULE ||--o{ FUNCTION : exports

    MODULE ||--o{ DEPENDENCY : requires

    FUNCTION }o--|| CONTRACT : implements

6. Gantt Charts

Best for: project timelines, workflow phases, milestone planning

gantt

    title Project Timeline

    section Phase 1

    Planning :p1, 0, 30d

    Design :p2, after p1, 20d

    section Phase 2

    Implementation :p3, after p2, 40d

    Testing :p4, after p3, 25d

Step-by-Step Generation Process

Step 1: Understand the Source Material

• Read the architecture description, spec, or workflow document

• Identify the main entities or nodes

• Determine how they relate or flow

• Choose the appropriate diagram type

Step 2: Identify Diagram Type

Source Material

Best Diagram Type

Workflow steps, process flow

Flowchart

Module relationships, brick connections

Flowchart or Class Diagram

Agent interactions, call sequences

Sequence Diagram

States and transitions

State Diagram

Data models, entities

Class Diagram or ERD

Database schema

ERD

Project timeline

Gantt Chart

Complex hierarchies

Class Diagram

Step 3: Extract Entities and Relationships

• List all nodes/entities from the source

• Identify connections between them

• Determine connection types (data flow, inheritance, calling, etc.)

• Note any decision points or conditions

Step 4: Generate Mermaid Syntax

• Use appropriate Mermaid diagram declaration

• Create nodes with descriptive labels

• Draw connections with proper syntax

• Add styling if needed for clarity

• Ensure valid Mermaid syntax

Step 5: Validate and Enhance

• Ensure all entities are included

• Verify connections are accurate

• Add styling for important elements

• Make diagram readable and not cluttered

• Test syntax for validity

Step 6: Document and Embed

• Add title and description

• Include explanation of diagram

• Provide legend if needed

• Embed in markdown with proper formatting

Usage Examples

Example 1: Architecture Description to Flowchart

Input:

The authentication module handles JWT token validation. When a request arrives,

it first checks if a token exists. If not, it returns unauthorized. If it does,

it validates the token signature. If valid, it extracts the payload and continues.

If invalid, it returns forbidden. The payload is passed to the authorization

module for role-based access control.

Output:

flowchart TD

    A[Request Arrives] --> B{Token Exists?}

    B -->|No| C[Return Unauthorized]

    B -->|Yes| D{Token Valid?}

    D -->|No| E[Return Forbidden]

    D -->|Yes| F[Extract Payload]

    F --> G[Check Role-Based Access]

    G --> H{Authorized?}

    H -->|No| I[Return Access Denied]

    H -->|Yes| J[Allow Request]

    C --> K[End]

    E --> K

    I --> K

    J --> K

Example 2: Module Spec to Class Diagram

Input:

Module: authentication

- Exports: validate_token, TokenPayload, AuthError

- Classes: TokenPayload (user_id, role, expires_at), AuthError (message, code)

- Functions: validate_token(token, secret) -> TokenPayload

- Internal: JWT (PyJWT library), Models (TokenPayload)

Output:

classDiagram

    class AuthenticationModule {

        +validate_token(token, secret)

        +TokenPayload

        +AuthError

    }

    class TokenPayload {

        +String user_id

        +String role

        +DateTime expires_at

        +to_dict()

    }

    class AuthError {

        +String message

        +Integer code

        +__str__()

    }

    AuthenticationModule -- TokenPayload

    AuthenticationModule -- AuthError

Example 3: Workflow to State Diagram

Input:

DDD Workflow: Phase 0 (Planning) -> Phase 1 (Documentation) ->

Approval Gate -> Phase 2 (Code Planning) -> Phase 3 (Implementation) ->

Phase 4 (Testing & Cleanup) -> Complete

Output:

stateDiagram-v2

    [*] --> Planning

    Planning --> Documentation

    Documentation --> ApprovalGate

    ApprovalGate --> CodePlanning

    CodePlanning --> Implementation

    Implementation --> Testing

    Testing --> [*]

Example 4: Agent Interaction to Sequence Diagram

Input:

The prompt-writer agent clarifies requirements from the user. It then sends

the clarified requirements to the architect agent. The architect creates a

specification and sends it to the builder agent. The builder implements code

and sends it to the reviewer. The reviewer checks quality and sends feedback

back to the builder if issues are found, or to the user if complete.

Output:

sequenceDiagram

    actor User

    participant PromptWriter

    participant Architect

    participant Builder

    participant Reviewer

    User->>PromptWriter: Request Feature

    PromptWriter->>Architect: Clarified Requirements

    Architect->>Builder: Specification

    Builder->>Reviewer: Implementation

    Reviewer-->>Builder: Issues Found

    Builder->>Reviewer: Fixed Implementation

    Reviewer-->>User: Complete & Approved

Example 5: System Architecture to Flowchart

Input:

Client requests flow through API Gateway to Services. Services can be

Authentication Service, User Service, or Data Service. All services

connect to a shared Database and Logger. Services return responses

through the API Gateway back to Client.

Output:

flowchart LR

    Client[Client]

    Gateway[API Gateway]

    Auth[Auth Service]

    User[User Service]

    Data[Data Service]

    DB[(Database)]

    Logger[Logger]

    Client <--> Gateway

    Gateway --> Auth

    Gateway --> User

    Gateway --> Data

    Auth --> DB

    User --> DB

    Data --> DB

    Auth --> Logger

    User --> Logger

    Data --> Logger

Mermaid Syntax Reference

Flowchart Nodes

A[Rectangle]

B(Rounded Rectangle)

C{Diamond/Decision}

D[(Database)]

E[/Parallelogram Right/]

F[\Parallelogram Left\]

G[[Subroutine]]

H((Circle))

Flowchart Connections

A --> B          # Arrow

A -- Text --> B  # Arrow with label

A ---|Yes| B     # Arrow with yes/no

A -->|Condition| B

A -.-> B         # Dotted line

A ==> B          # Bold arrow

Styling

classDef className fill:#f9f,stroke:#333,stroke-width:2px,color:#000

class A,B className

style A fill:#f9f,stroke:#333,stroke-width:4px

Quality Checklist

Before presenting a diagram, verify:

• All entities from source are included

• Connections accurately represent relationships

• Diagram type matches content (flowchart for flows, sequence for interactions, etc.)

• Labels are clear and descriptive

• No circular logic or dead ends (unless intentional)

• Mermaid syntax is valid

• Diagram is readable and not overly complex

• Decision points have clear yes/no paths

• Legend provided if needed for understanding

• Comments explain non-obvious elements

Common Patterns

Brick Module Visualization

flowchart TD

    B1["Brick Module 1<br/>(Responsibility)"]

    B2["Brick Module 2<br/>(Responsibility)"]

    S1["Stud: public_function"]

    S2["Stud: public_class"]

    B1 --> S1

    B1 --> S2

    S1 -.depends on.-> B2

    B2 --> "Stud: get_data"

Workflow Decision Tree

flowchart TD

    Start[Start] --> Q1{Condition 1?}

    Q1 -->|No| End1[End: Rejected]

    Q1 -->|Yes| Q2{Condition 2?}

    Q2 -->|No| End2[End: Review]

    Q2 -->|Yes| Q3{Condition 3?}

    Q3 -->|No| End3[End: Partial]

    Q3 -->|Yes| End4[End: Approved]

Error Handling Flow

flowchart TD

    A[Execute] --> B{Error?}

    B -->|No| C[Success]

    B -->|Yes| D{Recoverable?}

    D -->|No| E[Fail]

    D -->|Yes| F[Retry]

    F --> A

    C --> G[End]

    E --> G

Integration with Documentation

Embedding in Markdown

## System Architecture

flowchart TD

...

Key Components:

• Component A handles...

• Component B processes...

### Using with Document-Driven Development

- Create diagrams during documentation phase

- Include architecture diagrams in spec docs

- Use sequence diagrams to explain workflows

- Add state diagrams to describe state machines

### Using with Investigation Workflow

- Visualize discovered architecture

- Show data flow between components

- Map discovered dependencies

- Display call sequences between services

## Tips for Effective Diagrams

1. **Keep It Simple**: One concept per diagram

2. **Use Clear Labels**: Names should describe purpose

3. **Follow Visual Conventions**: Diamonds for decisions, circles for states

4. **Avoid Crossing Lines**: Reorganize to reduce visual clutter

5. **Logical Flow**: Top-to-bottom or left-to-right

6. **Consistent Styling**: Similar elements should look similar

7. **Legend**: Include if symbols aren't obvious

8. **Test Syntax**: Ensure Mermaid renders without errors

9. **Add Comments**: Explain non-obvious relationships

10. **Iterate**: Refine based on feedback

## Common Pitfalls to Avoid

- **Too Complex**: Diagram has too many elements (break into multiple diagrams)

- **Unclear Labels**: Node names don't describe their purpose

- **Missing Connections**: Important relationships not shown

- **Invalid Syntax**: Mermaid errors prevent rendering

- **Ambiguous Decision Points**: Yes/no paths not clearly marked

- **Crossing Arrows**: Visual confusion from overlapping connections

- **No Legend**: Symbols or colors not explained

- **Wrong Diagram Type**: Using flowchart for sequence data

- **Inconsistent Style**: Different formatting for similar elements

- **No Context**: Diagram shown without explanation

## Success Criteria

A good Mermaid diagram:

- [ ] Shows all key entities from source material

- [ ] Accurately represents relationships and flow

- [ ] Uses appropriate diagram type for content

- [ ] Clear, descriptive labels on all nodes

- [ ] Valid Mermaid syntax (renders without error)

- [ ] Readable without excessive complexity

- [ ] Supports understanding of the system

- [ ] Could be embedded in documentation

- [ ] Decision points clearly marked

- [ ] Legend included if needed

- [ ] Purpose and scope clear from context

## Related Skills

- **module-spec-generator**: Generate specs that can be visualized as class diagrams

- **Document-Driven Development**: Use diagrams in specification documents

- **Investigation Workflow**: Create architecture diagrams from discovered systems

## Output Format

Diagrams are generated in Mermaid markdown format, ready to embed:

mermaid

[Generated Mermaid Syntax]