Enterprise RAG Assistant

Overview

Enterprise RAG Assistant is a portfolio MVP for knowledge retrieval where document permissions and version freshness matter. Its synthetic corpus makes the implementation safe to demonstrate publicly. The project explores retrieval and evidence controls; it is not a production-ready service or a client deployment.

Engineering Challenge

A relevant chunk is not suitable evidence if the current user is not allowed to read it or if the chunk belongs to an inactive document version. Likewise, returning a citation ID does not prove that an answer claim follows from the cited text. These boundaries need to be explicit in retrieval, document lifecycle, source resolution, and evaluation.

Architecture

The React/Vite interface calls a Spring Boot modular monolith. The backend handles demo identity and CSRF, document ingestion and version activation, retrieval, optional answer generation, citation checks, evaluations, and traces. PostgreSQL with pgvector stores document metadata and vectors. Ollama provides local embeddings; DeepSeek generation is independently optional.

The retrieval implementation combines ACL-constrained vector search, PostgreSQL full-text search, and exact-identifier search using Reciprocal Rank Fusion. A deterministic evidence gate filters weak candidates before context assembly. Document versions are staged and activated transactionally. Citation/source lookup rechecks access rather than trusting a previously issued identifier.

React UI -> Spring Boot API -> identity and request controls
                         -> ingestion -> staged versions -> PostgreSQL / pgvector
                         -> ACL-filtered vector + full-text + exact retrieval
                            -> rank fusion -> evidence gate -> context and citations
                         -> optional DeepSeek generation
                         -> offline evaluation, traces, and metrics
Ollama provides local embeddings for ingestion and query retrieval.

Key Design Decisions

1. Authorize candidate retrieval in SQL. Permissions and active-version state are applied before candidates leave vector, full-text, or exact-match retrieval paths.
2. Fuse by rank, not raw score. Vector distance, lexical rank, and exact matching use different score scales; Reciprocal Rank Fusion combines rankings without pretending those values are directly comparable.
3. Stage then activate versions. Indexing a new version does not immediately replace the old one. Activation occurs only after indexing succeeds.
4. Treat citations as references, not proof. Source IDs are validated and reauthorized. The implementation explicitly does not claim citation-level entailment or generated-answer faithfulness.
5. Keep offline evaluation bounded. The deterministic suite evaluates retrieval, ACL isolation, freshness, citation-ID validation, and evidence sufficiency; it does not call an LLM to grade answer correctness.

Implementation and Verification

The repository includes Markdown/text/extractable-PDF ingestion, synthetic documents, role-scoped retrieval, document management, chat/source APIs, evaluation runs, trace APIs, and React workspaces. Three screenshots are available in the repository and shown below. The latest visible GitHub Actions quality workflow for the inspected main commit succeeded. The README documents backend integration tests, frontend tests/build, and Playwright browser workflows; that repository evidence is distinct from a fresh local test of this portfolio site.

Limitations and Further Work

The corpus is synthetic. Demo identities are not a real authentication system, and the SQL-based ACL approach is not PostgreSQL row-level security. The deterministic evidence thresholds are heuristic and calibrated for a small synthetic corpus. Citation validity does not establish claim entailment, and offline retrieval evaluation does not measure generated-answer correctness. Scanned PDF OCR, enterprise identity integration, distributed ingestion, and a live generated-answer benchmark are outside the current implementation.

Source

• GitHub repository
• README and setup instructions
• Architecture documentation
• Portfolio case-study notes