AI Knowledge Search Platform

Overview

This project is a full-stack AI-powered document search system that implements a Retrieval-Augmented Generation (RAG) pipeline using NestJS, PostgreSQL (pgvector), and React.

It allows users to upload documents, perform semantic search using vector similarity, and generate grounded answers with source citations.

The system is fully containerized and runs locally using Docker Compose.

Features

• Upload and process .txt, .md, and .pdf documents
• Automatic text chunking with overlap for retrieval quality
• Vector embeddings and cosine similarity search with pgvector
• Grounded LLM answers with source citations
• React frontend for upload, querying, and source inspection
• Local-first Docker Compose setup for reproducible runs

Architecture

The system follows a modular pipeline:

1. Document Upload -> Extract text (PDF/TXT/MD)
2. Chunking -> Split text into overlapping segments
3. Embeddings -> Convert chunks into vector representations
4. Storage -> Store embeddings in PostgreSQL (pgvector)
5. Query -> Embed user query
6. Retrieval -> Perform cosine similarity search (top-k chunks)
7. Generation -> Use retrieved context to generate grounded LLM response
8. Response -> Return answer with source citations

User -> API -> Ingestion -> DB (pgvector)
                     v
                  Query
                     v
                Retrieval
                     v
                   LLM
                     v
                 Response

Services

• frontend (React + Vite)
• backend (NestJS)
• postgres (PostgreSQL + pgvector)

Quick Start

1. Copy env files:

cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env

2. Set OPENAI_API_KEY in backend/.env.

3. Run:

docker compose up --build

Frontend: http://localhost:5173
Backend: http://localhost:3000

API / Usage

API Endpoints

• POST /documents/upload
• GET /documents
• GET /documents/:id
• POST /chat/query
• POST /demo/seed

Example POST /chat/query response

{
  "answer": "...",
  "sources": [
    {
      "documentId": "uuid",
      "chunkId": "uuid",
      "excerpt": "...",
      "filename": "...",
      "title": "...",
      "chunkIndex": 0,
      "score": 0.88
    }
  ]
}

Environment Variables

Backend (backend/.env):

• PORT
• DB_HOST
• DB_PORT
• DB_USER
• DB_PASSWORD
• DB_NAME
• OPENAI_API_KEY
• OPENAI_BASE_URL (optional)
• EMBEDDINGS_MODEL
• CHAT_MODEL
• EMBEDDING_DIMENSION

Frontend (frontend/.env):

• VITE_API_BASE_URL

Database Notes

• CREATE EXTENSION IF NOT EXISTS vector;
• CREATE EXTENSION IF NOT EXISTS pgcrypto;
• tables: documents, chunks, query_logs
• vector column: chunks.embedding VECTOR(1536)
• vector index: ivfflat (vector_cosine_ops)

Demo Data Safety

Demo documents are generic and portfolio-safe:

1. berlin-public-transport-guide.md
2. remote-work-policy.txt
3. ai-ethics-overview.md

Example Query

Question: What is the difference between U-Bahn and S-Bahn?

Answer: U-Bahn is mainly metro-style urban rail, while S-Bahn connects city center with outer districts and regional links.

Sources:

• berlin-public-transport-guide.md
• similarity score: ~0.75

Engineering Decisions

• Used PostgreSQL + pgvector to simplify architecture and avoid external vector database dependencies
• Chose NestJS for modular backend structure and maintainability
• Implemented character-based chunking for simplicity and fast iteration
• Used raw SQL for vector similarity search to maintain control over retrieval logic
• Designed system to be fully local and reproducible using Docker Compose

Limitations

• Synchronous ingestion (not suitable for large-scale workloads)
• Basic top-k retrieval without reranking
• Character-based chunking instead of token-aware splitting
• No authentication or multi-user support

Future Improvements

• Background jobs with retry handling for ingestion
• Hybrid retrieval (keyword + vector)
• Better citation formatting and confidence hints
• Pagination and filtering for larger corpora
• Integration and end-to-end test coverage

Verification Checklist

• docker compose up --build starts all services
• GET /documents returns ready documents
• Uploading .txt, .md, .pdf works
• POST /chat/query returns grounded answer + sources
• Unsupported file types are rejected cleanly