🧠 RepoMind

Your Codebase Has Answers. Ask Them.

RepoMind is a full-stack, AI-powered codebase intelligence workspace that turns any public GitHub repository into an interactive, cited conversational knowledge base.

🔗 Live Application: https://repomind-eta.vercel.app/

Explore Features • Architecture • Quickstart • API Reference • Tech Stack

---

🌟 Overview

Navigating complex or unfamiliar codebases is often slow and overwhelming. RepoMind bridges the gap between raw source code and developer understanding by combining:

• Language-Aware AST Chunking to preserve syntax boundaries.
• High-Dimension Vector Embeddings via Google Gemini.
• Multi-Angle Semantic Query Expansion targeting up to 10 architectural facets.
• Sub-Second Streaming Inference powered by Groq Llama 3.3 70B.
• Context-Grounded Prompting with file-level citations to minimize speculation.

---

⚡ Key Features

🚀 1. Autonomous Repository Ingestion

• Shallow Clone (--depth 1): Fast, lightweight cloning directly from GitHub URLs.
• Multi-Language Filtering: Scans and parses Python, JavaScript, TypeScript, JSX, TSX, C++, C Header, Java, and Markdown files while ignoring noise directories (node_modules, venv, dist, .git).
• Syntax-Aware Code Splitting: Utilizes LangChain's AST/language-specific text splitters (chunk_size: 600, chunk_overlap: 80) to keep function and class definitions coherent.
• Batch Vector Embeddings: Ingests document vectors into Qdrant Vector Database in regulated batches using gemini-embedding-2-preview.

🧠 2. Intelligent Dual-Engine Intent Router

• Conversational Classifier: Fast-path LLM analyzes incoming prompts to distinguish casual conversation ("hi", "who are you?") from technical repository queries ("explain the auth middleware").
• Direct Persona Responses: Greets and assists users with the RepoMind persona without querying the vector database unnecessarily.

🔍 3. Multi-Query Vector Retrieval & Synthesis

• 10-Angle Query Expansion: Deconstructs developer questions into up to 10 distinct technical angles (implementation details, execution flow, error handling, API routes, data structures, dependencies, classes/functions).
• Deduplicated Vector Search: Queries Qdrant concurrently across all angles and fuses unique snippets into a unified, high-relevance context window.

🛡️ 4. Context-Grounded Analysis & Citations

• Source-Constrained Prompting: Instructs the LLM to strictly rely on retrieved code snippets and state when parts are not visible.
• Source File Citations: Prompts the model to provide inline references to source files (e.g. (auth.py)).
• Fallback Transparency: When information is absent from retrieved files, the model is guided to respond: "Not visible in retrieved context."

🔐 5. Authentication & Quota Management

• Dual Auth: Email/password authentication (Bcrypt hashing + 7-day JWT tokens) and 1-click Google OAuth 2.0.
• MongoDB Usage Tracking: Daily rate-limiting (1 repo ingestion/day and 10 chats/day for registered users; guest read-only exploration).

🌌 6. Cyberpunk Glassmorphic Frontend

• Interactive UI: Custom dark mode with glowing constellation canvas particles, real-time token streaming, copy-to-clipboard code snippets, GitHub metadata fetch (stars, forks, language), and session query history.

---

🏗️ System Architecture

flowchart TD
    subgraph Client ["Frontend (HTML5 / Vanilla JS / Glassmorphic CSS)"]
        UI["Web UI (analyze.html / chat.html)"]
        Canvas["Cosmic Particle Galaxy"]
    end

    subgraph Backend ["FastAPI Application (backend/main.py)"]
        AuthRouter["Auth Router (/auth/*)"]
        IngestRouter["Ingest Router (/ingest)"]
        ChatRouter["Chat Router (/chat)"]
        ReposRouter["Repos Router (/repos)"]
    end

    subgraph RAG_Pipeline ["RAG & Processing Engine"]
        GitClone["Git Shallow Clone & Filter"]
        ASTSplitter["Language-Aware Text Splitter"]
        EmbedEngine["Google Gemini Embedding API"]
        IntentRouter{"Intent Classifier"}
        MultiQuery["10-Angle Query Generator"]
        LLM["Groq Llama-3.3-70B Streaming"]
    end

    subgraph Storage ["Databases"]
        Qdrant[("Qdrant Vector Database")]
        MongoDB[("MongoDB (Users & Usage)")]
    end

    %% Flow connections
    UI -->|1. Submit Repo URL| IngestRouter
    IngestRouter --> GitClone --> ASTSplitter --> EmbedEngine --> Qdrant
    IngestRouter --> MongoDB

    UI -->|2. Ask Question| ChatRouter
    ChatRouter --> IntentRouter
    IntentRouter -->|Chat Intent| LLM
    IntentRouter -->|RAG Intent| MultiQuery
    MultiQuery -->|Vector Similarity Search| Qdrant
    Qdrant -->|Retrieved Snippets + Citations| LLM
    LLM -->|Real-time Token Stream| UI

    UI -->|3. Register / Login / Google OAuth| AuthRouter
    AuthRouter --> MongoDB

Loading

---

🛠️ Tech Stack

Domain	Technology	Description
Live App	Vercel	Hosted web client interface
Backend Framework	FastAPI	High-performance asynchronous REST API server
Vector Database	Qdrant	Cloud vector search engine with Cosine distance indexing
LLM Inference	Groq	Fast streaming inference with llama-3.3-70b-versatile
Embeddings	Google Gemini	gemini-embedding-2-preview semantic vector model
RAG Orchestration	LangChain	AST character splitters & vector store connectors
Database	MongoDB	User profiles, OAuth accounts, and rate-limit tracking
Security & Auth	PyJWT / Bcrypt / Google OAuth	Token-based authorization & secure password hashing
Frontend	Vanilla JS / CSS3 / HTML5	Lightweight, glassmorphic UI with zero bulky frameworks

---

📁 Project Structure

RepoMind/
├── backend/
│   ├── helpers/
│   │   ├── auth.py         # Password hashing, JWT creation/verification, usage counters
│   │   ├── github.py       # Git cloning, multi-language file filtering & AST text splitting
│   │   └── rag.py          # Embedding storage, intent classifier, multi-query generator
│   ├── routes/
│   │   ├── auth.py         # Login, registration, /me status, Google OAuth 2.0 flow
│   │   ├── chat.py         # Intent-routed RAG query engine & streaming responses
│   │   ├── ingest.py       # Repository cloning, chunking, and vector indexing
│   │   └── repos.py        # System health checks and pre-indexed repos catalogue
│   ├── config.py           # App settings, prompts, rate-limit constants, logger setup
│   ├── database.py         # MongoDB, Qdrant, Google Gemini, and Groq clients
│   ├── main.py             # FastAPI entrypoint, CORS middleware & lifespan verification
│   ├── models.py           # Pydantic schema definitions
│   ├── requirements.txt    # Python dependencies
│   └── runtime.txt         # Target Python runtime version
├── frontend/
│   ├── index.html          # Landing page with interactive terminal demo
│   ├── analyze.html        # Repository ingestion & discovery workspace
│   ├── chat.html           # Core AI codebase chat workspace
│   ├── login.html          # User authentication login portal
│   ├── signup.html         # User registration portal
│   ├── privacy.html        # Privacy policy
│   ├── terms.html          # Terms of service
│   └── static_files/       # Modular stylesheets and JavaScript controllers
│       ├── index.css / index.js
│       ├── analyze.css / analyze.js
│       ├── chat.css / chat.js
│       ├── login.css / login.js
│       └── signup.css / signup.js
├── Notebook/
│   └── Github_RAG.ipynb    # Interactive RAG prototyping & experimentation notebook
└── README.md

---

🚀 Getting Started

Prerequisites

• Python 3.11+
• Git installed on your system PATH
• MongoDB database (local or MongoDB Atlas)
• Qdrant Cloud vector database instance
• Groq Cloud API Key
• Google AI Studio API Key
• Google OAuth 2.0 Client Credentials (optional for Google login)

---

1. Clone the Repository

git clone https://github.com/Gyan-Ranjan-01/RepoMind.git
cd RepoMind

---

2. Configure Environment Variables

Create a .env file in the root directory:

# JWT & Security
JWT_SECRET=your_super_secret_jwt_key_here

# MongoDB Connection
MONGODB_URL=mongodb+srv://<username>:<password>@cluster.mongodb.net/?retryWrites=true&w=majority

# Qdrant Vector DB
QDRANT_URL=https://your-cluster.qdrant.tech:6333
QDRANT_API_KEY=your_qdrant_api_key

# Google AI Studio (Embeddings)
GEMINI_API_KEY=your_gemini_api_key

# Groq Cloud (LLM Inference)
GROQ_API_KEY=your_groq_api_key

# Google OAuth 2.0 (Optional)
GOOGLE_CLIENT_ID=your_google_client_id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your_google_client_secret

# Network URLs
FRONTEND_URL=http://localhost:5500
BACKEND_URL=http://localhost:8000

---

3. Backend Setup

# Navigate to backend directory
cd backend

# Create and activate a virtual environment
python -m venv venv

# On Windows:
.\venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Start the FastAPI development server
uvicorn main:app --host 0.0.0.0 --port 8000 --reload

Backend will be accessible at: http://localhost:8000 (API documentation at http://localhost:8000/docs).

---

4. Frontend Setup

You can serve the frontend with any static web server (such as VSCode Live Server, Python HTTP server, or Nginx):

# Navigate to frontend folder
cd ../frontend

# Example with Python's built-in HTTP server:
python -m http.server 5500

Open your browser at http://localhost:5500.

---

📡 API Endpoints

🔐 Authentication (/auth)

Method	Endpoint	Description	Auth Required
POST	/auth/register	Create a new user account with email/password	No
POST	/auth/login	Authenticate user and receive JWT token	No
GET	/auth/me	Fetch authenticated user info and daily quotas	Yes (Bearer)
GET	/auth/google	Initiate Google OAuth 2.0 redirect	No
GET	/auth/google/callback	Google OAuth callback handler	No

📥 Ingestion (/ingest)

Method	Endpoint	Description	Auth Required
POST	/ingest	Clone, parse, chunk, and embed a GitHub repository	Yes (for new repos)

Sample Ingest Payload:

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

💬 Chat (/chat)

Method	Endpoint	Description	Auth Required
POST	/chat	Query the repository with real-time text streaming	Optional

Sample Chat Payload:

{
  "repo_url": "https://github.com/pallets/flask",
  "question": "How does Flask handle routing and URL dispatching?"
}

📊 Repositories & System

Method	Endpoint	Description
GET	/repos	List all indexed repositories and chunk counts
GET	/health	Server status and uptime monitor

---

📑 Supported File Types

RepoMind inspects codebase files across modern ecosystems:

Extension	Language	Splitter Strategy
.py	Python	AST Language Splitter
.js, .jsx	JavaScript / React	JavaScript AST Splitter
.ts, .tsx	TypeScript / React	TypeScript AST Splitter
.cpp, .h	C / C++	C++ AST Splitter
.java	Java	Java AST Splitter
.md	Markdown	Character Recursive Splitter

---

🛡️ Context-Grounded Prompting Strategy

RepoMind uses prompt design techniques to align LLM output with retrieved source context:

1. Context-Only Grounding: Instructs the model to treat retrieved snippets as the primary source of truth.
2. Inline Citations: Encourages referencing source file names (e.g., (helpers/rag.py)) alongside explanations.
3. Structured Breakdown: Guides broader architecture questions through clear sections:
   • Purpose
   • Technologies
   • Key Components
   • Data Flow
   • External Services
   • Notable Patterns
4. Visibility Feedback: Instructs the model to note when specific workflows or files aren't present in the retrieved snippets rather than guessing.

---

🤝 Contributing

Contributions, issues, and feature requests are welcome!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request