# GitVizz

Understand Any Codebase in Minutes, Not Hours

AI-powered repository analysis that turns complex codebases into interactive documentation, dependency graphs, and intelligent conversations.

Live Demo | Documentation | Report Bug | Request Feature

---

What is GitVizz?

GitVizz revolutionizes how developers understand and navigate codebases. Whether you're onboarding to a new project, reviewing code, or exploring open source repositories, GitVizz transforms complex code structures into intuitive, interactive experiences.

---

https://github.com/user-attachments/assets/52eeb2c1-598b-4173-b0e8-8d4b986dbf64

Features Showcase

### Graph Search **Interactive dependency graphs with intelligent search capabilities**	### Graph Dependency View **Visual code navigation with smart highlighting and dependency connections**
### Chat with Repository **AI-powered conversations about your codebase with context-aware responses**	### Code Viewer **Advanced code visualization with syntax highlighting and navigation**
### LLM Context Builder **Build comprehensive context for Large Language Models automatically**	### Documentation Generator **Automatically generate comprehensive documentation from your repository**

---

Why GitVizz?

• Instant Understanding: Analyze any repository in seconds, not hours
• AI-Powered Insights: Get intelligent summaries and explanations
• Visual Code Maps: Interactive dependency graphs and code relationships
• Chat with Code: Ask questions about any codebase and get instant answers
• Auto Documentation: Generate comprehensive docs automatically
• Smart Search: Find functions, classes, and patterns across entire repositories

---

Quick Start

Option 1: Try Online (Fastest)

Visit gitvizz.com and paste any GitHub repository URL to get started instantly!

Option 2: Docker Compose (Recommended for Local Development)

# Clone the repository
git clone https://github.com/adithya-s-k/gitvizz.git
cd gitvizz

# Copy environment files
cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env.local

# Start all services
docker-compose up --build

Access Points:

• Frontend: http://localhost:3000
• Backend API: http://localhost:8003
• Phoenix UI: http://localhost:6006 (LLM observability dashboard)

📊 Phoenix Observability: GitVizz includes Arize Phoenix for comprehensive LLM monitoring and tracing. See Phoenix Setup Guide for detailed configuration options.

Option 3: Manual Setup

Click to expand manual setup instructions

Backend Setup

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r backend/requirements.txt

# Configure environment
cp backend/.env.example backend/.env
# Edit backend/.env with your settings

# Start backend server
uvicorn backend.server:app --host 0.0.0.0 --port 8003 --reload

Frontend Setup

# Install dependencies
cd frontend
pnpm install

# Configure environment
cp .env.example .env.local
# Edit .env.local with your settings

# Start development server
pnpm dev

---

Architecture

GitVizz is built with modern, scalable technologies:

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Frontend      │    │    Backend      │    │   AI Services   │
│                 │    │                 │    │                 │
│ • Next.js 14    │◄──►│ • FastAPI       │◄──►│ • OpenAI        │
│ • TypeScript    │    │ • Python 3.9+  │    │ • Anthropic     │
│ • Tailwind CSS  │    │ • Async/Await   │    │ • Local LLMs    │
│ • ShadCN UI     │    │ • Pydantic      │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Tech Stack

Frontend:

• Next.js 14 - React framework with App Router
• Tailwind CSS - Utility-first CSS framework
• ShadCN UI - Beautiful, accessible components
• Responsive Design - Works on all devices

Backend:

• FastAPI - High-performance Python API framework
• AST Parsing - Advanced code analysis
• Graph Generation - Dynamic dependency mapping
• LLM Integration - Multiple AI provider support

---

Prerequisites

Required

• Node.js 18+ and pnpm
• Python 3.9+ and pip
• Docker & Docker Compose (for containerized setup)

Optional (for enhanced features)

• MongoDB - For user data and repository metadata storage
• GitHub Personal Access Token - For private repo access
• GitHub App - For advanced GitHub integration
• OpenAI API Key - For AI-powered features
• Anthropic API Key - Alternative AI provider
• Gemini API Key - Google's AI model support
• Groq API Key - Fast inference API
• Phoenix - LLM observability and tracing platform

---

Configuration & Setup

Environment Variables

Backend (.env)

# GitHub Integration
GITHUB_USER_AGENT=gitvizz-cognitivelab

# JWT Authentication
JWT_SECRET=your-jwt-secret-here-use-openssl-rand-base64-32
JWT_ALGORITHM=HS256
JWT_EXPIRE_MINUTES=10080  # 7 days
REFRESH_TOKEN_EXPIRE_DAYS=30  # 30 days

# Database Configuration
MONGO_URI=mongodb://localhost:27017
MONGODB_DB_NAME=gitvizz

# Server Configuration
HOST=0.0.0.0
PORT=8003

# File Storage
FILE_STORAGE_BASEPATH="storage"

# Data Encryption
ENCRYPTION_KEY=your-32-byte-base64-encryption-key-here
FERNET_KEY=your-32-byte-base64-encryption-key-here

# GitHub OAuth App Credentials
GITHUB_CLIENT_ID=your-github-oauth-client-id
GITHUB_CLIENT_SECRET=your-github-oauth-client-secret

# GitHub App Credentials (if using GitHub App instead of OAuth)
GITHUB_APP_ID=your-github-app-id
GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
your-github-app-private-key-here
-----END RSA PRIVATE KEY-----"

# Phoenix Observability (Optional)
PHOENIX_API_KEY=your-phoenix-api-key
PHOENIX_COLLECTOR_ENDPOINT=https://app.phoenix.arize.com

# LLM API Keys (at least one required)
OPENAI_API_KEY=your-openai-api-key-here
ANTHROPIC_API_KEY=your-anthropic-api-key-here
GEMINI_API_KEY=your-gemini-api-key-here
GROQ_API_KEY=your-groq-api-key-here

Frontend (.env.local)

# API base URL for the frontend application
NEXT_PUBLIC_BACKEND_URL=http://localhost:8003

# NextAuth Configuration
NEXTAUTH_URL=http://localhost:3000
AUTH_SECRET="your-auth-secret-here"

# GitHub App Integration
NEXT_PUBLIC_GITHUB_APP_NAME=your-github-app-name
AUTH_GITHUB_ID=your-github-app-client-id
AUTH_GITHUB_SECRET=your-github-app-client-secret

GitHub Integration Setup

Creating a GitHub Personal Access Token

Step-by-step guide to create a GitHub Personal Access Token

1. Navigate to GitHub: Go to github.com and sign in
2. Access Profile Settings: Click your profile picture → Settings
3. Developer Settings: Scroll down and click "Developer settings"
4. Personal Access Tokens: Click "Personal access tokens" → "Tokens (classic)"
5. Generate New Token: Click "Generate new token" → "Generate new token (classic)"
6. Authenticate: Use your password to confirm
7. Configure Token:
8. Note: Give your token a descriptive name
9. Expiration: Set appropriate expiration date
10. Scopes: Select required permissions
11. Repository Access: Choose "All repositories" for full access
12. Generate: Click "Generate token"

Important: Copy and save the token immediately - you won't be able to see it again!

For detailed instructions with screenshots, see docs/github_personal_token.md

Creating a GitHub App

Step-by-step guide to create a GitHub App

1. Navigate to GitHub Apps: Go to GitHub Apps settings
2. Create New App: Click "New GitHub App"

3. App Details:

4. GitHub App name: Enter your application name

5. Homepage URL: http://localhost:3000/
6. Callback URL: http://localhost:3000/api/auth/callback/github
7. Expire user authorization tokens: Deselect this
8. Setup URL: http://localhost:3000/

9. Webhook: Deselect "Active" to disable webhooks

10. Set Permissions:

11. Repository Permissions → Contents: Read-only

12. Account Permissions → Email addresses: Read-only

13. Create App: Click "Create GitHub App"

14. Get Credentials:
15. Copy App ID and Client ID
16. Generate and copy Client Secret
17. Generate Private Key:
18. Click "Generate a private key"
19. Download the .pem file
20. Copy entire contents including BEGIN/END lines
21. Wrap in double quotes for .env file

For detailed instructions with screenshots, see docs/create_github_app.md

---

Contributing

We love contributions! GitVizz is open source and community-driven.

Ways to Contribute

• Report Bugs - Found an issue? Let us know!
• Suggest Features - Have ideas? We'd love to hear them!
• Improve Documentation - Help others understand GitVizz better
• Submit Pull Requests - Code contributions are always welcome!
• Star the Repository - Show your support!

Development Workflow

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Commit Convention

We follow Conventional Commits:

• feat: New features
• fix: Bug fixes
• docs: Documentation changes
• style: Code style changes
• refactor: Code refactoring
• test: Adding tests
• chore: Maintenance tasks

---

Project Structure

gitvizz/
├── frontend/                 # Next.js frontend application
│   ├── app/                     # App router pages
│   ├── components/              # Reusable UI components
│   ├── api-client/              # Generated API client
│   └── public/                  # Static assets
├── backend/                  # FastAPI backend application
│   ├── controllers/             # API route handlers
│   ├── documentation_generator/ # AI-powered analysis
│   ├── models/                  # Data models
│   ├── routes/                  # API routes
│   ├── schemas/                 # Request/response schemas
│   ├── services/                # Business logic
│   └── utils/                   # Utility functions
├── gitvizz/                  # 📦 GitVizz Core Library
│   ├── gitvizz/                 # Python package
│   │   ├── graph_generator.py      # Main graph generation engine
│   │   ├── custom_ast_parser.py    # AST parsing with Tree-sitter
│   │   └── modal_app.py            # Optional Modal integration
│   ├── pyproject.toml           # Package configuration
│   └── README.md                # Library documentation
├── docs/                     # Documentation
├── docker-compose.yaml       # Container orchestration
└── README.md                 # You are here!

---

GitVizz Core Library

GitVizz includes a standalone Python library (gitvizz/) that provides the core code analysis and dependency graph generation functionality. This library can be used independently in your own projects:

Features

• 🐍 Multi-language Parsing: Python, JavaScript, TypeScript, React, Next.js
• 🌳 AST Analysis: Advanced Abstract Syntax Tree parsing with Tree-sitter
• 🕸️ Dependency Graphs: Generate detailed code relationship maps
• 📊 Interactive Visualizations: HTML graph outputs with Pyvis
• ⚡ Fast & Efficient: Optimized for large codebases
• 🔧 Extensible: Plugin architecture for new languages

Quick Start

```bash

Install the library

pip install git+https://github.com/adithya-s-k/GitVizz.git#subdirectory=gitvizz

Use in your Python code

fr