code-explainer

Ask plain-English questions about any GitHub monorepo. Get business-friendly answers grounded in your actual code.

Quick start

git clone https://github.com/taheroo/code-explainer
cd code-explainer

Windows

python -m venv .venv
.venv\Scripts\activate
pip install -r rag_backend/requirements.txt

macOS / Linux (Python 3)

python3 -m venv .venv
source .venv/bin/activate
pip3 install -r rag_backend/requirements.txt

Create rag_backend/.env:

REPO_MODE=monorepo
MONOREPO_URL=https://github.com/your-org/your-repo
OPENROUTER_API_KEY=sk-or-...       # openrouter.ai
LLM_MODEL=google/gemma-4-31b-it:free
QDRANT_COLLECTION=codebase
HF_TOKEN=hf_...                    # huggingface.co
GITHUB_TOKEN=                      # optional, for private repos

uvicorn rag_backend.main:app --reload

Auto-clones your repo, indexes all service folders, serves on http://localhost:8000.

Using Docker

Prerequisites: Docker (with Compose plugin).

# 1. Create .env from template and fill in your API keys
cp .env.example .env

# 2. Build and start both services (Qdrant + rag-backend)
docker compose up --build -d

# 3. Watch startup logs (models load, then server starts)
docker compose logs -f rag-backend

# 4. Check health
curl http://localhost:8000/health

# 5. Ingest the code into Qdrant
curl -X POST http://localhost:8000/ingest \
  -H "Content-Type: application/json" \
  -d '{}'

# 6. Ask a question
curl -X POST http://localhost:8000/query \
  -H "Content-Type: application/json" \
  -d '{"question":"What does this project do?"}'

# 7. Stop everything
docker compose down

Windows users: PowerShell replaces curl with its own alias. Use curl.exe or prefix with cmd /c "...". Example: cmd /c "curl -s http://localhost:8000/health".

The .env file lives at the project root (not inside rag_backend/), and the cloned_repos/ directory is bind-mounted into the container so manual clones are visible at runtime.

If you want to clone manually

Clone your repo so its root lands directly in cloned_repos/ at the project root:

cd code-explainer
git clone https://github.com/your-org/your-repo cloned_repos

If cloned_repos/ already exists, the auto-cloner skips cloning, so a manual clone works fine.

Do not clone into a nested folder like cloned_repos/my-repo/ — the engine expects service folders as direct children of cloned_repos/, not one level deeper.

Example response

curl -X POST http://localhost:8000/query \
  -H "Content-Type: application/json" \
  -d '{"question":"How does the trust score work?"}'

{
  "answer": "The idea of this project appears to be a trust score visualization feature. From a user perspective, it displays a score, likely indicating the level of trust or credibility, in a graphical and animated manner.\n\nThe business problem it solves is to provide a clear and engaging way to communicate trust scores to users, helping them make informed decisions. The impact on users is that they can quickly and easily understand the trust score, with the animation and colors used to convey the score in a visually appealing and intuitive way."
}

Deployment

The app is deployed on Render with Qdrant Cloud for vector storage.

Live instance

• URL: https://code-explainer-c8g2.onrender.com
• Qdrant: Managed cloud instance for persistent vector data

Architecture

Component	Service
App server	Render — FastAPI (uvicorn) inside Docker
Vector DB	Qdrant Cloud — dense + sparse hybrid search
LLM	Groq
Embeddings	Sentence Transformers (BGE-small) baked into Docker image

Environment variables (Render dashboard)

QDRANT_URL=https://your-qdrant-cloud-instance.cloud.qdrant.io
QDRANT_API_KEY=qdrant-...
GROQ_API_KEY=gsk-...

The Dockerfile builds the backend, the docker-compose.yml is used for local development (with a local Qdrant container). On Render, Qdrant Cloud replaces the local container.

Architecture

Pipeline

Step	What happens
Ingest	Scans repos, chunks code by function/class (AST for Python, regex for JS/TS), embeds dense + sparse vectors, stores in Qdrant
Retrieve	Hybrid dense/sparse search → RRF merge → top chunks
Generate	LLM (Groq) summarizes chunks with strict grounding prompt

Endpoints

Endpoint	Method	Description
/query	POST	Ask a question, returns answer
/ingest	POST	Re-index repos (optional repo param)
/health	GET	Server health check
/session/{id}/clear	GET	Clear chat history