Navinator

The Problem

Software onboarding is confusing. Modern codebases are becoming increasingly complex, with thousands of interconnected files, functions, and dependencies. For developers joining unfamiliar projects, understanding how everything works can mean spending days manually tracing function calls, searching through files, and piecing together outdated documentation. Existing AI coding assistants can explain individual snippets, but often lack a deeper understanding of how the entire codebase connects. Developers need more than answers they need a way to navigate and understand the bigger picture.

Our Solution

We built Navinator, an AI-powered codebase navigator that transforms complex software projects into interactive 3D maps. Developers can explore how files, functions, and dependencies connect, then ask questions in plain English, such as "How does login work?" and receive a guided, step-by-step tour through the actual code execution path.

Navinator turns unfamiliar repositories into navigable environments. Instead of manually searching through hundreds of files or relying on disconnected AI explanations, developers can visually explore their software architecture, follow real function relationships, and inspect the exact source code behind every step. Each generated tour is validated against actual dependency graph connections, keeping AI explanations grounded in the underlying code.

How We Built It

We combined React, TypeScript, and Vite for the frontend with Python and FastAPI for the backend. We used Python's Abstract Syntax Tree (AST) to parse repositories and extract function calls, imports, and dependencies, constructing a structural graph of the codebase. We leveraged NetworkX to represent and traverse these relationships, alongside BM25 search for relevant code retrieval.

For the AI agent, we integrated Anthropic's Claude using its tool-use capabilities, allowing it to search the codebase, inspect source functions, trace execution paths, and generate guided tours. We implemented path validation to ensure every step in a generated tour corresponds to a real connection in the dependency graph.

On the frontend, we built an interactive 3D force-directed graph for visualizing code relationships, alongside a question panel, source-code inspector powered by Monaco Editor, and guided tour playback. We also implemented repository uploads, allowing developers to explore their own codebases.

Challenges We Faced

One of our biggest challenges was engineering a reliable, production-grade dependency graph. We needed to ensure that every connection between files and functions represented a genuine relationship within the codebase, rather than an AI-generated assumption or random guess. This meant building a robust parsing and dependency-resolution pipeline that could accurately map real function calls, trace execution paths, and validate relationships across the repository. Our biggest priority was making sure that every connection and every step in a guided tour was grounded in the actual source code, not hallucinated by an LLM.

What We Learned

We learned how to combine static code analysis, graph-based retrieval, and agentic AI into a unified developer experience. Building Navinator challenged us to think beyond traditional AI chat interfaces and explore how AI can interact with structured information to produce more reliable and useful experiences.

We also gained a deeper understanding of the importance of grounding AI-generated outputs in verifiable data. Rather than treating AI as a standalone answer generator, we designed an agent that actively explores, traces, and validates relationships within a real codebase.

What's Next

We envision Navinator becoming a comprehensive navigation and onboarding platform for complex software projects. We plan to expand support for additional programming languages, introduce local LLM integrations for privacy-sensitive repositories, and develop deeper architectural visualizations, including 2D dependency diagrams.

We also want to explore how repositories evolve over time, allowing developers to replay changes, understand architectural decisions, and identify the impact of modifications across an entire project.

Ultimately, our goal is to make understanding unfamiliar software as intuitive as navigating a map.

Built With

• React
• TypeScript
• Vite
• Python
• FastAPI
• NetworkX
• Anthropic Claude API
• Python AST
• BM25
• Monaco Editor
• Three.js / 3D force graph visualization

Built With

• ast-parsing
• fastapi
• graph-algorithms
• networkx
• openai-api
• python
• react
• tailwind-css
• three.js
• typescript