CodeMap

Inspiration

Every developer knows the pain of joining a new team and staring at a codebase with hundreds of files, no clear entry point, and a README that was last updated two years ago. You end up spending days — sometimes weeks — just figuring out what connects to what. Senior engineers get pulled away from their own work to give walkthroughs. We thought: what if AI could do that walkthrough for you? What if you could just paste a GitHub link and instantly get a map of the entire architecture with a guided tour, like having a senior dev sit next to you and explain everything?

What it does

CodeMap takes a GitHub repository URL and produces two things: an interactive dependency graph where every file is a color-coded node you can click to explore, and an AI-generated guided tour that walks you through the codebase step by step — starting at the entry point and following the main data flow, just like a senior engineer would.

The tool clones the repo, parses every file's imports and exports using AST analysis, classifies files into architectural layers (routers, services, models, utils, etc.), sends the code to Claude AI for summarization, and renders the result as a visual, explorable diagram in the browser.

How I built it

The backend is FastAPI running a 4-stage pipeline:

Clone & Walk — GitPython clones the repo into a temp directory, then we walk the file tree filtering out noise like node_modules, lock files, and binaries.
Static Analysis — Python's ast module parses Python files for imports/exports. JS/TS files use regex-based parsing. Each file gets classified into an architectural layer based on its path.
AI Summarization — File contents are batched and sent to the Claude API, which generates per-file summaries, a full architecture overview, and an ordered guided tour with narration.
Graph Layout — NetworkX builds a directed dependency graph and computes node positions using topological ordering (for DAGs) or spring layout.

The frontend is React with React Flow for the interactive graph, Tailwind CSS for styling, and Vite as the dev server (with a proxy to the backend). The tour system has play/pause/next/prev controls that highlight nodes and show narration in a side panel.

The two servers connect through Vite's dev proxy — the frontend proxies /api/* requests to the FastAPI backend, so everything runs on a single origin with no CORS issues.

Challenges I ran into

Uvicorn kept restarting mid-analysis. When we cloned repos into a folder inside the project, some repos had .py files buried in their node_modules. Uvicorn's --reload file watcher picked those up, restarted the server, and wiped our in-memory task store — causing infinite 404 loops on the frontend. The fix was cloning into /tmp instead of the project directory.

Python virtual environment issues. Even after creating a venv and installing packages, the system Python was still being used because uvicorn on the PATH pointed to the global install. We had to use python3 -m uvicorn to force execution through the venv, and eventually built a run.sh script that handles activation automatically.

SDK version mismatch. Pinning anthropic==0.39.0 caused a crash because the older SDK passed a deprecated proxies argument to a newer version of httpx. Loosening the pin to >=0.42.0 resolved it — a good lesson in not over-pinning dependencies.

Accomplishments that I'm proud of

The tool actually works end-to-end: paste a URL, wait a minute, and you get a genuinely useful interactive map of a real codebase.
The guided tour feature is something we haven't seen in other tools — it doesn't just show you the graph, it walks you through it with AI-generated narration like a senior dev would.
The pipeline architecture is clean: each stage is independent, progress is reported in real-time, and the frontend shows exactly what the backend is doing at each step.
Built a single ./run.sh command that handles venv activation, dependency installation, and starting both servers — making the project easy to run for anyone.

What I learned

AST parsing — using Python's ast module to extract imports/exports programmatically, which is far more reliable than regex for structured languages.
React Flow — building custom interactive node graphs with click handlers, dynamic styling, and mini-maps.
Background task patterns — running long operations in a ThreadPoolExecutor with polling-based progress updates, and the tradeoffs vs WebSockets.
The importance of isolating side effects — the uvicorn restart bug taught us that cloning external code into your project directory can have unexpected consequences.
Prompt engineering for structured output — getting Claude to return consistent JSON arrays for batch file summarization required careful system prompts and response parsing.

What's next for CodeMap

Search and filter — filter nodes by layer, language, or search by filename to navigate large repos faster.
Directory grouping — collapse directories into clustered super-nodes so repos with hundreds of files don't overwhelm the graph.
Persistent storage — save analysis results to a database so you don't re-analyze the same repo every time.
Private repo support — add GitHub token authentication to analyze private repositories.
Multi-language AST parsing — integrate tree-sitter for proper AST analysis of Go, Rust, Java, and other languages beyond Python and JS/TS.

Built With

fastapi
python