Mermaid Diagrams

Creating Mermaid Diagrams

Basic Syntax

Wrap Mermaid code in fenced code blocks with mermaid language identifier:

```mermaid
<diagram-type>
  <diagram-content>
```

Flowchart Example

```mermaid
flowchart TD
    Start([Start]) --> Input[Get User Input]
    Input --> Validate{Valid?}
    Validate -->|Yes| Process[Process Data]
    Validate -->|No| Error[Show Error]
    Process --> Save[(Save to DB)]
    Save --> End([End])
    Error --> Input
```

Sequence Diagram Example

```mermaid
sequenceDiagram
    participant User
    participant API
    participant Database

    User->>API: POST /create
    API->>Database: INSERT query
    Database-->>API: Success
    API-->>User: 201 Created
```

Class Diagram Example

```mermaid
classDiagram
    class Module {
        +String name
        +String version
        +deploy()
        +validate()
    }
    class Resource {
        +String id
        +Map tags
    }
    Module --> Resource : creates
```

State Diagram Example

```mermaid
stateDiagram-v2
    [*] --> Pending
    Pending --> Running : start
    Running --> Completed : success
    Running --> Failed : error
    Failed --> Pending : retry
    Completed --> [*]
```

Entity Relationship Diagram Example

```mermaid
erDiagram
    MODULE ||--o{ RESOURCE : creates
    MODULE {
        string name
        string version
        string provider
    }
    RESOURCE {
        string id
        string type
        map tags
    }
```

Gantt Chart Example

```mermaid
gantt
    title Implementation Timeline
    dateFormat YYYY-MM-DD
    section Phase 1
    Design           :2026-01-01, 7d
    Implementation   :2026-01-08, 14d
    section Phase 2
    Testing          :2026-01-22, 7d
    Deployment       :2026-01-29, 3d
```

Best Practices

1. Choose the Right Diagram Type

2. Keep Diagrams Simple

• Limit nodes: 10-15 nodes per diagram (split complex flows)
• Use clear labels: Short, descriptive text
• Avoid clutter: One main concept per diagram
• Use subgraphs: Group related elements

3. Use Consistent Styling

```mermaid
flowchart LR
    style Start fill:#90EE90
    style End fill:#FFB6C1
    style Error fill:#FFA07A

    Start --> Process
    Process --> End
    Process --> Error
```

4. Add Descriptive Context

Always add explanatory text before and/or after diagrams:

## Deployment Workflow

The following diagram shows the complete deployment process from code commit to production:

```mermaid
flowchart TD
    Commit --> CI
    CI --> Test
    Test --> Deploy
```

After deployment, the system automatically runs health checks and monitoring.

Common Patterns

Agent Handoff Workflow

```mermaid
flowchart LR
    Plan[Implementation Plan] --> Shaper[Scenario Shaper]
    Shaper --> Tester[Terraform Tester]
    Tester --> Module[Module Specialist]
    Module --> Docs[Documentation]
    Docs --> Examples[Examples]

    Module -.feedback.-> Tester
    Module -.feedback.-> Shaper
    Docs -.feedback.-> Module
    Examples -.feedback.-> Module
```

TDD Workflow

```mermaid
stateDiagram-v2
    [*] --> WriteScenario
    WriteScenario --> WriteTest
    WriteTest --> RunTest
    RunTest --> TestFails
    TestFails --> Implement
    Implement --> RunTest
    RunTest --> TestPasses
    TestPasses --> Refactor
    Refactor --> [*]
```

Module Architecture

```mermaid
graph TB
    subgraph "Module Root"
        Main[main.tf]
        Vars[variables.tf]
        Outputs[outputs.tf]
    end

    subgraph "Examples"
        Basic[examples/basic/]
        Complete[examples/complete/]
    end

    subgraph "Tests"
        Unit[tests/unit.tftest.hcl]
        Integration[tests/integration.tftest.hcl]
    end

    Main --> Examples
    Tests -.validates.-> Main
```

Troubleshooting

Advanced Features

Clickable Nodes

```mermaid
flowchart LR
    A[Documentation] --> B[Examples]
    click A "https://github.com/repo/docs" "View Docs"
    click B "https://github.com/repo/examples" "View Examples"
```

Styling and Themes

```mermaid
%%{init: {'theme':'forest'}}%%
flowchart TD
    A --> B
```

Available themes: default, forest, dark, neutral, base

Subgraphs for Organization

```mermaid
flowchart TB
    subgraph "Frontend"
        UI[User Interface]
        API[API Client]
    end

    subgraph "Backend"
        Server[API Server]
        DB[(Database)]
    end

    UI --> API
    API --> Server
    Server --> DB
```

References

• Mermaid Syntax Reference: https://mermaid.js.org/intro/syntax-reference.html
• GitHub Diagrams Documentation: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams
• Mermaid Live Editor: https://mermaid.live/ (for testing/validation)
• Flowchart Syntax: https://mermaid.js.org/syntax/flowchart.html
• Sequence Diagram Syntax: https://mermaid.js.org/syntax/sequenceDiagram.html
• Class Diagram Syntax: https://mermaid.js.org/syntax/classDiagram.html
• State Diagram Syntax: https://mermaid.js.org/syntax/stateDiagram.html
• ER Diagram Syntax: https://mermaid.js.org/syntax/entityRelationshipDiagram.html
• Gantt Chart Syntax: https://mermaid.js.org/syntax/gantt.html

Quick Start Checklist

• Identify what needs visualization
• Choose appropriate diagram type
• Draft diagram structure (nodes, connections, flow)
• Add Mermaid code block to Markdown file
• Validate syntax at mermaid.live
• Add explanatory text around diagram
• Test rendering on GitHub/VS Code
• Refine styling and layout if needed