🤖 AI Code Documentation Generator

A full-stack application that analyzes GitHub repositories, visualizes dependency graphs, and generates comprehensive documentation using Google Gemini AI with real-time streaming.

✨ Features

📊 Repository Analysis

Multi-language parsing (Python, JavaScript, TypeScript)
Dependency graph visualization with React Flow
Circular dependency detection using DFS algorithm
Statistics dashboard showing most imported/importing files
Real-time filtering by search query and language

🤖 AI-Powered Documentation

Streaming documentation generation via Server-Sent Events
README.md generation with Chain-of-Thought prompting
Unit test generation for individual files
Real-time progress tracking with live updates
Syntax-highlighted code blocks and markdown rendering

🎨 Interactive UI

Zoom, pan, and explore dependency graphs
Color-coded nodes by programming language
Search and filter capabilities
Minimap navigation for large graphs
Responsive design optimized for desktop

🔒 Production-Ready

Rate limiting with sliding window algorithm
Ephemeral storage with automatic cleanup
Global error handling with structured responses
CORS security configuration
Docker containerization with multi-stage builds

🏗️ Architecture

┌─────────────────────────────────────────┐
│    Frontend (Next.js 14 + React Flow)   │
│  • Interactive graph visualization      │
│  • Real-time SSE streaming              │
│  • Zustand state management             │
└─────────────────────────────────────────┘
              ↓ HTTP/SSE
┌─────────────────────────────────────────┐
│       Backend (FastAPI + Python)        │
│  • Repository cloning & parsing         │
│  • Dependency graph construction        │
│  • Google Gemini AI integration         │
│  • Rate limiting & concurrency control  │
└─────────────────────────────────────────┘

🚀 Quick Start

Prerequisites

Python 3.11+
Node.js 18+
Git
Google Gemini API key (Get one here)

1. Clone Repository

git clone https://github.com/yourusername/ai-code-doc-generator.git
cd ai-code-doc-generator

2. Backend Setup

cd backend

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Configure environment
cp .env.example .env
# Edit .env and add your GEMINI_API_KEY

# Create __init__.py files
touch app/{__init__,config/__init__,middleware/__init__,core/__init__,models/__init__,services/__init__,api/__init__,api/v1/__init__,api/v1/routes/__init__}.py

# Start server
python -m app.main

Backend will run at http://localhost:8000

3. Frontend Setup

cd frontend

# Install dependencies
npm install

# Configure environment
cp .env.local.example .env.local

# Start development server
npm run dev

Frontend will run at http://localhost:3000

4. Test the Application

Open http://localhost:3000 in your browser
Enter a GitHub repository URL (e.g., https://github.com/psf/requests)
Click "Analyze" to visualize the dependency graph
Switch to "Generate Docs" tab for AI-powered documentation

🐳 Docker Deployment

# Build and start both services
docker-compose up --build

# Access the application
# Backend: http://localhost:8000
# Frontend: http://localhost:3000

📖 API Documentation

Analysis Endpoints

Analyze Repository Graph

POST /api/v1/analyze/graph
Content-Type: application/json

{
  "url": "https://github.com/pallets/flask"
}

Response:

{
  "nodes": [...],
  "edges": [...],
  "metadata": {
    "repository_url": "https://github.com/pallets/flask",
    "total_files": 45,
    "languages": {"python": 45},
    "analysis_time_seconds": 12.5
  },
  "statistics": {
    "most_imported": [...],
    "most_importing": [...],
    "circular_dependencies": [...]
  }
}

AI Generation Endpoints

Stream Documentation

GET /api/v1/generate/documentation/stream?url=https://github.com/pallets/flask

Response: Server-Sent Events stream with real-time progress

Generate README

POST /api/v1/generate/readme
Content-Type: application/json

{
  "url": "https://github.com/pallets/flask",
  "summary": "A lightweight WSGI web framework"
}

Generate Unit Tests

POST /api/v1/generate/unit-test
Content-Type: application/json

{
  "url": "https://github.com/pallets/flask",
  "file_path": "src/flask/app.py"
}

See API_DOCUMENTATION.md for complete API reference.

🎯 Usage Examples

Analyzing a Repository

import requests

# Analyze repository
response = requests.post(
    'http://localhost:8000/api/v1/analyze/graph',
    json={'url': 'https://github.com/pallets/flask'}
)

data = response.json()
print(f"Found {len(data['nodes'])} files")
print(f"Languages: {data['metadata']['languages']}")

Streaming Documentation

const eventSource = new EventSource(
  'http://localhost:8000/api/v1/generate/documentation/stream?url=https://github.com/pallets/flask'
);

eventSource.addEventListener('file_complete', (e) => {
  const data = JSON.parse(e.data);
  console.log('Documented:', data.file_path);
  console.log('Content:', data.documentation);
});

eventSource.addEventListener('complete', (e) => {
  const data = JSON.parse(e.data);
  console.log(`Done! ${data.total_files_documented} files in ${data.total_time_seconds}s`);
  eventSource.close();
});

⚙️ Configuration

Backend Environment Variables

# Required
GEMINI_API_KEY=your_gemini_api_key_here

# Optional (with defaults)
DEBUG=false
HOST=0.0.0.0
PORT=8000

# CORS
CORS_ORIGINS=["http://localhost:3000"]

# Rate Limiting
MAX_CONCURRENT_LLM_CALLS=5
GEMINI_PRO_RPM=2
GEMINI_PRO_RPD=50
GEMINI_FLASH_RPM=10
GEMINI_FLASH_RPD=250

# Timeouts
GITHUB_CLONE_TIMEOUT=300
LLM_REQUEST_TIMEOUT=120

Frontend Environment Variables

NEXT_PUBLIC_API_URL=http://localhost:8000/api/v1

🧪 Testing

Backend Tests

cd backend

# Health check
curl http://localhost:8000/api/v1/health

# Analyze repository
curl -X POST http://localhost:8000/api/v1/analyze/graph \
  -H "Content-Type: application/json" \
  -d '{"url": "https://github.com/psf/requests"}'

Frontend Tests

cd frontend

# Run linter
npm run lint

# Type check
npx tsc --noEmit

# Build production
npm run build

End-to-End Testing

See COMPLETE_TESTING_GUIDE.md for comprehensive testing instructions.

📊 Performance

Analysis Performance

Repository Size	Files	Analysis Time	Memory Usage
Small	10-20	3-5 seconds	<100MB
Medium	50-100	8-15 seconds	<300MB
Large	200+	20-40 seconds	<500MB

Documentation Generation

Repository Size	Generation Time	Rate Limit
Small (10-20 files)	30-60 seconds	10 RPM (Flash)
Medium (50-100 files)	2-5 minutes	10 RPM
Large (200+ files)	10-30 minutes	May hit RPD

🛠️ Technology Stack

Backend

FastAPI - Modern async web framework
Google Generative AI - Gemini 2.0 Flash
GitPython - Repository cloning
Python AST - Native Python parsing
SSE-Starlette - Server-Sent Events streaming
Pydantic - Data validation

Frontend

Next.js 14 - React framework with App Router
React Flow - Graph visualization
Dagre - Graph layout algorithm
Zustand - State management
Tailwind CSS - Utility-first styling
React Markdown - Markdown rendering
Syntax Highlighter - Code highlighting

Infrastructure

Docker - Containerization
Uvicorn - ASGI server
Nginx - Reverse proxy (production)

📁 Project Structure

ai-code-doc-generator/
├── backend/
│   ├── app/
│   │   ├── api/v1/routes/      # API endpoints
│   │   ├── config/             # Configuration
│   │   ├── core/               # Core utilities
│   │   ├── middleware/         # Middleware (CORS, rate limiting)
│   │   ├── models/             # Pydantic schemas
│   │   ├── services/           # Business logic
│   │   └── main.py             # FastAPI application
│   ├── temp_repos/             # Ephemeral storage (gitignored)
│   ├── requirements.txt        # Python dependencies
│   └── Dockerfile              # Backend container
├── frontend/
│   ├── src/
│   │   ├── app/                # Next.js pages
│   │   ├── components/         # React components
│   │   ├── services/           # API client
│   │   └── store/              # Zustand store
│   ├── package.json            # Node dependencies
│   └── Dockerfile              # Frontend container
├── docker-compose.yml          # Multi-container setup
└── README.md                   # This file

🔐 Security

Input Validation: All requests validated with Pydantic models
CORS: Configurable allowed origins
Rate Limiting: Sliding window algorithm prevents API abuse
Ephemeral Storage: Repositories automatically cleaned up
No Persistence: Stateless design, no data retention
Environment Variables: Sensitive data in environment, not code

🚦 Rate Limiting

Gemini API Limits

Model	Requests/Minute	Requests/Day
Gemini 2.5 Pro	2	50
Gemini 2.5 Flash	10	250

Global Concurrency

Max Concurrent Requests: 5 (configurable)
Algorithm: Sliding window with async wait
Behavior: Requests wait, don't fail

🐛 Troubleshooting

"CORS Error" in Frontend

Solution: Verify backend .env includes frontend URL:

CORS_ORIGINS=["http://localhost:3000"]

"Rate Limit Exceeded"

Solution: Wait for rate limit window to reset, or reduce MAX_CONCURRENT_LLM_CALLS

Graph Not Rendering

Solution: Check browser console for errors, verify React Flow CSS loaded

Stream Disconnects

Solution: Check backend logs, verify rate limits, increase timeouts

See Troubleshooting Section for more solutions.

📚 Documentation

API Documentation - Complete API reference
Deployment Guide - Production deployment
Frontend Setup - Frontend development guide
Testing Guide - End-to-end testing
Phase Guides - Phase-specific testing

🤝 Contributing

Contributions are welcome! Please follow these steps:

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

Development Guidelines

Follow PEP 8 for Python code
Use TypeScript for all frontend code
Write descriptive commit messages
Add tests for new features
Update documentation as needed

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

FastAPI - For the excellent async web framework
Google Gemini - For powerful AI capabilities
React Flow - For beautiful graph visualization
Next.js - For the amazing React framework
Tailwind CSS - For utility-first styling

📧 Contact

Issues: GitHub Issues
Discussions: GitHub Discussions
Email: your.email@example.com

🗺️ Roadmap

Version 1.0 (Current)

✅ Repository analysis
✅ Dependency graph visualization
✅ AI documentation generation
✅ Real-time streaming
✅ Statistics dashboard

📊 Stats

Lines of Code: ~5,000+
API Endpoints: 7
Technologies: 15+
Docker Containers: 2
Supported Languages: 3 (Python, JavaScript, TypeScript)

⭐ Star History

If you find this project useful, please consider giving it a star! ⭐

Built with ❤️ using FastAPI, Next.js, and Google Gemini AI

Report Bug · Request Feature · Documentation

FilesExpand file tree

README.md

Latest commit

History