| name | c4-diagram |
| description | Generate interactive C4 architecture diagrams from any codebase. Use when user says "c4 diagram", "architecture diagram", "codebase diagram", "visualize architecture", or wants to map a project's structure. Accepts a local repo path or git URL. |
| argument-hint | ["path-or-git-url"] |
| allowed-tools | Bash(deno:*), Bash(git clone:*), Bash(ls:*), Bash(firefox:*), Read, Glob, Grep |
C4 Architecture Diagram Generator
Generate an interactive, multi-level C4 architecture diagram from a codebase and open it in the browser.
References
Before starting, read these files:
${CLAUDE_SKILL_DIR}/references/diagram-data-schema.md - JSON schema for diagram data${CLAUDE_SKILL_DIR}/references/mermaid-c4-patterns.md - Mermaid rendering patterns
Workflow
Step 1: Resolve target
If $ARGUMENTS is a git URL (starts with http or git@):
git clone --depth 1 "$ARGUMENTS" /tmp/c4-diagram-repo
Otherwise, use the path directly. Set REPO_PATH to the absolute path.
If no argument given, use the current working directory.
Step 2: Explore the codebase
Scan the repo to understand its architecture. Read key files:
Config files (read whichever exist):
package.json, pnpm-workspace.yaml, lerna.json - Node.js monoreponuxt.config.ts / next.config.js / vite.config.ts - Frontend frameworkCargo.toml - Rustgo.mod - Gopyproject.toml / requirements.txt - Pythondocker-compose.yml - Multi-serviceCLAUDE.md, README.md - Project docs
Directory structure:
- Use
Glob to map top-level and key subdirectories
- Identify: pages/routes, components, services, API endpoints, middleware, data layer
Dependencies:
- External services (look for SDK imports, API URLs, env vars)
- Databases, caches, queues, CDNs
- Third-party integrations
Step 3: Design C4 levels
Build a mental model, then create the DiagramData JSON:
Level 1 - Context: Who uses this system? What external systems does it interact with?
- Nodes: actors (person), the system itself (system), external services (external)
- Edges: high-level interactions
Level 2 - Container: What are the deployable/runnable units?
- Group the system's containers in a boundary subgraph
- Nodes: frontend app, API server, workers, databases (as container or external)
- Include tech stack in descriptions
Level 3 - Component: What are the major modules inside the main container?
- Group by architectural layer (UI, data, business logic)
- Nodes: pages, components, services, composables, middleware
- Show data flow between components
Level 4 - Code (optional, 1-3 interesting subsystems):
- Detailed views of specific areas (routing, forms, data flow, etc.)
- Fine-grained nodes with specific file references
Guidelines for good diagrams
- Node IDs: alphanumeric + hyphens, max 20 chars, unique within a level
- Descriptions: max ~30 chars per line, 2-3 lines max
- Keep levels focused: 5-12 nodes per level is ideal
- Set clickTargets on nodes that have drill-down levels
- Hints: mention clickable nodes using
<span class="hl">Node Name</span>
- Source files: add
sourceFiles arrays pointing to key files (relative to repo root)
- Emojis: use sparingly for person (👤), system (🌐), groups (🏠, 🖼️, 📦)
- Groups: use
direction LR inside subgraphs when you want horizontal layout
Stack-specific tips
Nuxt/Next.js: L2 = SSR app + static assets + external APIs. L3 = pages, components, composables/hooks, server routes. L4 = routing tree, data fetching, forms.
Django/Rails: L2 = web app + DB + cache + workers. L3 = apps/models, views/controllers, serializers, middleware. L4 = model relationships, URL routing.
Go/Rust microservices: L2 = each service as a container + shared infra. L3 = handlers, middleware, repositories, domain. L4 = request lifecycle.
Monorepo: L2 = each package as a container. L3 = internals of the main package. L4 = cross-package dependencies.
Step 4: Write the JSON
Write the complete DiagramData JSON to /tmp/c4-diagram-data.json.
Set repoUrl to the GitHub/remote URL if available (check git remote). Source file links will point to GitHub when set.
Validate that:
initialLevel points to an existing level key- All
clickTargets values point to existing level keys
- All
Edge.from and Edge.to reference existing node IDs in that level
- All
Group.nodeIds reference existing node IDs in that level
Step 5: Render
deno run --allow-read --allow-write ${CLAUDE_SKILL_DIR}/scripts/render.ts /tmp/c4-diagram-data.json /tmp/c4-diagram.html
Step 6: Open
firefox /tmp/c4-diagram.html &
Tell the user the diagram is open. Mention:
- Click highlighted nodes to drill down
- Use breadcrumb to navigate back
- Right-click nodes with 📄 to see source file links (opens on GitHub if repoUrl is set)
