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.

1. 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

1. Read Config and Infrastructure files. Summarize what they configure and why.
2. 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:

• ``
• ``
• ``

1. Dark theme. Background #0a0a0a, cards #141414, borders #262626, text #e5e5e5, muted #a3a3a3, accent #3b82f6.
2. Responsive. Sidebar collapses on mobile.
3. Mermaid config. Use dark theme: mermaid.initialize({ theme: 'dark', startOnLoad: true }).
4. No frameworks. Vanilla JS for tab switching, collapsibles, and tree toggling.
5. Smooth transitions. CSS transitions on tab switches and collapsible sections.
6. 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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jircik
• Source: jircik/Visual-Explainer
• License: MIT

Install and usage instructions live in the source repository linked above.