🛡️ SentinelRAG

AI-Powered Document Intelligence Platform

Enterprise-grade Retrieval-Augmented Generation (RAG) system built with FastAPI, Next.js, LangChain, ChromaDB & Google Gemini

📖 Table of Contents

• About SentinelRAG
• Motivation
• Key Features
• System Architecture
• How It Works — The RAG Pipeline
• Technology Stack
• Project Structure
• Getting Started
• API Reference

---

📚 About SentinelRAG

SentinelRAG is a modern Retrieval-Augmented Generation (RAG) platform that lets users upload PDF documents and interact with them using natural language.

Instead of relying solely on the knowledge baked into a Large Language Model (LLM), SentinelRAG retrieves the most relevant chunks of your documents from a vector database before generating a response — significantly reducing hallucinations and producing context-aware, source-grounded answers.

The system combines document processing, semantic search, vector embeddings, and modern LLMs into a single full-stack application, with a clean separation between the frontend, backend, AI services, retrieval pipeline, and vector database.

---

🎯 Motivation

LLMs are incredibly powerful, but they come with real limitations:

• 📅 Limited knowledge after their training cutoff
• 🔒 No access to private or proprietary documents
• 🤯 A tendency to hallucinate when information is unavailable
• 📎 No way to cite sources

Retrieval-Augmented Generation solves this by retrieving relevant information from your documents before generating a response. SentinelRAG was built to demonstrate a production-ready implementation of that architecture.

---

✨ Key Features

Category	Highlights
📄 Document Upload	PDF upload, automatic storage, metadata extraction, secure file validation
📖 PDF Processing	Text extraction, page metadata preservation, character counting, error handling
✂️ Intelligent Chunking	Recursive text splitting with configurable size & overlap for optimal retrieval
🧠 Embeddings	Sentence Transformers (all-MiniLM-L6-v2), 384-dim normalized vectors, CPU-optimized
🗄️ Vector Database	ChromaDB with persistent storage, semantic search, and metadata support
🔍 Semantic Retrieval	Top-K similarity search with source tracking and metadata preservation
🤖 Multi-LLM Support	Gemini 2.5 Flash, Gemma, Qwen, Llama 3.3, with automatic model selection
💬 Chat Interface	Source citations, conversation history, responsive dark-themed UI

---

🏗 System Architecture

                 +----------------------+
                 |      Next.js UI      |
                 +----------+-----------+
                            |
                            v
                  FastAPI REST API
                            |
      ------------------------------------------
      |            |            |               |
      v            v            v               v
 Upload API    Chat API     Models API     Retrieval API
      |            |
      v            v
PDF Processing   RAG Service
      |            |
      v            |
 Text Chunking     |
      |            |
      v            |
  Embeddings       |
      |            |
      v            |
   ChromaDB <-------
      |
      v
Retrieved Context
      |
      v
 Google Gemini
      |
      v
 Final AI Response

---

🧠 How It Works — The RAG Pipeline

Upload PDF → Text Extraction → Chunking → Embedding Generation → Vector Storage
                                                                       │
User Question → Question Embedding → Similarity Search  ◄─────────────┘
                                            │
                                            ▼
                              Relevant Chunks Retrieved
                                            │
                                            ▼
                             Prompt Construction (Question + Context)
                                            │
                                            ▼
                                    Gemini LLM
                                            │
                                            ▼
                              AI Response + Cited Sources

Step	Description
1. Upload	User uploads a PDF through the web interface
2. Text Extraction	Backend extracts readable text while preserving page metadata
3. Chunking	Text is split into overlapping chunks to preserve context
4. Embedding	Each chunk is converted into a dense vector embedding
5. Vector Storage	Embeddings are stored in ChromaDB for similarity search
6. Question Embedding	The user's question is embedded using the same model
7. Similarity Search	ChromaDB retrieves the most semantically relevant chunks
8. Prompt Construction	Retrieved chunks + question are combined into a grounded prompt
9. LLM Response	Gemini generates an answer using the retrieved context
10. Display	The frontend shows the answer, sources, and chat history

This workflow ensures responses are grounded in your uploaded documents rather than relying solely on the LLM's internal knowledge.

---

⚙️ Technology Stack

Layer	Technologies
Frontend	Next.js 16 · React 19 · TypeScript · Tailwind CSS · Lucide React
Backend	FastAPI · Python 3.13 · Uvicorn · Pydantic
AI & RAG	LangChain · Google Gemini · HuggingFace Embeddings · Sentence Transformers · ChromaDB
Machine Learning	all-MiniLM-L6-v2 · Semantic Embeddings · Cosine Similarity Search
Dev Tools	Git · GitHub · VS Code · Postman · Swagger UI

---

📂 Project Structure

SentinelRAG/
│
├── backend/
│   ├── app/
│   │   ├── api/
│   │   │   ├── routes/
│   │   │   │   ├── chat.py
│   │   │   │   ├── upload.py
│   │   │   │   ├── models.py
│   │   │   │   └── health.py
│   │   │   └── router.py
│   │   │
│   │   ├── core/
│   │   │   ├── config.py
│   │   │   └── logging.py
│   │   │
│   │   ├── rag/
│   │   │   ├── embeddings.py
│   │   │   ├── retriever.py
│   │   │   ├── vectorstore.py
│   │   │   ├── llm.py
│   │   │   └── pipeline.py
│   │   │
│   │   ├── services/
│   │   │   ├── pdf_service.py
│   │   │   ├── upload_service.py
│   │   │   └── chat_service.py
│   │   │
│   │   ├── models/
│   │   ├── schemas/
│   │   ├── utils/
│   │   └── main.py
│   │
│   ├── chroma_db/
│   ├── uploads/
│   ├── requirements.txt
│   ├── .env.example
│   └── README.md
│
├── frontend/
│   ├── app/
│   ├── components/
│   ├── lib/
│   ├── services/
│   ├── public/
│   ├── styles/
│   ├── package.json
│   └── next.config.ts
│
├── screenshots/
├── docs/
├── .gitignore
├── LICENSE
└── README.md

The backend handles the full RAG pipeline — upload, parsing, chunking, embeddings, vector storage, retrieval, prompting, and LLM calls. The frontend delivers a clean, chat-based user experience on top of it.

---

🚀 Getting Started

1. Clone the repository

git clone https://github.com/yourusername/SentinelRAG.git
cd SentinelRAG

2. Backend setup

# Run these commands from the repository root.
# Create and activate a virtual environment
python -m venv .venv

# Windows
.venv\Scripts\activate

# Linux / macOS
source .venv/bin/activate

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

# Optional: install development/test dependencies
pip install -r backend/requirements-dev.txt

3. Frontend setup

cd frontend
npm install

4. Configure environment variables

Create a .env file inside the backend/ directory:

GEMINI_API_KEY=YOUR_GOOGLE_API_KEY

LLM_MODEL=gemini-2.5-flash

GROQ_API_KEY=
OPENROUTER_API_KEY=

CHROMA_PERSIST_PATH=./data/vectorstore
TOP_K_RETRIEVAL=5
CHUNK_SIZE=500
CHUNK_OVERLAP=50

⚠️ Never commit your .env file. Keep API keys secure and use .env.example as a template.

Variable	Description
LLM_MODEL	Default Gemini model name
GEMINI_API_KEY	API key for Gemini
GROQ_API_KEY	Optional Groq API key
OPENROUTER_API_KEY	Optional OpenRouter API key
CORS_ORIGINS	Comma-separated browser origins allowed to call the API
CHUNK_SIZE	Size of text chunks
CHUNK_OVERLAP	Overlap between chunks
TOP_K_RETRIEVAL	Number of chunks retrieved per query
CHROMA_PERSIST_PATH	Persistent vector database location

5. Run the backend

uvicorn backend.app.main:app --reload

Run this command from the repository root. This matches the absolute backend.app.* imports used by the application.

• API: http://127.0.0.1:8000
• Swagger docs: http://127.0.0.1:8000/docs
• ReDoc: http://127.0.0.1:8000/redoc

6. Run the frontend

cd frontend
npm run dev

• App: http://localhost:3000

7. Run checks

From the repository root:

python -m compileall -q backend
python -m pytest -q
cd frontend
npm run lint
npm run build

8. Run with Docker Compose

From the repository root, create backend/.env using backend/.env.example, add at least one provider API key, and start both services:

docker compose up --build

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000
• Swagger docs: http://localhost:8000/docs

Uploaded PDFs and the Chroma vector store persist in the repository's data/ directory. To point the containerized frontend at a different API URL, set NEXT_PUBLIC_API_URL before starting Compose, for example:

NEXT_PUBLIC_API_URL=http://localhost:8000/api/v1 docker compose up --build

On PowerShell, use $env:NEXT_PUBLIC_API_URL = "http://localhost:8000/api/v1" before running docker compose up --build. For a deployed frontend, set CORS_ORIGINS in backend/.env to its exact origin, such as https://app.example.com.

Compose waits for the backend healthcheck at /api/v1/health before starting the frontend. After deployment, verify that endpoint and review docker compose ps before directing traffic to the frontend.

For Render Docker deployment, leave the repository root as the root directory and set the Dockerfile path to backend/Dockerfile. The backend automatically uses Render's PORT environment variable; the local Docker default remains port 8000.

Try it out

1. Open the frontend in your browser.
2. Upload a PDF document and wait for indexing to complete.
3. Ask a question related to the document.
4. Confirm the response references the correct source content.

You can also explore the API independently via Swagger UI.

---

📡 API Reference

Base URL: http://localhost:8000/api/v1

Health Check

GET /health

{
  "status": "healthy",
  "service": "SentinelRAG API",
  "version": "1.0.0"
}

Upload Document

POST /upload · multipart/form-data

Parameter	Type
file	PDF

{
  "message": "Document uploaded successfully",
  "document_id": "server-generated-id",
  "filename": "sample.pdf",
  "chunks_created": 58
}

Chat

POST /chat

Request

{ "question": "Summarize this document.", "document_id": "server-generated-id", "model_id": "auto" }

Response

{
  "answer": "...",
  "sources": [
    { "page": 3, "content": "Relevant retrieved chunk..." }
  ]
}

Available Models

GET /models

{ "models": ["gemini-2.5-flash", "gemma", "qwen", "llama"] }

---

⚡ Performance & Security

Performance optimizations

• Recursive text chunking with configurable overlap
• Persistent, cached ChromaDB storage
• Fast, CPU-optimized embedding generation
• Context-aware prompt construction
• Modular, scalable service architecture

Security — currently in place

• PDF & file type validation
• Environment variable management and API key isolation
• Safe file uploads and error handling

Security — recommended for production

• Authentication (JWT / OAuth)
• HTTPS enforcement and rate limiting
• Request validation, logging & monitoring
• User management and role-based access control (RBAC)

---

🗺️ Roadmap

Phase	Status	Focus
1	✅ Done	Project setup, FastAPI backend, Next.js frontend, PDF upload, ChromaDB integration
2	✅ Done	Embedding generation, semantic retrieval, Gemini integration, chat interface, source citations
3	🚧 In Progress	Multi-document support, streaming responses, authentication, conversation history
4	🔮 Planned	Cloud deployment, Docker & Kubernetes, CI/CD, monitoring, performance tuning

Other planned enhancements: DOCX/TXT ingestion, image & OCR support, hybrid search (BM25 + vector), metadata filtering, multi-user support, model switching from the UI, citation highlighting, AI-generated summaries, exportable chat history, and an admin/analytics dashboard.

---

📸 Screenshots

Add screenshots to the screenshots/ folder and reference them below.

## Home Page
![Home](screenshots/home.png)

## Upload
![Upload](screenshots/upload.png)

## Chat
![Chat](screenshots/chat.png)

---

🤝 Contributing

Contributions are welcome!

1. Fork the repository
2. Create a feature branch

   git checkout -b feature/new-feature

3. Commit your changes

   git commit -m "Add new feature"

4. Push to your branch

   git push origin feature/new-feature

5. Open a Pull Request

Please make sure your code follows the project's style and includes appropriate documentation.

---

📜 License

This project is licensed under the MIT License — you're free to use, modify, distribute, and fork it under those terms.

---

👨‍💻 Author

Yashraj Vilas Agawane Final Year B.Tech Information Technology Student · Full Stack Developer · AI/ML Enthusiast

• GitHub: github.com/yashrajagawane
• LinkedIn: linkedin.com/in/yashrajagawane

🙏 Acknowledgements

Thanks to the open-source community and the creators of FastAPI, Next.js, React, LangChain, ChromaDB, Hugging Face, Google Gemini, Sentence Transformers, Tailwind CSS, TypeScript, and Python — the technologies that power SentinelRAG.

⭐ If you found this project helpful, consider giving it a star!

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