Dies Primus

Stop reading codebases. Walk through them. Any GitHub repo becomes an explorable 3D city with an AI guide who knows every street.

Comment

Inspiration

Every developer knows the pain of opening an unfamiliar GitHub repository and being greeted by hundreds or thousands of files. A file tree tells you what exists, but not what matters, how the pieces connect, or where you should start.

We wanted to change the way developers understand unfamiliar codebases.

Our idea was simple: what if a codebase could be explored like a city?

That became Repo City - a 3D, explorable representation of a GitHub repository where the AI acts as your guide.

What it does

Repo City turns any GitHub repository into a living 3D city.

  • Folders become districts
  • Files become buildings
  • Lines of code determine building height
  • Programming languages determine colour
  • The role of a file influences its visual form
  • Code relationships form the underlying architecture
  • An AI guide explains the project and answers questions

Users can walk through the generated city, inspect individual files, understand how components connect, and ask the AI questions about the actual codebase.

Instead of searching through a flat file tree, developers can visually explore the architecture and ask:

"What does this component do?"

"Where is this functionality implemented?"

"What happens when a request is sent?"

The AI answers using repository evidence and cites real source paths.

How we built it

We built a pipeline that combines static code analysis, knowledge graphs, vector search, and LLMs.

First, the repository is fetched and analyzed. Source code is parsed into structured representations, including files, classes, functions, imports, calls, and relationships.

We then build a NetworkX knowledge graph representing the architecture of the repository.

For semantic understanding, we use an LLM to analyze important parts of the codebase. The resulting knowledge is converted into embeddings and stored in ChromaDB for semantic retrieval.

When a user asks a question, the system combines:

Vector retrieval + Knowledge Graph context + Code semantics → LLM → Grounded answer

This hybrid approach allows deterministic code relationships to provide the facts while the LLM focuses on explaining them naturally.

The final repository structure is transformed into a procedural 3D city and rendered interactively in the browser.

Challenges we ran into

Understanding large repositories

Real repositories can contain thousands or even tens of thousands of files. Sending an entire repository to an LLM would be inefficient and noisy.

We solved this by triaging the repository and prioritizing meaningful architectural components instead of blindly processing everything.

Keeping the AI grounded

We didn't want the AI to invent relationships between files.

Our solution was to make the knowledge graph the authority for structural relationships. The graph determines dependencies and connections, while the LLM explains those verified relationships.

Turning code into a city

A codebase has no natural physical representation, so we had to design a visual language for software architecture.

We mapped properties such as file size, language, and role into physical characteristics of buildings.

Rendering the city efficiently

A large repository can generate hundreds of buildings. We therefore used instanced rendering and procedural generation to keep the experience interactive in the browser.

Accomplishments that we're proud of

We are proud that Repo City is not just a visualization mockup it works end-to-end on real GitHub repositories.

A single repository can be analyzed, transformed into a structured knowledge graph, semantically understood by AI, indexed for retrieval, and represented as an explorable 3D city.

We also built an AI pipeline that can answer questions using actual repository context while testing against hallucinations and keeping repository data isolated.

Most importantly, we created a completely different way to approach a problem developers have traditionally solved by scrolling through files.

What we learned

We learned that the best way to use AI for code understanding is not to make the LLM responsible for everything.

Static analysis is better at determining what actually exists and how components are connected. Vector search is useful for finding semantically relevant information. Knowledge graphs are useful for relationships. LLMs are best used to turn all of that information into explanations humans can understand.

This led us to a hybrid approach:

Code analysis provides the facts.
The graph provides the relationships.
Vector search finds relevant context.
AI provides the explanation.

We also learned a lot about procedural 3D generation, browser rendering performance, and designing an interface that makes complex technical information intuitive.

What's next for Dies Primus

Repo City is currently focused on making unfamiliar codebases easier to understand through visual exploration and an AI guide.

Next, we want to expand the experience with deeper developer workflows: an editor extension, pull requests represented as construction work in the city, and team dashboards that show how a codebase evolves over time.

Our long-term vision is to make software architecture something developers can explore, understand, and navigate visually rather than something they have to reconstruct from thousands of lines of code.

Built With

Share this project:

Updates

Submission history