The Problem

Every developer has probably experienced this at some point.

You clone an unfamiliar repository, open it in your editor, and suddenly find yourself navigating through dozens or even hundreds of files.

You start asking questions:

• Where does this functionality actually live?
• Which files depend on this module?
• How does information flow between different components?
• Where should I even begin?

Understanding an unfamiliar codebase can take considerably longer than expected.

I wanted to make that process easier.

Introducing Codebase X-Ray

Codebase X-Ray is an interactive codebase visualization tool that transforms Python repositories into visual architecture graphs.

Instead of manually navigating through directories and tracing imports, developers can explore the structure of a repository through an interactive interface.

The idea: Turn codebase exploration into visual exploration.

How I Built It

I approached the project by separating repository analysis from visualization.

1. Static Analysis with Python AST

The backend uses Python's Abstract Syntax Tree (AST) capabilities to inspect source files without executing them.

This allows the scanner to extract structural information and identify import statements.

2. Dependency Extraction

The scanner identifies relationships between Python modules wherever imports can be resolved.

These relationships are converted into nodes and edges that represent the repository's architecture.

3. Backend with FastAPI

FastAPI handles repository scanning requests and communicates structured analysis results to the frontend.

It supports public GitHub repository scanning, local repository scanning, and ZIP archive uploads subject to validation limits.

4. Interactive Visualization

The frontend uses React and React Flow to render the architecture graph.

Dagre calculates the initial graph layout, making it easier to visualize relationships between files.

What Can You Do With It?

Some of the features currently available include:

• Visualize Python repository structures.
• Explore detected import dependencies.
• Inspect incoming and outgoing imports.
• Group files by directory.
• Drag and reposition nodes and folder groups.
• Search for files by name or path.
• Switch between dark and light themes.
• Explore the graph in fullscreen mode.
• View repository analysis statistics.

The Technology Stack

Technology	Purpose
React	Frontend
Vite	Build tooling
React Flow	Graph visualization
Dagre	Graph layout
FastAPI	Backend API
Python AST	Static analysis
Uvicorn	Application server

Challenges Along the Way

The most interesting part wasn't simply rendering nodes and connecting edges.

Some of the challenges I encountered included:

• Resolving imports across repository structures.
• Converting static analysis results into meaningful graph relationships.
• Managing folder groups and their contained nodes.
• Handling large repository archives and implementing upload restrictions.
• Configuring frontend/backend communication during deployment.
• Debugging CORS and production environment configuration.

Building and deploying the project taught me that getting something working locally is only one part of developing a real application.

What's Next?

Codebase X-Ray is an evolving project.

Some directions I'd like to explore include:

• Function-level dependency tracing.
• Change-impact analysis.
• Better module resolution.
• Support for additional programming languages.
• Guided challenges for learning unfamiliar repositories.
• Better scalability for larger codebases.

The long-term goal is to make understanding an unfamiliar codebase significantly more intuitive.

Try It Yourself

The project is publicly available.

Live Demo: https://codebase-xray-1.onrender.com

GitHub: https://github.com/sreevatsarajesh

If you're a developer, contribute to open-source projects, or regularly work with unfamiliar repositories, I'd love to hear your thoughts.

What would you want to see in a tool like this?

Feedback, suggestions, and contributions are welcome.

---

Built by Sreevatsa Rajesh

Building, experimenting, and learning in public.