Codebase X-Ray

Interactive architecture maps for unfamiliar codebases. Point it at a GitHub repo and get a live dependency graph, git-churn vs. complexity hotspots, blast radius per file, and a generated reading path — built for the first hour of onboarding into a codebase you have never seen.

Status — all phases complete

• Phase 1 — Core parsing engine (tree-sitter dependency graph, git churn, cyclomatic complexity), verified against wild-roads, enterprise-rag-platform, and dream-architect.
• Phase 2 — GitHub ingestion (window-aware shallow clone) + D3 graph with pan/zoom/drag.
• Phase 3 — World-class visual pass: custom design system (ink/mist/signal palette, Inter + JetBrains Mono), hero graph (size = blast radius, color = complexity heat), settle-in animation, hover highlight propagation, detail panel, designed loading/empty states.
• Phase 4 — Hotspot/risk layer: churn x complexity score, animated Structure/Risk mode switch, ranked risk panel.
• Phase 5 — Blast radius ripple on node click + rule-based suggested reading path with step-through panel.
• Phase 6 — Optional local Ollama file summaries (gated, on-demand).

Run it

Backend (FastAPI, port 8090):

cd backend
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
.venv/bin/uvicorn app.main:app --port 8090

Frontend (Vite, port 5173, proxies /api to 8090):

cd frontend
npm install
npm run dev

Then open http://localhost:5173 and paste a GitHub URL.

Layout

• backend/ — FastAPI + tree-sitter + radon + git analysis (endpoints /api/analyze and /api/summarize).
• frontend/ — React + TypeScript + Tailwind v4 + D3 (custom design system in src/index.css and src/lib/).
• scripts/ — headless-browser verification scripts (puppeteer-core).

Notes

• Core analysis is fully offline; the only optional network calls are the git clone and the opt-in local Ollama summary (requires an Ollama server with llama3.2:3b).
• Node color encodes complexity (Structure view) or churn x complexity (Risk view); node size encodes dependents (blast radius) or risk severity.
• Backend regression tests: cd backend && .venv/bin/python -m unittest tests.test_analysis