# Flow Diagram Trace data flow through a codebase and produce an interactive HTML diagram. Trigger: `/flow-diagram` ## Usage ``` /flow-diagram src/api/handler.ts /flow-diagram "what happens when a user submits a form" /flow-diagram src/routes/index.ts -> service -> database ``` The argument is either: - A file path (entry point to trace from) - A natural language description of the flow to diagram - A path with `->` arrows describing the flow to trace ## Process ### 1. Investigate Read the actual source code. Do NOT guess or hallucinate connections. Every node and edge in the diagram must come from real imports, function calls, API routes, database queries, or event dispatches found in the code. Trace strategy: - Start from the entry point file/function - Follow imports and function calls - Track data shape transformations (what goes in, what comes out) - Note async boundaries (API calls, database queries, queue jobs, webhooks) - Stop at external service boundaries -- show them as terminal nodes For each step, record: - File path and line number of the key call - Function/method name - Data shape entering and leaving (brief: e.g., "txHash: string" -> "TraceResult") - Whether it's sync, async, or a separate job/request - A short description of what the function does (1-2 sentences) ### 2. Build the node metadata For every node in the diagram, prepare a JSON metadata object with: - `id`: unique node ID used in Mermaid - `label`: display name (function or file name) - `file`: relative file path - `line`: line number - `layer`: one of "api", "service", "database", "async" - `description`: what this step does (1-2 sentences) - `dataIn`: data shape entering (e.g., "{ txHash: string, chainId: number }") - `dataOut`: data shape leaving (e.g., "TraceResult | null") - `code`: the key line(s) of code showing the call (2-5 lines max) This metadata powers the interactive detail panel. ### 3. Build the Mermaid diagram Use `flowchart TD` (top-down) for linear flows, `flowchart LR` (left-right) for branching. Node naming rules: - Use the actual function or file name as the node label - Color-code by layer using classDef: - API endpoints: blue (#4a9eff) - Services/business logic: green (#4ade80) - Database/external: orange (#fbbf24) - Queue/async boundaries: purple (#c084fc) Edge labels show what data moves between nodes (keep brief). Use subgraphs for logical groupings when the flow crosses boundaries. ### 4. Output Write a single self-contained HTML file to `~/.agent/diagrams/flow-.html`. The HTML file must include: **Diagram area (left/top):** - Mermaid diagram with zoom controls (+/-, scroll-to-zoom, reset) - Nodes are clickable -- clicking a node opens the detail panel for that node **Detail panel (right side or bottom):** - Shows when a node is clicked - Displays: node name, file:line, description, data in/out shapes, code snippet - Has a close button - Slides in smoothly - Highlights the selected node in the diagram **Legend** below the diagram mapping colors to layers. Use this template (fill in the placeholders): ```html Flow: {name}

{title}

{description}

{mermaid_content}
API
Service
External
Async

Click a node to inspect

``` ### 5. Report After opening the file, print a brief summary in chat: - The flow path in one line (A -> B -> C -> D) - File path of the diagram - Any notable findings (circular deps, dead code paths, missing error handling) ## Rules - NEVER fabricate connections. Every edge must be traceable to an import, function call, or API route in the code. - Keep diagrams focused. If a flow touches 20+ files, group related files into subgraph clusters. - Use subgraphs for logical boundaries (e.g., "API Layer", "Service Layer", "Database"). - Show data shape at key transformation points as edge labels. - External services (databases, third-party APIs, message queues) are always terminal leaf nodes colored orange. - When the entry point is ambiguous, ask the user to clarify rather than guessing. - Node IDs in Mermaid must match the keys in NODE_DATA exactly so click handlers work. - The `code` field in NODE_DATA should show the most relevant 2-5 lines from that step (the actual function call or key logic), not the entire file. - Always use `securityLevel: 'loose'` in Mermaid config so click handlers work.