Codebase X-Ray：Python 程式碼庫及其相依關係的互動式視覺化工具

I Built Codebase X-Ray: Visualizing Python Codebases and Their Dependencies

Have you ever opened an unfamiliar Python repository and spent more time figuring out how its files connect than actually understanding the code?

That was the problem I wanted to tackle with Codebase X-Ray.

It's a developer tool I'm building to analyze Python repositories and turn their structure and dependencies into an interactive visual graph.

Why I Built It

When working with a multi-file project, understanding the relationships between modules, functions, classes, and imports can be difficult. Jumping between files isn't always the best way to understand the overall architecture.

I wanted a tool that could provide a visual starting point for exploring an unfamiliar codebase.

How It Works

Codebase X-Ray combines static code analysis with an interactive frontend.

1. Python AST Analysis

The backend uses Python's built-in ast module to inspect source files without executing them.

It extracts information such as functions, classes, and imports, which forms the basis of the repository's structural representation.

2. Dependency Extraction

The scanner identifies import relationships between files and builds dependency information that can be visualized.

Dynamic imports and some external dependencies can be difficult to resolve statically, so the results aren't intended to represent every possible runtime relationship.

3. Interactive Graph Visualization

The frontend uses React and React Flow to display relationships between code elements. Dagre helps arrange the graph layout.

Instead of navigating every file individually, developers can explore the structure visually.

4. Technology Stack

• Python for AST-based analysis
• FastAPI for the backend API
• React and Vite for the frontend
• React Flow for graph visualization
• Dagre for graph layout

Codebase X-Ray in Action

1. Repository Scanning and System Metrics

The first step is scanning a repository. Codebase X-Ray accepts a GitHub repository URL or a local directory path and analyzes the Python source files.

Once scanning completes, the dashboard displays key metrics, including the number of Python files discovered, import relationships extracted, symbols identified, and parsing errors encountered.

In this example, the scanner processed 23 Python files, identified 15 import relationships, extracted 48 symbols, and reported zero parsing errors.

2. Interactive Dependency Graph

After scanning, the extracted information is presented as an interactive dependency graph. Each node represents a code element or file in the visualization, while the connecting edges represent import relationships.

Files are organized into color-coded project groups, making it easier to distinguish different parts of a repository and understand how they connect.

The graph supports navigation and zooming, allowing developers to explore the structure of a codebase visually instead of relying entirely on manual file-by-file inspection.

3. Inspecting Individual Files

The graph provides an overview of the repository, but sometimes you need to focus on a particular file.

Selecting a file opens the file inspector, which displays its path, project group, and available dependency information. In this example, the inspector shows app.py and its outgoing import to utils.py.

This makes it easier to investigate how a file depends on other modules and navigate the codebase with more context.

What's Next?

I'm continuing to improve Codebase X-Ray, particularly its ability to make larger codebases easier to explore.

I'm also considering optional local AI integration through Ollama to generate code summaries and explain dependency relationships without making AI a requirement for the core scanner.

Check Out the Project

GitHub repository: https://github.com/sreevatsarajesh/Codebase_XRay

I'd Love Your Feedback

• What would you want to see in a codebase visualization tool?
• Which parts of understanding an unfamiliar repository take you the most time?
• Would AI-generated explanations of code relationships be useful, or would you prefer purely static analysis?

Thanks for reading!