Case study · Personal project · 2026 to Present

Knowra

A RAG platform that answers from your organisation's documents, backed by citations, and restricted strictly to what you're allowed to see.

View the code ↗ Jump to architecture ↓

Role: Sole architect and engineer
Stack: FastAPI, React/TypeScript, PostgreSQL
Retrieval: FAISS + BM25, RRF, cross-encoder
LLMs: Groq, OpenAI, Gemini, Ollama

knowra.platform · Interactive Media Tour

            Slide 1 of 5
          

Clip:

Knowra Chat Interface with Source Citations

Knowra Document Management & Collection Access

Knowra Knowledge Base Dashboard and Telemetry

Knowra Security Administration and Role Permissions

1080p 60fps Trailer

Knowra Official Showcase Trailer

Comprehensive walkthrough demonstrating cited QA, permission enforcement, and passage highlight exploration.

Results

What testing showed.

7–8 / 10

Test questions answered from the correct source document

Top 5

Where the right source consistently ranks in retrieval

~20%

Fewer hallucinated answers after cross-encoder re-ranking, with answer quality up ~15–20%

0 / 200+

Restricted-document leaks across permission test cases

2–5 s

Typical answer time; 2–3 s for direct questions

Measured on internal test sets during development.

The Problem

The answer exists. Nobody can find it.

Every company has the same productivity leak: the answer to "what's our remote work policy?" is already written down, buried in a PDF on a shared drive or in the head of whoever answered it last.

So people ask a colleague, again. Or they ask a general chatbot, which answers confidently without ever having read the handbook. In an enterprise there's a second problem: a naive RAG system will happily retrieve a document the person asking was never allowed to see.

What It Does

Ask in plain English. Get an answer you can check.

Cited answers

Each claim links to the exact source page, with the passage highlighted.

Permission-aware

Admins decide which roles can see which documents. Access is enforced before retrieval, and no authorised source means no claim.

Any document

Multi-format ingestion with structure extraction and duplicate detection.

Admin tooling

Manage collections, users and roles from one console.

Architecture

From a document to a cited answer.

Dual-pipeline system: Offline Ingestion & Indexing + Online Fail-Closed Retrieval.

A Offline Ingestion & Security Indexing Flow

Background ETL Pipeline · Asynchronous

📄 Raw Documents

Step 1 · Dedupe Gate

Parse & Checksum

PDF, DOCX, TXT. SHA-256 hash skips unchanged files.

Step 2 · Segmentation

Semantic Chunking

Splits along clause & heading boundaries (512 tokens).

Step 3 · Dual Store

FAISS + BM25 Indices

Dense vector embeddings + Sparse keyword terms.

Step 4 · Security Tag

Fail-Closed RBAC ACL

Attaches user-role access permissions to chunks.

💾 Index Ready

B Online Query & Fail-Closed Retrieval Flow

Synchronous Query Path · 2–5s Latency

💬 User Question

Step 1 · Classifier

Intent Router

Routes chat & greetings in ~60ms without search.

Step 2 · Security Gate

Pre-Retrieval RBAC

Resolves JWT role against document ACLs.

✓ Allowed → Hybrid Search ✗ Restricted → Safe Refusal

Step 3 · Hybrid Search

Parallel Retrieval

FAISS vector similarity + BM25 keyword matching.

Step 4 · Fusion

RRF Merge

Reciprocal Rank Fusion outputs Top 30 candidates.

Step 5 · Cross-Encoder

Neural Re-Ranker

Re-scores candidate pairs to extract Top 5 chunks.

Step 6 · LLM Synthesis

Grounded Engine

Writes answer strictly from verified passages.

✅ Cited Answer

A Offline Ingestion & Security Indexing Specifications

3 Pipeline Stages · Background ETL

01 Multi-Format Ingestion

Parse & Dedupe

Parses PDF, DOCX, TXT documents with structure extraction and cryptographic deduplication.

Engineering Rationale Re-uploading folders costs zero compute because SHA-256 checksums identify and skip untouched files.

Input / Output Boundary Raw PDF/DOCX/TXT files → Normalized text blocks with metadata headers.

Safeguard / Metric 100% duplicate suppression; zero wasted embedding calls.

02 Semantic Chunking

Structure-Aware

Splits at clause, heading, and table boundaries rather than arbitrary token cuts.

Engineering Rationale Fixed token windows slice definitions in half. Preserving clause boundaries ensures full context per chunk.

Input / Output Boundary Parsed document trees → 512-token semantic chunks with heading context.

Safeguard / Metric Preserves clause integrity; zero split definitions across chunks.

03 Hybrid Indexing & RBAC

Dual Store + ACL

Builds dense vector indices in FAISS and sparse inverted indices in BM25 with role access controls.

Engineering Rationale Vectors capture conceptual meaning while BM25 preserves exact product codes, IDs, and acronyms.

Input / Output Boundary Semantic chunks → FAISS HNSW index + BM25 index + Role ACL tags.

Safeguard / Metric Fail-closed ACL tagging bound at the index partition layer.

B Online Query & Fail-Closed Retrieval Specifications

5 Pipeline Stages · 2–5s Latency

04 Query Intent Router

Fast Classifier

Classifies queries before retrieval: answers small talk directly and applies ingress guardrails.

Engineering Rationale Chit-chat does not require search. Routing saves latency, compute, and keeps guardrails centralized.

Input / Output Boundary User prompt → Route decision [Document Search | Small Talk | Guardrail Block].

Safeguard / Metric Sub-60ms routing latency; protects retrieval budget.

05 Pre-Retrieval Access Filter

Security Gate

Resolves requester JWT roles and filters document IDs before any vector or keyword search runs.

Engineering Rationale Post-filtering is too late because secret text enters prompt context. Filtering upfront prevents leakage.

Input / Output Boundary Requester JWT + Query → Whitelisted document ID partitions.

Safeguard / Metric 0 unauthorized document leaks across 200+ permission test cases.

06 Hybrid Search & RRF

Parallel Search

Runs parallel FAISS dense search and BM25 sparse search, fused via Reciprocal Rank Fusion.

Engineering Rationale Dense embeddings catch paraphrased questions while BM25 locks onto exact policy codes and names.

Input / Output Boundary Query + Allowed partition → Top 30 candidate passages ranked by RRF score.

Safeguard / Metric Consistently ranks target source in top 5 retrieval candidates.

07 Neural Cross-Encoder

Re-Ranking

Joint cross-attention re-ranks query-passage candidate pairs to prune low-relevance distractions.

Engineering Rationale Bi-encoders miss nuances. Cross-encoders examine full cross-attention, cutting irrelevant chunks.

Input / Output Boundary Top 30 RRF candidates → Top 5 high-confidence verified chunks.

Safeguard / Metric ~20% reduction in hallucinations; answer precision up ~15–20%.

08 LLM Synthesis & Citations

Synthesis Engine

Provider-agnostic LLM generates concise answers where every statement binds to verified citation badges.

Engineering Rationale Every answer cites its exact page. If no authorized source exists, it refuses to guess.

Input / Output Boundary Top 5 chunks + user prompt → Grounded answer with clickable citation badges.

Safeguard / Metric No authorized source = refusal to invent; 100% citation traceability.

Engineering Decisions

The calls that shaped it.

Filter before retrieval, not after

Post-filtering generated answers is too late: the restricted text has already been in the prompt. Resolving access first, and failing closed when it can't be resolved, makes leaks structurally impossible rather than unlikely.

Hybrid over pure vector search

Company documents are full of acronyms, product codes and policy numbers. Dense vectors handle paraphrase; BM25 handles the exact terms. RRF combines both without hand-tuned weights.

Route before you retrieve

Not every message needs a search. Classifying intent first saves latency and tokens on small talk and product-help questions, and gives one clear place to enforce guardrails.

Provider-agnostic LLM layer

One interface over Groq, OpenAI, Gemini and Ollama, so the model can be swapped for cost, latency or data-residency reasons without touching retrieval.

Production Readiness

Built to run, not to demo.

Auth & access

JWT auth, RBAC across 4 roles, rate limiting.
Containers

Docker Compose, non-root images, health checks.
Data

PostgreSQL with Alembic migrations; incremental index updates.
Tests

PyTest on the backend plus frontend test suites.

Need a knowledge assistant your team can trust?

Email me Next: Document Intelligence →