athola/data-flow

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