Simple RAG System (Full‑Stack)

A minimal, production‑style Retrieval Augmented Generation (RAG) application. Users can upload a document (PDF, TXT, Markdown) and ask questions about its content through a chat interface.

The project focuses on correctness, clarity, and real‑world engineering practices rather than UI polish or experimental optimizations.

---

Features

• Document upload (PDF, TXT, Markdown)
• Text chunking and embedding
• Vector storage using PostgreSQL + pgvector
• Semantic retrieval of relevant chunks
• Question answering using Gemini (free tier)
• Simple chat‑style frontend

---

Tech Stack

Backend

• Python
• FastAPI
• SQLAlchemy (async)
• PostgreSQL + pgvector
• asyncpg
• Gemini (google‑genai SDK)

Frontend

• React (Vite)
• Fetch API
• Plain CSS

---

Project Structure

rag-app/
├── backend/
│   ├── app/
│   │   ├── api/            # Route definitions
│   │   ├── core/           # DB and config
│   │   ├── models/         # ORM models
│   │   ├── services/       # Chunking, embeddings, retrieval, LLM
│   │   └── main.py         # FastAPI app entry
│   └── requirements.txt
│
├── frontend/
│   ├── src/
│   │   ├── api/            # Backend API calls
│   │   ├── components/     # UI components
│   │   └── styles.css
│   └── package.json
│
└── README.md

---

Prerequisites

• Python 3.10+
• Node.js 18+
• PostgreSQL 14+
• pgvector extension enabled
• Gemini API key (free tier)

---

Backend Setup

1. Create virtual environment

cd backend
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

2. Install dependencies

pip install -r requirements.txt

3. Configure environment variables

Create a .env file or export variables:

DATABASE_URL=postgresql+asyncpg://user:password@localhost:5432/rag_db
GEMINI_API_KEY=your_api_key_here

Ensure pgvector is enabled:

CREATE EXTENSION IF NOT EXISTS vector;

4. Run backend

uvicorn app.main:app --reload

Backend runs at: http://localhost:8000

---

Frontend Setup

1. Install dependencies

cd frontend
npm install

2. Run frontend

npm run dev

Frontend runs at: http://localhost:5173

---

Usage

1. Open the frontend in the browser
2. Upload a PDF, TXT, or Markdown file
3. Ask questions related to the document
4. The system retrieves relevant content and generates an answer

---

Architecture Overview

Document Flow

1. File uploaded via frontend
2. Backend extracts text (PDF parser or raw text)
3. Text is split into chunks
4. Each chunk is embedded using Gemini embeddings
5. Embeddings are stored in PostgreSQL (pgvector)

Query Flow

1. User asks a question
2. Question is embedded
3. Vector similarity search retrieves relevant chunks
4. Retrieved text is sent as context to the LLM
5. LLM generates a grounded answer

---

Key Design Decisions

• Async SQLAlchemy + asyncpg: avoids blocking I/O and aligns with FastAPI’s async model
• pgvector: simple, production‑ready vector storage without extra infrastructure
• Simple chunking: predictable behavior, easy to reason about
• No chat history storage: keeps scope aligned with assessment requirements
• Minimal frontend: focuses on usability and clarity, not visual polish

The optional “Accuracy and Performance Considerations” section from the assessment was intentionally not implemented.

---

Notes

• CORS is enabled for local development
• No paid APIs or proprietary services are used

---

License

This project is provided for assessment and educational purposes.