Inspiration
Understanding an unfamiliar codebase often means jumping between files, tracing imports, and trying to reconstruct the architecture in your head. Documentation can help, but it rarely answers every question. AI explanations can help too, but only if you can check what they claim. We built Codebase Archaeologist to bring the code, its relationships, and its explanations into one place.
What it does
Codebase Archaeologist turns a public Python GitHub repository into an interactive map. Developers can explore dependencies, select files and symbols, inspect source code, and investigate architectural patterns and potential risks. Optional AI explanations describe selected code using cited evidence. The interface distinguishes deterministic facts, heuristic findings, and AI interpretations, so users can see what the analyzer established and what still requires judgment.
How we built it
We built the frontend with React, React Flow, and Vinext, and a Python FastAPI backend running in Docker on an Oracle Cloud VM. The analyzer examines Python’s abstract syntax tree to extract symbols and relationships without executing the repository’s code. Hosted analysis pins each repository to a specific commit, keeping source references tied to the version analyzed. For AI interpretation, we integrated Llama 3.3 70B through Cloudflare Workers AI. The model receives a bounded evidence packet for the selected symbol. We validate its response structure and check that its citations reference supplied evidence.
Challenges we ran into
One challenge was making a dense dependency graph useful. We added filtering, focused symbol selection, and source navigation to help users investigate specific questions. Another was getting AI explanations to stay grounded. During evaluation, we encountered invalid citations, placeholder uncertainty text, and unsupported claims about behavior. These failures pushed us to improve the evidence packets, validation, and presentation of uncertainty.
Accomplishments that we're proud of
Building a working end-to-end product: A public Python GitHub URL becomes an interactive map with source navigation, dependency relationships, and risk findings. Making AI explanations checkable: Users can inspect citations and compare interpretations with the underlying code. Keeping uncertainty visible: We distinguish facts, heuristics, and AI interpretations rather than presenting every finding as equally reliable. Deploying on limited infrastructure: We brought the frontend, isolated analyzer, and model integration together with resource limits and persistent quotas. Learning from failures: We turned issues found during testing into stronger validation, clearer explanations, and a more usable interface.
What we learned
We learned that a valid citation does not automatically make an explanation correct. Structural validation helps, but human review still matters. We also learned to respect the limits of static analysis. Python’s dynamic behavior means some relationships remain unresolved, and a possible execution path does not prove runtime behavior. Making those gaps visible became a central part of the product.
What's next for Codebase Archaeologist
Our current release is a Python-first beta. Next, we want to expand real-repository evaluation, improve framework-aware execution flows, and add durable report snapshots and sharing. Longer term, we plan to support mixed-language repositories while preserving the same evidence-first approach.
Log in or sign up for Devpost to join the conversation.