Skip to content

Browser RAG — Codebase Interview Dossier

Repository: Hari31416/browser-rag
Inspected checkout: repos/browser-rag (cloned 2026-07-09)
Stack: React 19 · TypeScript · Vite · PGlite/pgvector · Transformers.js · WebLLM

Reading order

  1. Evidence Map — what was inspected and confidence levels
  2. Product & System Overview — what it does and how pieces fit
  3. Agentic AI Architecture — RAG orchestration, rewrite, multi-engine LLM
  4. Backend Deep Dive — in-browser service layer (DB, workers, RAG modules)
  5. Frontend Deep Dive — routes, UI, state
  6. Data Model & Storage — schema and persistence
  7. Infra & Local Ops — dev, build, GitHub Pages
  8. Security & Safety — privacy boundaries and gaps
  9. Testing & Quality — quality gates
  10. Unique Engineering Highlights — interview-worthy work
  11. Interview Prep — scripts and Q&A
  12. Risks & Next Steps — unknowns and hardening

Preview and export

From projects/browser-rag/:

make serve          # MkDocs live preview
make build          # Static site → site-dossier/
make consolidate    # Single Markdown file
make pdf            # PDF via md2pdf (requires install-md2pdf)

Executive summary

Browser RAG is a fully client-side Retrieval-Augmented Generation app. Document parsing, chunking, embedding, hybrid vector+keyword search with Reciprocal Rank Fusion, and LLM answer generation all run in the browser. Persistence uses PGlite (WASM Postgres) with pgvector on IndexedDB. There is no application backend; CI only builds and deploys a static site to GitHub Pages.

The distinctive engineering bet is treating the browser as a complete RAG runtime: Web Workers for indexing/embeddings, a real SQL vector store, and a multi-engine LLM adapter (WebLLM, Transformers.js, Gemma-4 and LFM2 kernels) behind one streaming API.

System map

graph TD
  classDef default fill:#1e293b,stroke:#38bdf8,stroke-width:2px,color:#f8fafc
  classDef highlight fill:#065f46,stroke:#34d399,stroke-width:2px,color:#f0fdf4
  classDef warning fill:#78350f,stroke:#fbbf24,stroke-width:2px,color:#fffbeb

  UI["React UI<br/>TanStack Router/Query"]:::highlight
  RAG["RAG Orchestrator<br/>rewrite → retrieve → answer"]
  IDX["Indexing Pipeline<br/>extract → chunk → embed"]
  RET["Hybrid Retrieval<br/>vector + keyword + RRF"]
  LLM["LLM Runtime<br/>4 engine adapters"]
  DB["PGlite + pgvector<br/>idb://browser-rag"]
  W1["indexing.worker"]
  W2["embedding.worker"]
  IDB["IndexedDB file store<br/>browser-rag-files"]
  HF["Model weights<br/>HF / MLC CDN"]:::warning

  UI --> RAG
  UI --> IDX
  RAG --> RET
  RAG --> LLM
  RET --> DB
  IDX --> W1
  IDX --> W2
  W2 --> HF
  LLM --> HF
  IDX --> DB
  IDX --> IDB

  linkStyle default stroke:#64748b,stroke-width:2px

The UI drives two pipelines: indexing (workers + embeddings into PGlite) and chat (optional query rewrite, hybrid retrieval, streamed local LLM). Model weights may download from the network; document content stays local.

Diagram index

Topic Chapter
High-level architecture 01
Ask-flow sequence 01, 02
Agent/RAG orchestration 02
ER / storage 05
Deploy topology 06

Top 10 things to know

  1. No server app — all RAG logic is TypeScript in the browser (src/rag/, src/llm/, src/db/).
  2. PGlite + pgvector persists projects, documents, chunks, and history in IndexedDB (src/db/client.ts).
  3. Hybrid retrieval fuses cosine similarity with OR-term ts_rank via RRF (src/rag/retrieval.ts).
  4. Query rewrite turns follow-ups into standalone search queries before retrieval (src/rag/orchestrator.ts).
  5. Embeddings run in a dedicated Web Worker via Transformers.js (WebGPU, q8) (src/workers/embedding.worker.ts).
  6. Parse/chunk also run off-thread (src/workers/indexing.worker.ts).
  7. Four LLM engines share one adapter API; RAG disables tools (toolsEnabled: false).
  8. Projects lock an embedding model at create time for vector consistency (UI soft-lock; schema stores embedding_model_id).
  9. COOP/COEP headers are set for Vite dev/preview to enable WASM threads; production Pages headers are unverified.
  10. No automated tests — CI is build + GitHub Pages deploy only.

Most impressive engineering work

  1. In-browser Postgres with pgvector and hybrid RRF retrieval
  2. Dual-worker indexing/embedding path that keeps the React UI responsive
  3. Unified multi-engine LLM runtime with thinking-token parsers
  4. Conversation-aware retrieval rewrite + retrieval debug panel with stage timings

Report coverage

File Focus
00-evidence-map.md Inspection scope and confidence
01-product-and-system-overview.md Product and architecture
02-agentic-ai-architecture.md RAG + LLM orchestration
03-backend-deep-dive.md Client-side service layer
04-frontend-deep-dive.md UI and routing
05-data-model-and-storage.md Schema and storage
06-infra-and-local-ops.md Dev and deploy
07-security-and-safety.md Privacy and risks
08-testing-and-quality.md Quality signals
09-unique-engineering-highlights.md Distinctive work
10-interview-prep.md Interview scripts
11-open-questions-and-risks.md Gaps and next steps

Open questions (preview)

  • Production COOP/COEP on GitHub Pages is Unknown
  • Tool-calling plumbing is stubbed (MAX_TOOL_ROUNDS = 0) — product intent unclear
  • Backup omits the separate browser-rag-files IndexedDB store
  • Settings label chunk size as “Characters” while chunkText treats values as tokens