Mermaid

Mermaid Diagram Creation

Create professional, color-coded mermaid diagrams with consistent styling for architecture documentation.

When to Use

• Creating flowcharts, sequence diagrams, or state diagrams
• Documenting architecture or component relationships
• Visualizing workflows or data flows

Critical Constraints

ALWAYS:

• Use the standard color palette defined below
• Include a color legend table after the diagram
• Use %%{init: {...}}%% for diagram configuration
• Group related nodes in subgraphs
• Apply class styling to all nodes

NEVER:

• Use inline styles (use classDef instead)
• Create diagrams without color coding
• Omit the color legend

Instructions

1. Identify all nodes: List every distinct state, action, or decision point

2. Categorize each node by type:

   • Input/CLI elements
   • State/Data nodes
   • Handlers/Processors
   • Phase/Control nodes
   • New/Proposed components
   • Output/Artifacts
   • Gaps/Warnings (optional)

3. Choose direction: Pick TB for hierarchical flows, LR for sequential/parallel flows

4. Assess grouping: Look for distinct logical phases or stages

   • If phases exist, use subgraphs with descriptive names
   • Keep start/end/error nodes outside subgraphs

5. Draft the diagram using the template below

6. Add color legend table after the diagram

7. Review: Verify all connections and class assignments

Standard Color Palette

Diagram Template

```mermaid
%%{init: {'flowchart': {'nodeSpacing': 50, 'rankSpacing': 60, 'curve': 'basis'}}}%%
graph TB
    %% CLASS DEFINITIONS %%
    classDef cli fill:#1a237e,stroke:#7986cb,stroke-width:2px,color:#fff;
    classDef stateNode fill:#004d40,stroke:#4db6ac,stroke-width:2px,color:#fff;
    classDef handler fill:#e65100,stroke:#ffb74d,stroke-width:2px,color:#fff;
    classDef phase fill:#6a1b9a,stroke:#ba68c8,stroke-width:2px,color:#fff;
    classDef newComponent fill:#2e7d32,stroke:#81c784,stroke-width:2px,color:#fff;
    classDef output fill:#00695c,stroke:#4db6ac,stroke-width:2px,color:#fff;
    classDef detector fill:#b71c1c,stroke:#ef5350,stroke-width:2px,color:#fff;
    classDef gap fill:#ff6f00,stroke:#ffa726,stroke-width:2px,color:#000;
    classDef terminal fill:#1a237e,stroke:#7986cb,stroke-width:2px,color:#fff;

    %% TERMINAL NODES %%
    START([START])
    END([END])

    %% SUBGRAPHS %%
    subgraph GroupName ["Group Title"]
        direction TB
        Node1["Label Line 1<br/>━━━━━━━━━━<br/>Detail line"]
        Node2["Another Node"]
    end

    %% CONNECTIONS %%
    START --> Node1
    Node1 --> Node2
    Node2 --> END

    %% CLASS ASSIGNMENTS %%
    class Node1,Node2 handler;
    class START,END terminal;
```

**Color Legend:**
| Color | Category | Description |
|-------|----------|-------------|
| Dark Blue | Terminal | Start and end points |
| Orange | Handler | Processing components |

Node Shape Reference

A([Label])     # Rounded: Start/End terminals
A{Label}       # Diamond: Decision points
A[Label]       # Rectangle: Standard nodes
A[(Label)]     # Cylinder: Database/storage
A[[Label]]     # Subroutine: Subgraph call
A{{Label}}     # Hexagon: Preparation step

Multiline Labels

Use <br/> for line breaks and ━━━━━━━━━━ as visual separator:

Node["Title<br/>━━━━━━━━━━<br/>Description line 1<br/>Description line 2"]

Status Symbols

Use symbols to indicate component status:

Example:

Node["★ NewHandler<br/>━━━━━━━━━━<br/>Proposed feature"]

Example: Simple Workflow

%%{init: {'flowchart': {'nodeSpacing': 40, 'rankSpacing': 50}}}%%
flowchart LR
    classDef phase fill:#6a1b9a,stroke:#ba68c8,stroke-width:2px,color:#fff;
    classDef handler fill:#e65100,stroke:#ffb74d,stroke-width:2px,color:#fff;
    classDef terminal fill:#1a237e,stroke:#7986cb,stroke-width:2px,color:#fff;

    START([START])

    subgraph Workflow ["T → I → V Workflow"]
        T["TestCreator (T)<br/>━━━━━━━━━━<br/>Create tests first"]
        I["Implementer (I)<br/>━━━━━━━━━━<br/>Implement code"]
        V["Verifier (V)<br/>━━━━━━━━━━<br/>Validate results"]
    end

    END([END])

    START --> T --> I --> V --> END

    class T,I,V handler;
    class START,END terminal;

Color Legend:

Example: Complex Architecture

%%{init: {'flowchart': {'nodeSpacing': 50, 'rankSpacing': 60, 'curve': 'basis'}}}%%
graph TB
    classDef cli fill:#1a237e,stroke:#7986cb,stroke-width:2px,color:#fff;
    classDef stateNode fill:#004d40,stroke:#4db6ac,stroke-width:2px,color:#fff;
    classDef handler fill:#e65100,stroke:#ffb74d,stroke-width:2px,color:#fff;
    classDef phase fill:#6a1b9a,stroke:#ba68c8,stroke-width:2px,color:#fff;
    classDef output fill:#00695c,stroke:#4db6ac,stroke-width:2px,color:#fff;

    subgraph CLI_Layer ["CLI Entry Layer"]
        TaskOpt["--task / -t<br/>━━━━━━━━━━<br/>Task description"]
        PathOpt["--project-path<br/>━━━━━━━━━━<br/>Project location"]
    end

    subgraph State_Layer ["State Management"]
        State["GraphState<br/>━━━━━━━━━━<br/>Mutable context<br/>Phase tracking"]
    end

    subgraph Processing ["Processing Pipeline"]
        Init["init_node<br/>━━━━━━━━━━<br/>Initialize state"]
        Handler["MainHandler<br/>━━━━━━━━━━<br/>Process request"]
        Complete["complete_node<br/>━━━━━━━━━━<br/>Finalize output"]
    end

    subgraph Output ["Output Artifacts"]
        Result["result.json<br/>━━━━━━━━━━<br/>Final output"]
    end

    TaskOpt --> State
    PathOpt --> State
    State --> Init
    Init --> Handler
    Handler --> Complete
    Complete --> Result

    class TaskOpt,PathOpt cli;
    class State stateNode;
    class Init,Complete phase;
    class Handler handler;
    class Result output;

Color Legend: