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.

Phase 2: Map

Build a mental model of:

1. Architecture pattern — monolith, microservices, serverless, MVC, hexagonal, event-driven, etc.
2. Entry points — where execution starts (server boot, CLI entry, main function, route registration)
3. Request/data flows — trace 2-3 primary flows end-to-end (e.g., "user signs up", "API processes a request", "CLI parses and executes a command")
4. Layer boundaries — routes → controllers → services → repositories → database, or equivalent
5. Key decisions — architectural choices that aren't obvious (why this ORM, why this folder structure, why this pattern)

Phase 3: Generate

Create ./visual-explainer/index.html with this structure:

┌─────────────────────────────────────────────────┐
│  Header: Project Name + Stack Badges            │
├────────────┬────────────────────────────────────┤
│            │                                    │
│  Sidebar   │   Main Content Area               │
│  Navigation│                                    │
│            │   (switches based on active tab)   │
│  - Overview│                                    │
│  - Arch    │                                    │
│  - Files   │                                    │
│  - Flows   │                                    │
│  - Details │                                    │
│            │                                    │
├────────────┴────────────────────────────────────┤
│  Footer: Generated by visual-explainer          │
└─────────────────────────────────────────────────┘

Tab 1: Overview

• Project name, description (from README or package.json)
• Stack badges (language, framework, database, infra)
• Quick stats: file count, line count, dependency count
• One-paragraph summary of what the project does and how

Tab 2: Architecture

• Mermaid.js diagram showing the high-level architecture
• Labeled boxes for each major layer/component
• Arrows showing data flow direction
• Brief text explanation below the diagram

Tab 3: File Structure

• Interactive collapsible file tree
• Each folder has a one-line description of its purpose
• Each core file has: purpose, key exports, and why it exists
• Color coding: Core (blue), Config (gray), Infra (orange), Test (green)
• Skip files are hidden by default with a toggle to show them

Tab 4: Flows

• 2-3 Mermaid.js sequence diagrams showing primary workflows
• Each flow traces a real path through the code (e.g., "HTTP request → route → controller → service → DB → response")
• Annotated with file names so the reader can follow along in the code

Tab 5: Deep Dive

• Expandable cards for each core file
• Each card shows:
  • File path
  • Purpose (one sentence)
  • Key functions/methods with their purpose and reasoning
  • Dependencies (what it imports)
  • Dependents (what imports it)

HTML Implementation Rules

1. Single file. Everything in one index.html — HTML, CSS, JS.
2. CDN dependencies only:
   • <script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
   • <script src="https://cdn.tailwindcss.com"></script>
   • <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
3. Dark theme. Background #0a0a0a, cards #141414, borders #262626, text #e5e5e5, muted #a3a3a3, accent #3b82f6.
4. Responsive. Sidebar collapses on mobile.
5. Mermaid config. Use dark theme: mermaid.initialize({ theme: 'dark', startOnLoad: true }).
6. No frameworks. Vanilla JS for tab switching, collapsibles, and tree toggling.
7. Smooth transitions. CSS transitions on tab switches and collapsible sections.
8. Print-friendly. Include a @media print that expands all sections and removes the sidebar.

Quality Checklist

Before writing the file, verify:

• Every core file has been read and understood
• Architecture pattern is identified and diagrammed
• At least 2 real workflows are traced end-to-end
• File tree annotations explain why, not just what
• Mermaid diagrams render correctly (valid syntax)
• No placeholder text like "TODO" or "description here"
• The dashboard tells a coherent story — a new developer could read it top to bottom and understand the project

Common Mistakes

Mistake	Fix
Listing files without explaining purpose	Every file annotation must answer "why does this exist?"
Generic descriptions ("handles logic")	Be specific: "Validates JWT tokens and attaches user to request context"
Skipping the flow diagrams	Flows are the most valuable part — trace real paths through the code
Including every single file	Skip noise: lockfiles, generated code, config that needs no explanation
Broken Mermaid syntax	Test diagram syntax mentally — watch for unescaped special characters, missing semicolons
Forgetting to create the output directory	Always mkdir -p ./visual-explainer before writing

Example Invocations

User: "Explain this codebase visually"
→ Run full analysis → generate ./visual-explainer/index.html

User: "Create a visual overview of this project"
→ Same as above

User: "I need to onboard someone to this repo"
→ Run full analysis → generate ./visual-explainer/index.html