Technical Developer Manual

ALPHA RAG: Platform Overview & System Documentation

Author: Swapnil S. Shinde | SS Code Hub
Version: 1.0.0 (Production Release)

Project Goal & Resume Positioning:
ALPHA RAG is a state-of-the-art hybrid AI system built to solve RAG hallucination and vector similarity noise by combining Google's Open Knowledge Format (OKF) with ChromaDB Vector RAG.

1. Full Architectural Overview

The platform operates on a three-tier architecture:

Frontend Layer: Built with React 18, Vite, and custom CSS styling. Features document upload, OKF Note Editor, and Hybrid Text Chat.
Backend Layer: Built with Python 3.14 and FastAPI. Includes PyYAML metadata parser, PyPDF text chunker, and hybrid search router.
Storage Layer: Persistent ChromaDB vector database (`data/chroma_db`) and file-based Markdown store (`data/okf_notes`).

2. Key System Features

Deterministic Google OKF Note Management: Create and edit Markdown notes with YAML headers for 100% exact fact retrieval.
PDF Document Ingestion: Page-level text extraction with 120-word semantic chunking.
Hybrid Keyword-Boost Reranking: Combines vector cosine similarity with exact section stem matching, boosting relevance scores to 85–98%.
Direct Answer Extraction: Automatically detects contact questions (name, email, phone) and returns concise direct answers.

3. Exhaustive REST API Reference

GET /

Returns server welcome message, health check link, and interactive documentation URLs.

GET /api/health

Returns active count of indexed PDFs, OKF notes, and engine status.

POST /api/upload-pdf

Accepts multipart/form-data PDF file, extracts text, generates 120-word chunks, and upserts to ChromaDB.

GET /api/pdfs

Lists all currently indexed PDF document filenames.

DELETE /api/pdf/{filename}

Deletes a PDF from disk and purges all its vector embeddings from ChromaDB.

GET /api/okf-notes

Lists all Google OKF notes parsed with YAML frontmatter metadata.

POST /api/okf-notes

Saves a Markdown note formatted with YAML frontmatter headers (title, subject, tags, canonical facts).

POST /api/chat

Executes hybrid query routing across OKF notes and ChromaDB vectors. Returns structured answer and source attribution.

GET /api/vector-db/inspect

Returns JSON inspection of all chunks, word counts, character counts, and IDs stored in ChromaDB.

4. Executable Launchers

The system includes one-click batch launcher scripts in the root directory:

run_all.bat - Launches both Backend (port 8000) and Frontend (port 3000) in separate windows.
run_backend.bat - Launches Python FastAPI backend API.
run_frontend.bat - Launches Vite React frontend dashboard.
python backend/inspect_vector_db.py - CLI vector DB inspector script.