Codebase Cartographer

Overview

Codebase Cartographer is a full-stack application for visualizing software architecture and dependency relationships in GitHub repositories. It combines authenticated analysis workflows, background processing, and an interactive React dashboard to help developers inspect repository structure, identify cyclic dependencies, and manage analysis history.

This repository is designed for developers and teams who need a clean, modern interface for analyzing codebase architecture without manually tracing imports or file relationships.

Table of Contents

• Features
• Tech Stack
• Installation
• Configuration
• Running Locally
• API Endpoints
• Usage
• Project Structure
• Deployment
• Contributing
• License

Features

• Authenticated GitHub repository analysis
• Background task processing with Celery and Redis
• Tree-sitter parsing for Python, JavaScript, and TypeScript
• Dependency graph generation with NetworkX
• Persistent project history in MongoDB
• Interactive dashboard with search, filtering, and multiple graph layouts
• Branch selection and GitHub URL validation
• Rate-limited analysis endpoint for abuse protection

Tech Stack

Backend

• Python 3.8+
• FastAPI
• Uvicorn
• Celery
• Redis
• MongoDB
• Tree-sitter
• NetworkX
• GitPython
• Pydantic

Frontend

• React
• TypeScript
• Vite
• Tailwind CSS
• Lucide React icons

Installation

Prerequisites

• Python 3.8 or newer
• Node.js 16 or newer
• Git
• MongoDB
• Redis

Backend setup

cd backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Frontend setup

cd frontend
npm install

Configuration

Backend environment variables

Set these values in your shell or a .env file before running the backend.

• MONGO_URI — MongoDB connection string (default: mongodb://localhost:27017)
• REDIS_URL — Redis broker/backend URL (default: redis://localhost:6379)
• JWT_SECRET_KEY — JWT signing secret for user authentication
• JWT_EXPIRE_MINUTES — Token expiry in minutes (default: 60)
• GIT_CLONE_TIMEOUT — Git clone timeout in seconds (default: 300)
• FILE_SCAN_TIMEOUT — File scan timeout in seconds (default: 60)
• PARSING_TIMEOUT — Source parsing timeout in seconds (default: 240)
• TOTAL_ANALYSIS_TIMEOUT — Maximum analysis runtime in seconds (default: 600)
• MAX_REPO_SIZE_GB — Maximum repository size in GB (default: 2)
• MAX_FILE_SIZE_MB — Maximum individual file size in MB (default: 50)
• MAX_FILES_IN_REPO — Maximum scanned source files (default: 50000)

Note: the frontend currently uses frontend/lib/client.js with a hardcoded API base URL of http://localhost:8000. Update this value for remote or production deployments.

Running Locally

Start Redis and MongoDB

Start both services before launching the backend.

Start Celery worker

cd backend
celery -A core.tasks worker --loglevel=info

Start backend API

cd backend
source venv/bin/activate
uvicorn main:app --host 0.0.0.0 --port 8000 --reload

Start frontend app

cd frontend
npm run dev

The UI should be available at http://localhost:5173.

API Endpoints

The backend exposes these authenticated endpoints:

• POST /api/auth/register — register a new user
• POST /api/auth/login — authenticate and receive a JWT
• GET /api/projects — list user analysis history
• GET /api/projects/{project_id} — retrieve a stored analysis result
• DELETE /api/projects/{project_id} — delete an analysis record
• POST /api/analyze — queue a GitHub repository analysis

Notes

• POST /api/analyze is rate limited to 5 requests per minute per IP
• All /api/projects routes and /api/analyze require a Bearer token
• The analysis process is asynchronous and executed via Celery

Usage

1. Register or log in through the frontend UI
2. Enter a valid GitHub repository URL and optional branch
3. Submit the analysis request
4. Monitor the analysis status in the project dashboard
5. View the generated dependency graph, metrics, and repository summary

What the app shows

• Graph nodes representing repository files and code entities
• Dependency links between files based on parsed imports
• Project complexity and circular dependency metrics
• History of analyzed repositories per user
• Interactive node search and filter controls

Project Structure

codebase-cartographer/
├── backend/
│   ├── main.py
│   ├── config.py
│   ├── database.py
│   ├── models.py
│   ├── requirements.txt
│   ├── core/
│   │   ├── auth.py
│   │   ├── downloader.py
│   │   ├── errors.py
│   │   ├── graph_builder.py
│   │   ├── parser.py
│   │   └── tasks.py
│   └── tests/
├── frontend/
│   ├── index.html
│   ├── package.json
│   ├── tsconfig.json
│   ├── vite.config.ts
│   ├── src/
│   │   ├── App.tsx
│   │   ├── main.tsx
│   │   ├── types.ts
│   │   ├── components/
│   │   └── lib/
│   └── .env.example
└── README.md

Deployment

For production deployment:

1. Use a secure JWT_SECRET_KEY
2. Configure MONGO_URI and REDIS_URL
3. Run a Celery worker alongside the backend
4. Build the frontend with npm run build
5. Serve the frontend from a static host or CDN
6. Point the frontend API client to the deployed backend URL

Recommended production commands:

cd backend
uvicorn main:app --host 0.0.0.0 --port 8000

cd frontend
npm run build
npm run preview

Contributing

Contributions are welcome. To contribute:

1. Fork the repository
2. Create a new branch
3. Add tests and update types as needed
4. Open a pull request with a clear description of your changes

If you extend analysis metrics, keep backend models consistent with backend/models.py and frontend types in frontend/src/types.ts.

License

Released under the MIT License.