visual-explainer

Visual Explainer

Generate an interactive HTML dashboard that visually explains a codebase — its architecture, file structure, data flows, and the purpose behind every meaningful file and function.

When to Use

• User asks to explain, visualize, or document a codebase
• User wants to understand how a project works
• User needs onboarding documentation for a repo
• User asks for architecture diagrams or code maps

When NOT to Use

• Single-file explanations (just explain inline)
• Non-code projects (pure docs, assets)
• The user only wants a README

Output

A self-contained ./visual-explainer/index.html file in the project root. No external dependencies except CDN links (Mermaid.js, Tailwind CSS, Inter font).

Process

Phase 1: Analyze

1. Detect the project root. Use the current working directory.
2. Read the file tree. Run find . -type f excluding: node_modules, .git, dist, build, .next, __pycache__, .venv, target, vendor, .cache, coverage dirs, and lockfiles.
3. Detect the stack. Identify languages, frameworks, and tools from config files (package.json, pom.xml, Cargo.toml, pyproject.toml, go.mod, docker-compose.yml, etc.).
4. Classify files. Sort every file into one of these categories:
   • Core — main application logic, entry points, route handlers, services, controllers, models, schemas
   • Config — environment, build, lint, CI/CD configs
   • Infrastructure — Docker, deployment, IaC
   • Test — test files, fixtures, mocks
   • Skip — lockfiles, generated code, binary assets, .gitignore, LICENSE, package-lock.json, etc.
5. Read all Core files. Understand:
   • What each file does (purpose, not line-by-line)
   • Key exports, classes, functions, and why they exist
   • How files depend on each other (imports/requires)
   • The data flow: entry point → processing → output/response
6. Read Config and Infrastructure files. Summarize what they configure and why.
7. Skim Test files. Note what they cover, don't explain each test.