ijahangirabbas/chaibook-llm

Purpose and entry points

ChaiBook is a multi-tenant RAG research-notebook platform: users organize sources into notebooks, asynchronously index content, then ask grounded questions with streamed cited answers. The backend runs an Express API and/or independent worker via backend/src/server.ts, backend/src/app.ts, and backend/src/worker.ts. The browser client is a Vite/React SPA entered through frontend/src/main.tsx and routed in frontend/src/app/router.tsx.

API boundary, identity, and tenancy

Versioned REST/SSE endpoints are assembled under backend/src/routes/v1/index.ts; controllers expose notebook, source, search, chunk, chat, and user operations in backend/src/controllers/. Clerk JWT verification and workspace-scoped authorization are enforced before business operations through backend/src/middlewares/auth.middleware.ts and backend/src/lib/clerk.auth.ts. Request middleware also provides idempotency, rate limits, context/logging, metrics, uploads, and SSE response handling under backend/src/middlewares/.

Relational system of record

PostgreSQL, accessed through Prisma, holds workspace/notebook/source/chunk/conversation metadata, statuses, quotas, and persisted generation/citation records. The schema and client boundary are backend/prisma/schema.prisma, backend/src/db/prisma.client.ts, and repository implementations in backend/src/repositories/. Repositories/services must preserve workspace isolation and soft-deletion semantics; Qdrant is a retrieval index rather than the relational authority.

Source ingestion pipeline

Source creation accepts uploaded files or remote content, stores raw file material in S3-compatible storage, creates source metadata, and enqueues deferred indexing. Key orchestration is backend/src/services/source.service.ts, backend/src/services/s3.service.ts, and backend/src/queue/ingestion.queue.ts. The worker consumes BullMQ/Redis jobs, updates lifecycle status, selects a loader for PDF/text/web/YouTube/captions, chunks extracted content, embeds it, persists chunks, and indexes vectors. Loader polymorphism is centered on backend/src/loaders/base.loader.ts, backend/src/loaders/loader.factory.ts, and backend/src/loaders/pdf.loader.ts.

Vector retrieval and RAG generation

backend/src/services/rag.service.ts drives notebook chat: embed the question, retrieve tenant/notebook-filtered Qdrant candidates, rerank/diversify them, construct untrusted source-bounded context, and stream LLM output plus citations. Vector abstraction isolates Qdrant behind backend/src/vectorstore/base.vectorstore.ts, backend/src/vectorstore/qdrant.store.ts, and backend/src/services/vector.service.ts; reranking is isolated in backend/src/services/rerank.service.ts. The chat controller and SSE middleware form the HTTP streaming boundary: backend/src/controllers/chat.controller.ts and backend/src/middlewares/sse.middleware.ts.

Frontend interaction model

The React client contains notebook/source management, search, and chat views, with application shell/auth layouts in frontend/src/app/layouts/AppLayout.tsx and frontend/src/app/layouts/AuthLayout.tsx. Primary user workflows reside in frontend/src/app/pages/Notebook/NotebookPage.tsx, frontend/src/app/pages/Sources/SourcesPage.tsx, and frontend/src/app/pages/Chat/ChatPage.tsx. frontend/src/services/api.service.ts is the backend transport boundary; frontend/src/store/useAppStore.ts holds shared client state. Chat UI supports streamed messages and source citations via frontend/src/components/Chat/VirtualMessageList.tsx and frontend/src/components/MessageBubble/CitationButton.tsx.

Runtime and external infrastructure

Backend requires Node/TypeScript, PostgreSQL, Redis/BullMQ, Qdrant, and S3-compatible object storage. Clerk provides authentication; Jina or OpenAI provides embeddings and Jina reranking; Groq or OpenAI provides chat completion. Runtime configuration and provider/vector settings are centralized in backend/src/config/env.config.ts, backend/src/config/embeddings.config.ts, and backend/src/config/qdrant.config.ts. Process-role deployment permits API-only, worker-only, or combined instances.