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.
Generate an interactive, multi-level C4 architecture diagram from a codebase and open it in the browser.
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 patternsIf $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.
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 docsDirectory structure:
Glob to map top-level and key subdirectoriesDependencies:
Build a mental model, then create the DiagramData JSON:
Level 1 - Context: Who uses this system? What external systems does it interact with?
Level 2 - Container: What are the deployable/runnable units?
Level 3 - Component: What are the major modules inside the main container?
Level 4 - Code (optional, 1-3 interesting subsystems):
<span class="hl">Node Name</span>sourceFiles arrays pointing to key files (relative to repo root)direction LR inside subgraphs when you want horizontal layoutNuxt/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.
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 keyclickTargets values point to existing level keysEdge.from and Edge.to reference existing node IDs in that levelGroup.nodeIds reference existing node IDs in that leveldeno run --allow-read --allow-write ${CLAUDE_SKILL_DIR}/scripts/render.ts /tmp/c4-diagram-data.json /tmp/c4-diagram.html
firefox /tmp/c4-diagram.html &
Tell the user the diagram is open. Mention: