/data-flow

name: data-flow
description: Generates a Mermaid sequence diagram showing how data moves between components. Use when tracing request flows or documenting data transformation pipelines.

Data Flow Diagram

Generate a Mermaid sequence diagram showing how data moves between components in a codebase.

When To Use

• Tracing how a request flows through the system
• Understanding data transformation pipelines
• Documenting API call chains
• Answering "what happens when X is called?"

When NOT To Use

• Static call structure (use `cartograph:call-chain`)
• Process steps and state transitions (use `cartograph:workflow-diagram`)

Workflow

Step 1: Explore the Codebase

Dispatch the codebase explorer agent:

Agent(cartograph:codebase-explorer)
Prompt: Explore [scope] and return a structural model.
Focus on function calls, data transformations, and
inter-module communication for a data flow diagram.

Step 2: Generate Mermaid Syntax

Transform the structural model into a Mermaid sequence diagram.

**Rules for data flow diagrams**:

• Use `sequenceDiagram` for request/response flows
• Participants are modules or components (not functions)
• Arrows show data direction: `->>` for calls,

`-->>` for returns

• Use `activate`/`deactivate` for long-running operations
• Add `Note over` for data transformations
• Limit to 8-10 participants maximum
• Use `alt`/`else` for conditional flows
• Handle circular calls by showing them once with a note

**Example output**:

sequenceDiagram
    participant User
    participant Command as /commit
    participant Sanctum as sanctum.commit
    participant Leyline as leyline.git_platform
    participant Git

    User->>Command: /commit
    Command->>Sanctum: generate_message()
    Sanctum->>Leyline: get_staged_changes()
    Leyline->>Git: git diff --cached
    Git-->>Leyline: diff output
    Leyline-->>Sanctum: structured changes
    Note over Sanctum: Classify change type
    Sanctum-->>Command: commit message
    Command->>Git: git commit -m "..."

Step 3: Render via MCP

Call the Mermaid Chart MCP to render:

mcp__claude_ai_Mermaid_Chart__validate_and_render_mermaid_diagram
  prompt: "Data flow diagram of [scope/feature]"
  mermaidCode: [generated syntax]
  diagramType: "sequenceDiagram"
  clientName: "claude-code"

If rendering fails, fix syntax and retry (max 2 retries).

Step 4: Present Results

Show the rendered diagram with a brief description of the flow depicted (2-3 sentences).

Exit Criteria

• [ ] Mermaid `sequenceDiagram` syntax generated with participants

and at least one `->>` call arrow

• [ ] `mcp__claude_ai_Mermaid_Chart__validate_and_render_mermaid_diagram`

called with `diagramType: "sequenceDiagram"` and returns without error (or retry attempted on first failure)

• [ ] Participant count is at most 10; if more components exist,

they are aggregated and the aggregation noted

• [ ] A 2-3 sentence description of the depicted flow is shown

alongside the rendered diagram

• [ ] Return arrows (`-->>`) are present for any request that has

a corresponding response in the traced flow