codemap-diagram

name

codemap-diagram

description

This skill should be used when the user asks to "draw a diagram", "visualize architecture", "show me the database schema", "create an ERD", "sequence diagram", "flow diagram", "dependency graph", "architecture diagram", "C4 diagram", or needs any visual representation of code structure, data flow, or system architecture. All diagrams are generated as native mxGraph XML and rendered via drawio-mcp. Also triggers when a code explanation would benefit from a visual aid.

Diagram Generation via drawio-mcp

Step 0: Execution Mode (MANDATORY)

Before doing ANY work, ask the user:

"Want me to delegate this to the diagrammer agent (specialized diagram generation), or proceed inline in this chat?"

• If user chooses agent → launch the diagrammer agent with the diagram type, scope, and context. STOP here — do not continue with the steps below.
• If user chooses inline → proceed with the methodology below.
• If user doesn't respond clearly → default to agent.

---

CRITICAL RULES:

• ALL diagrams MUST be native mxGraph XML saved as .drawio files. Never generate Mermaid (.mmd), PlantUML, or text-based diagrams — this is a hard requirement, not a preference.
• If drawio-mcp is unavailable, report the error. Do NOT fall back to any other format.

Generate all diagrams as native mxGraph XML. Save as .drawio files and render via drawio-mcp create_diagram tool.

Available drawio-mcp tools: create_diagram (render XML), search_shape (find shapes).

Diagram Type Selection

Use this decision tree to choose the right diagram type:

Question	Diagram Type
Overview of the entire system?	C4 Container — boxes for each service/component, arrows for communication
How a user action flows through the system?	Flowchart — steps, decisions, outcomes
How an API request moves between components?	Sequence — lifelines with arrows showing call order
What tables exist and how they relate?	ERD — tables with columns, FK relationships
Which modules depend on which?	Dependency Graph — directed graph of imports/calls
How components within one service connect?	C4 Component — internal structure of one container

See ${CLAUDE_PLUGIN_ROOT}/skills/codemap-diagram/references/diagram-types.md for detailed guidance on each type.

Generation Process

For every diagram, follow these steps:

Step 1: Analyze the Code

• Read relevant source files (models, routes, configs, imports)
• Identify the entities/components to include
• Determine relationships/connections between them
• Decide what to include and what to omit (keep diagrams focused)

Step 2: Generate mxGraph XML

• Use templates from ${CLAUDE_PLUGIN_ROOT}/skills/codemap-diagram/references/mxgraph-templates.md
• Apply color coding from ${CLAUDE_PLUGIN_ROOT}/skills/codemap-diagram/references/color-legend.md
• Follow naming rules: use actual names from code, not generic labels
• Keep diagrams readable: max 15 nodes per diagram, split if more

Step 3: Save as .drawio File

• Save to docs/codemap/diagrams/{type}-{scope}.drawio
• Create docs/codemap/diagrams/ directory if it doesn't exist
• File naming: architecture.drawio, erd.drawio, flow-login.drawio, sequence-create-deal.drawio, deps-routes.drawio

Step 4: Render via drawio-mcp

• Call the create_diagram MCP tool with the generated XML
• Present the interactive URL to the user
• If drawio-mcp is unavailable, report the error — do NOT fall back to Mermaid or text diagrams

Step 5: Report to User

• Show the file path where .drawio was saved
• Show the interactive preview URL from drawio-mcp
• Brief description of what the diagram shows

mxGraph XML Rules

• Always wrap in <mxGraphModel> root element
• Use <root> with cell id="0" (root) and cell id="1" (default parent)
• Node cells: vertex="1" with <mxGeometry> for position/size
• Edge cells: edge="1" with source and target attributes
• NO XML comments (<!-- -->) — drawio-mcp forbids them
• Use style attribute for colors, shapes, fonts
• Position nodes with adequate spacing (min 40px gap between nodes)

Color Legend

Apply consistent colors across all diagrams:

Layer	Fill Color	Hex	When to use
Data	Light Blue	#dae8fc	Models, database tables, migrations, ORM
Logic	Light Green	#d5e8d4	Routes, services, business logic, controllers
Interface	Light Yellow	#fff2cc	Templates, static files, API endpoints, forms
External	Light Red	#f8cecc	Third-party APIs, MCP servers, external services
Auth	Light Purple	#e1d5e7	Authentication, authorization, security components
Infra	Light Gray	#f5f5f5	Docker, config files, CI/CD, environment

Diagram Quality Rules

• Use real names from code — not "Service A" but "deals_bp" or "User model"
• Show direction — arrows indicate data flow or dependency direction
• Include cardinality on ERD — 1:N, N:M relationships marked
• Label edges — "imports", "calls", "FK: user_id", "HTTP POST"
• Keep it focused — one diagram per concept, don't mix architecture with DB schema
• Add a title — every diagram has a text label at top describing what it shows

Error Handling

• drawio-mcp unavailable → inform the user, suggest retry. Do NOT fall back to Mermaid.
• File path doesn't exist → ask the user to verify the path
• Too many entities (>15 nodes) → split into multiple diagrams, explain the split
• ORM not detected → ask the user to specify the ORM type or point to model files