Inspiration
Opening a large codebase for the first time is disorienting. The file tree tells you where things are, but not what matters or how the pieces connect. I wanted to see a repo the way you see a city from a plane: the tall buildings, the busy neighborhoods, the roads between them. Then I wanted to ask it a question and get flown to the answer.
What it does
Paste a GitHub URL and Gitropolis builds the repo as a 3D city. Every source file is a building, and its height comes from lines of code. Folders become districts.
The colors read like a fall foliage report. A file's color depends on how many commits touched it in the last year, in five stages: None, Patchy, Partial, Near peak and Peak. Files nobody touched stay dark green, and the busiest ones turn scarlet. The 5% of files that change most also get pale gold roofs. The stages are distinct colors, not a gradient, so the busy parts of a codebase stand out from across the city.
Click a building to see its connections. Sky-blue arcs go to the files it imports, and violet arcs come from the files that import it. The arcs glow; the buildings don't.
Then hold Space and ask a question out loud, like "How does undo work?" The camera rises, sweeps across the city and lands on the files that answer it, one stop at a time, while a narrator explains what each file does. The rest of the city dims so you can follow the path, and a row of markers in the caption shows which stop you're on.
The demo city is Excalidraw: 541 source files, 154,000 lines and 3,646 import edges. Its tallest tower is App.tsx, at 11,499 lines with 108 commits last year. Its label reads "The god component."
How we built it
The backend is Node and Express on Render. It clones the repo without downloading old file versions (git clone --filter=blob:none), which takes about 4 seconds for Excalidraw, and gets the commit count for every file from a single git log. Regex passes pull out each file's exports and imports. Monorepo imports like @excalidraw/element resolve through the tsconfig paths and the workspace package names. d3-hierarchy lays the folders out as a squarified treemap, and each city ends up as one JSON file.
The frontend is React Three Fiber with drei and a bloom pass, on Vercel. All 541 buildings are a single instanced mesh, set on bark-brown ground under warm, low light. Voice input uses the Web Speech API and narration uses the browser's own speech synthesis, so neither needs an API key.
A question runs two OpenAI calls with structured outputs. The first reads a one-line summary of every file and names 4 to 6 places to start. The server expands those along the import graph and gives the second call only that neighborhood, with every edge labeled by the functions it carries, like useMermaidRenderer -> common [convertMermaidToExcalidraw]. The second call writes a tour of 3 to 5 stops, and each stop names the function it contributes. If that function is defined in a different file, the server adds the defining file to the tour.
I built it with Claude as a coding assistant.
Challenges we ran into
The first version of Ask the City failed every test. I had written an eval with three questions and the files each tour had to visit. It passed 0 of 3 on gpt-4.1-mini. Switching to gpt-4.1 also passed 0 of 3. It just missed different files.
Every file the model missed was one import away from a file it had picked. It only saw a flat list of files, so it had no way to follow those links. Worse, my own import graph was hiding them. A line like import { Store } from "@excalidraw/element" pointed at the package's index.ts, which only re-exports names from other files. Tracing each name to the file that defines it added 807 edges. Giving the model the import graph instead of a flat list fixed two of the three questions.
The third question, "How does text-to-diagram turn a prompt into a drawing?", kept ending at MermaidToExcalidraw.tsx. The conversion lives in common.ts, which three different files call. The model had picked the file whose name matched the question. Once the edges showed which functions each file imports, and each stop had to name its function, it passed. I then added a fourth question, about the riskiest files to change. All four passed in each of three runs: 12 of 12.
Part of that failure was mine. My original test required mermaid.ts, a 52-line config file, because its name sounded right. I had made the same mistake as the model, so I rewrote the tests from the code itself.
Two smaller problems took real time. A few tiny treemap cells came out zero units wide, which made the lighting math return NaN, and the bloom pass spread it across the whole frame until the city went black. And Render's free tier sleeps, so a voter could wait 50 seconds for the first answer. Now the demo answers are saved from a run that passed the same checks as the eval, and they ship with the frontend, so those tours start right away without waking the server.
Accomplishments that we're proud of
The tours follow the code, not the file names. Ask about undo and the camera goes from the undo action to the history module to the store that records each change, which is how undo works in Excalidraw.
I'm proud of the eval too. It turned "the AI picks weird files" into a specific bug I could fix, and it caught a wrong assumption of my own.
And the god component label still makes me laugh.
What we learned
A bigger model wasn't the fix. gpt-4.1 found no more of the required files than gpt-4.1-mini until I gave it the structure of the code. Showing it which file imports which function did more than any change to the prompt wording.
I also learned to write tests from the code, not from file names.
What's next for Gitropolis
- Python and Go import parsing, so it works beyond JS and TS repos
- A time-lapse slider that grows the city commit by commit, so you can watch the foliage change
- Lighting up the first call's picks during the scan, so you can watch it search
- Follow-up questions in the middle of a tour
- Private repos through GitHub sign-in
Built With
- d3.js
- express.js
- node.js
- openai
- react
- react-three-fiber
- render
- three.js
- vercel
- web-speech-api