Codebase Cartographer 🗺️

Stop reading code. Start seeing it.

Codebase Cartographer is an AI-powered developer tool that instantly visualizes the structure of your project. It turns spaghetti code into an interactive map, explaining every function and warning you about critical dependencies using Google Gemini AI.

project_demo.mp4

🚀 Why this exists?

The Problem

1. Onboarding is painful: Jumping into a new codebase takes days of reading widely scattered files.
2. Spaghetti Code is invisible: It’s hard to see how a change in utils.js breaks payment.py until it’s too late.
3. Documentation rots: READMEs are rarely updated, but the code never lies.

The Solution Codebase Cartographer acts as an autonomous senior engineer. It:

1. Scans your local folder (Python, JS, TS, Java).
2. Maps the functions and their relationships.
3. Explains what every function does using AI.
4. Warns you about critical risks ("If you touch this, billing breaks").

✨ Features

• ⚡ Polyglot Support: Works with Python, JavaScript, TypeScript, and Java out of the box.
• 🤖 AI-Powered: Uses Google Gemini 2.5 Flash to summarize code logic in plain English.
• 🛡️ Risk Analysis: Automatically flags "Critical" functions (e.g., payment processing, auth).
• 🔌 Zero-Config CLI: No databases, no Docker. Just pip install and run.
• 🕸️ Interactive Graph: Built with React Flow to visualize complex dependencies easily.

🛠️ Installation

Prerequisites

• Python 3.8+
• A Google Gemini API Key (Free Tier is fine)

1. Clone the repo

git clone https://github.com/yourusername/codebase-cartographer.git
cd codebase-cartographer

2. Install Dependencies

pip install -e .

3. Setup API Key Create a .env file in the backend folder:

# backend/.env
GEMINI_API_KEY="AIzaSyYourKeyHere..."

🏃‍♂️ How to Run

You can run the tool on the current folder, or point it at any other project on your computer.

Scan the current folder

python backend/cli.py .

Scan another project

python backend/cli.py "C:/Users/Dev/Projects/MyOtherApp"

The tool will automatically:

1. Launch a local server.
2. Open your browser to http://localhost:8000.
3. Start analyzing files and rendering the map.

🏗️ Architecture

This is a Hybrid App that packages a modern React frontend inside a Python CLI.

• Frontend: React, React Flow, Dagre (Auto-layout).
• Backend: FastAPI, Uvicorn.
• AI Engine: Google Gemini 2.5 Flash (via google-generativeai).
• Parser: Custom "Unbreakable" Regex-based parser (No heavy dependencies like Tree-sitter).

Directory Structure

/backend
  ├── cli.py           # Entry point (Typer CLI + FastAPI)
  ├── mapper.py        # Core Logic (Regex Parsing + Gemini AI)
  └── /dist            # Compiled React Frontend (Static files)
/frontend
  ├── src/             # React Source Code
  └── package.json

🤝 Contributing

1. Fork the repo.
2. cd frontend and npm install.
3. Run npm run dev for frontend development.
4. Run python backend/cli.py for backend testing.
5. Submit a PR!

License

MIT