Codebase Visualizer

A 3D solar system explorer for any GitHub repository. Drill from cluster galaxies down to file systems, then into individual functions.

Quick Start

npm install

Add your keys to .env.local:

GITHUB_TOKEN=your_github_personal_access_token
GEMINI_API_KEY=your_gemini_api_key

npm run dev

Open http://localhost:3000.

How It Works

Level 1 — Galaxy View

Large glowing orbs represent codebase clusters (Auth, API, UI, DB, etc.). Sized by file count. Click to drill in.

Level 2 — Solar System View

Files orbit around a cluster core. Connected by import lines. Sized by importance. Click to drill in.

Level 3 — Planet Surface View

Functions, classes, and constants inside a single file. Different shapes for different types. Connected by call relationships.

Architecture

app/page.tsx                    → Orchestrator (level state, lazy loading)
app/api/analyze-repo/           → Level 1: repo → clusters
app/api/analyze-cluster/        → Level 2: cluster → files + links (lazy, cached)
app/api/analyze-file/           → Level 3: file → functions + calls (lazy, cached)

src/components/
  Graph3D.tsx                   → Level switcher (ssr:false)
  ClusterGraph.tsx              → Level 1 renderer
  FileGraph.tsx                 → Level 2 renderer
  FunctionGraph.tsx             → Level 3 renderer
  NodePanel.tsx                 → Adaptive side panel
  Breadcrumb.tsx                → Navigation trail
  LoadingScreen.tsx             → Animated loading
  UrlInput.tsx                  → Landing input

src/lib/
  github.ts                     → GitHub API (tree, contents, single file)
  parser.ts                     → Import + function extraction
  llm.ts                        → 3 lazy Gemini calls
  cache.ts                      → In-memory response cache
  constants.ts                  → Colors, sizes, limits

Environment Variables

Variable	Source	Required
GITHUB_TOKEN	GitHub Settings	Yes
GEMINI_API_KEY	Google AI Studio	Yes (falls back to heuristic clustering)