ExplainMyCode 🔍

AI-powered GitHub repository architectural analysis. Paste a public repo URL — get a senior-engineer-level explanation in seconds.

---

Features

• 🔗 Submit any public GitHub repository URL
• 🔎 Automatic language & framework detection via file heuristics
• 📦 Dependency parsing (npm, pip, go, maven, cargo, rubygems…)
• 🤖 AI architectural explanation with enforced JSON schema output
• 🌲 Interactive repository tree visualization
• 📜 Analysis history with status tracking
• ⚡ Async job queue — never blocks the HTTP request
• 🐳 Full Docker Compose setup (one command to run everything)

---

Architecture

User ──► Next.js Frontend ──► FastAPI Backend ──► Celery Worker
                                     │                   │
                                  PostgreSQL           Redis
                                                         │
                                              GitPython clone + scan
                                                         │
                                              OpenAI structured JSON

---

Quick Start (Docker Compose — recommended)

Prerequisites

• Docker Desktop + Docker Compose
• An OpenAI API key

1. Clone & configure

git clone https://github.com/your-username/explainmycode
cd explainmycode
cp .env.example .env

Edit .env and fill in:

OPENAI_API_KEY=sk-...          # Required
SECRET_KEY=<openssl rand -hex 32>  # Required — generate a real key
POSTGRES_PASSWORD=<strong-password>

2. Start all services

docker-compose up --build -d

Services:

Service	URL
Frontend (Next.js)	http://localhost:3000
Backend (FastAPI)	http://localhost:8000
API Docs (Swagger)	http://localhost:8000/docs
PostgreSQL	localhost:5432
Redis	localhost:6379

3. Run database migrations (first time only)

Migrations run automatically on backend startup via:

alembic upgrade head

---

Manual Setup (Development)

Backend

Requirements: Python 3.11+, PostgreSQL 14+, Redis 6+, Git

cd backend

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

# Install dependencies
pip install -e ".[dev]"
# Also install psycopg2:
pip install psycopg2-binary

# Configure environment
cp ../.env.example .env
# Edit .env with your local values:
# DATABASE_URL=postgresql+asyncpg://postgres:password@localhost:5432/explainmycode
# REDIS_URL=redis://localhost:6379/0
# OPENAI_API_KEY=sk-...
# SECRET_KEY=<generate one>
# ALLOWED_ORIGINS=http://localhost:3000

# Run migrations
alembic upgrade head

# Start the API
uvicorn app.main:app --reload --port 8000

# In a separate terminal — start Celery worker:
celery -A app.tasks.celery_app worker --loglevel=info --queues=analysis

Frontend

Requirements: Node.js 18+

cd frontend

npm install

# Configure environment
echo "NEXT_PUBLIC_API_URL=http://localhost:8000" > .env.local
echo "NEXT_PUBLIC_POLL_INTERVAL_MS=2000" >> .env.local

npm run dev

Visit: http://localhost:3000

---

Environment Variables Reference

Backend / Docker

Variable	Required	Default	Description
DATABASE_URL	✅	—	PostgreSQL asyncpg connection string
REDIS_URL	✅	—	Redis URL for Celery broker
OPENAI_API_KEY	✅	—	OpenAI API key for AI explanations
SECRET_KEY	✅	—	32+ char random secret (use openssl rand -hex 32)
OPENAI_MODEL	❌	gpt-4o-mini	OpenAI model to use
OPENAI_MAX_TOKENS	❌	2048	Max tokens for LLM response
ALLOWED_ORIGINS	❌	http://localhost:3000	Comma-separated CORS origins
LOG_LEVEL	❌	INFO	Logging level
REPO_SCAN_MAX_DEPTH	❌	4	Max folder depth to scan
GITHUB_TOKEN	❌	—	Optional GitHub token for higher rate limits

Frontend

Variable	Required	Default	Description
NEXT_PUBLIC_API_URL	✅	http://localhost:8000	Backend API base URL
NEXT_PUBLIC_POLL_INTERVAL_MS	❌	2000	Job status polling interval in ms

---

Project Structure

explainmycode/
├── backend/
│   ├── app/
│   │   ├── api/v1/jobs.py          # API routes
│   │   ├── core/config.py          # Settings (pydantic-settings)
│   │   ├── core/logging.py         # JSON structured logging
│   │   ├── db/session.py           # Async DB session
│   │   ├── models/repository.py    # SQLAlchemy ORM models
│   │   ├── schemas/schemas.py      # Pydantic v2 schemas
│   │   ├── services/scanner.py     # Repo cloning & scanning
│   │   ├── services/ai.py          # OpenAI integration
│   │   ├── tasks/analysis.py       # Celery task
│   │   └── main.py                 # FastAPI app factory
│   ├── alembic/                    # Database migrations
│   ├── tests/test_scanner.py       # Unit tests
│   ├── Dockerfile
│   └── pyproject.toml
├── frontend/
│   ├── app/                        # Next.js 14 App Router
│   │   ├── layout.tsx
│   │   ├── page.tsx                # Home / submit form
│   │   ├── jobs/[id]/page.tsx      # Job status & results
│   │   └── history/page.tsx        # Analysis history
│   ├── components/
│   │   ├── SubmitForm.tsx
│   │   ├── StatusPoller.tsx
│   │   ├── ResultsDashboard.tsx
│   │   ├── RepoTreeView.tsx
│   │   └── HistoryTable.tsx
│   ├── lib/api.ts                  # Typed API client
│   ├── types/index.ts              # TypeScript types
│   └── Dockerfile
├── docker-compose.yml
├── .env.example
└── README.md

---

Running Tests

cd backend
pip install -e ".[dev]"
pytest tests/ -v

Tests do not require network access or a real database.

---

API Endpoints

Method	Path	Description
POST	/api/v1/jobs	Submit a repository URL for analysis
GET	/api/v1/jobs	List all jobs (paginated)
GET	/api/v1/jobs/{job_id}	Get job status + result
GET	/health	Health check
GET	/docs	Swagger UI

---

Security Notes

• No code is executed from scanned repositories
• Repositories are cloned with --depth 1 (shallow) and deleted after scanning
• All secrets are loaded from environment variables — never hardcoded
• API keys are never exposed to the frontend
• CORS is restricted to configured ALLOWED_ORIGINS

---

License

MIT