Skip to content

10. Interview Prep Guide

2-minute architecture script

Browser RAG is a fully client-side RAG app. Users create a project pinned to an embedding model, upload documents, and we extract and chunk text in a Web Worker, embed with Transformers.js in a second worker, and store chunks plus pgvector embeddings in PGlite on IndexedDB. At ask time we optionally rewrite follow-ups into a standalone search query, run hybrid vector and keyword search, fuse with RRF, then stream an answer from a local LLM — WebLLM, Transformers.js, or bundled Gemma/LFM kernels — with citations and a retrieval debug panel. There is no application server; GitHub Pages hosts the static build.

5-minute architecture script

Start with the privacy constraint from AGENTS.md: every library must run in the browser. That forces three design choices: a WASM database (PGlite + pgvector), on-device embeddings, and on-device generation.

Indexing: upload saves original bytes in a dedicated IndexedDB for retries. An indexing worker runs extractors — including @llamaindex/liteparse-wasm for PDFs — then chunkText with heading/page metadata. The main thread loads the project’s embedding model, applies query/passage prefixes when required (E5/BGE), embeds in the embedding worker, and transactionally replaces chunk rows.

Retrieval: embed the (possibly rewritten) query; fetch top vector hits by cosine distance; if hybrid is enabled, run English FTS with OR terms and ts_rank; fuse with RRF (k=60); return top-K from project settings.

Generation: build a sourced context block, stream through a unified LLM adapter with thinking enabled and tools disabled, and surface debug timings in the UI.

Ops: Vite sets COOP/COEP for cross-origin isolation in dev/preview; CI builds and deploys dist to gh-pages under /browser-rag/.

Likely system design questions

Question Answer sketch
Why not a server RAG API? Privacy, zero infra, demo portability; trade device limits
How would you scale to 1M chunks? Add ANN index or shard; or move vector search to a worker/WASM ANN; may need server
Why RRF over weighted score mix? Avoid calibrating incompatible score scales
How do you handle multi-turn? Rewrite for search; keep history for answer

Likely backend questions

  • PGlite singleton + migration versioning
  • Why delete-then-insert chunks on retry
  • OR tsquery rewrite rationale
  • Unused tables (collections, index_jobs, model_cache)

Likely frontend questions

  • SystemInitProvider as composition root for four engines
  • TanStack Router basepath for Pages
  • Streaming UI event mapping
  • Prefs default id mismatch as a known footgun

Likely infra / security questions

  • COOP/COEP purpose and Pages gap
  • XSS via marked + dangerouslySetInnerHTML
  • Weight download vs document privacy
  • Backup omitting browser-rag-files

Likely data / agent questions

  • Not a tool agent — RAG orchestrator with stubbed tools
  • Embedding model as project invariant
  • OCR flagged but not implemented
  • Chunk settings labeled “Characters” vs token estimates

STAR stories

Hybrid retrieval debugging
Situation: keyword-heavy queries failed under vector-only search. Task: improve recall without a server. Action: add FTS with OR terms + RRF and a debug panel. Result: lexical and semantic hits visible and fused per query.

UI jank during indexing
Situation: main-thread PDF parse blocked chat. Task: keep UI responsive. Action: move extract/chunk and embeddings to workers. Result: progress callbacks without freezing React.

Multi-engine LLM
Situation: WebLLM and Transformers.js APIs differed. Task: one chat path. Action: adapter interface + shared stream events + parsers for thinking. Result: settings can switch engines without rewriting chat.

Weak spots to acknowledge

  • No automated tests
  • Tool loop is dead code
  • Soft embedding lock
  • Possible production header gap
  • Markdown XSS surface
  • Settings/chunk unit labeling mismatch

Short answers

What was hard?
Getting hybrid search and multi-engine streaming to feel like one product inside browser memory and threading constraints.

What would you improve?
Tests for RRF/chunking; sanitize Markdown; harden embedding lock + reindex; include file IDB in backups; verify Pages isolation headers; either ship tools or delete stubs.

What are you proud of?
A complete local RAG data plane — Postgres vectors, hybrid fusion, workers, and multi-engine generation — with a debug UI that makes the pipeline inspectable.