c4-diagram

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 monorepo
• nuxt.config.ts / next.config.js / vite.config.ts - Frontend framework
• Cargo.toml - Rust
• go.mod - Go
• pyproject.toml / requirements.txt - Python
• docker-compose.yml - Multi-service
• CLAUDE.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)