# ijahangirabbas/chaibook-llm architecture

> Architecture diagram of the GitHub repository ijahangirabbas/chaibook-llm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ijahangirabbas/chaibook-llm
- Repository: https://github.com/ijahangirabbas/chaibook-llm

## Overview

#### 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.

Main entry points: [`backend/src/services/rag.service.ts`](https://github.com/ijahangirabbas/chaibook-llm/blob/main/backend/src/services/rag.service.ts) (RAG orchestration), [`backend/src/services/source.service.ts`](https://github.com/ijahangirabbas/chaibook-llm/blob/main/backend/src/services/source.service.ts) (Source orchestration), [`backend/src/loaders/base.loader.ts`](https://github.com/ijahangirabbas/chaibook-llm/blob/main/backend/src/loaders/base.loader.ts) (Chunk & embed), [`backend/src/middlewares/auth.middleware.ts`](https://github.com/ijahangirabbas/chaibook-llm/blob/main/backend/src/middlewares/auth.middleware.ts) (Auth & workspace guard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Browser SPA"]
  node_spa["React SPA<br/>Vite/React<br/>[main.tsx]"]
  node_client_routes["Routes &amp; layouts<br/>client routing<br/>[router.tsx]"]
  node_notebook_views["Notebook, source &amp; chat views<br/>UI workflows<br/>[NotebookPage.tsx]"]
  node_client_transport["API transport &amp; state<br/>client boundary<br/>[api.service.ts]"]
end

subgraph group_api["API Runtime"]
  node_api_runtime["Express API<br/>Node runtime<br/>[server.ts]"]
  node_v1_routes["v1 REST/SSE routes<br/>HTTP boundary<br/>[index.ts]"]
  node_auth_tenancy["Auth &amp; workspace guard<br/>middleware<br/>[auth.middleware.ts]"]
  node_controllers["Controllers<br/>API operations"]
  node_sse_chat["Streaming chat boundary<br/>SSE<br/>[chat.controller.ts]"]
  node_rag_service["RAG orchestration<br/>[rag.service.ts]"]
  node_retrieval["Vector retrieval &amp; rerank<br/>retrieval layer<br/>[vector.service.ts]"]
end

subgraph group_pipeline["Async Indexing"]
  node_source_service["Source orchestration<br/>[source.service.ts]"]
  node_ingestion_queue["Ingestion queue<br/>BullMQ queue<br/>[ingestion.queue.ts]"]
  node_worker["Indexing worker<br/>Node worker<br/>[worker.ts]"]
  node_loaders["Content loaders<br/>loader factory<br/>[loader.factory.ts]"]
  node_chunk_embed["Chunk &amp; embed<br/>indexing stage<br/>[base.loader.ts]"]
end

subgraph group_data["Data &amp; Providers"]
  node_repositories["Repositories<br/>persistence boundary"]
  node_postgres[("PostgreSQL / Prisma<br/>system of record<br/>[schema.prisma]")]
  node_redis[("Redis<br/>queue backend")]
  node_object_storage[("S3-compatible storage<br/>raw source storage<br/>[s3.service.ts]")]
  node_qdrant[("Qdrant<br/>vector index<br/>[qdrant.store.ts]")]
  node_ai_providers{{"Embedding, rerank &amp; chat providers<br/>AI providers"}}
  node_clerk{{"Clerk<br/>identity provider<br/>[clerk.auth.ts]"}}
end

node_spa -->|"boots"| node_client_routes
node_client_routes -->|"renders"| node_notebook_views
node_notebook_views -->|"uses"| node_client_transport
node_client_transport -->|"REST / SSE"| node_v1_routes
node_api_runtime -->|"mounts"| node_v1_routes
node_v1_routes -->|"guards with"| node_auth_tenancy
node_auth_tenancy -->|"verifies JWT"| node_clerk
node_auth_tenancy -->|"authorizes"| node_controllers
node_controllers -->|"creates sources"| node_source_service
node_controllers -->|"chat requests"| node_sse_chat
node_sse_chat -->|"streams"| node_rag_service
node_source_service -->|"stores raw files"| node_object_storage
node_source_service -->|"creates metadata"| node_repositories
node_source_service -->|"enqueues"| node_ingestion_queue
node_ingestion_queue -->|"uses"| node_redis
node_worker -->|"consumes"| node_ingestion_queue
node_worker -->|"extracts via"| node_loaders
node_loaders -->|"content"| node_chunk_embed
node_chunk_embed -->|"persists chunks"| node_repositories
node_chunk_embed -->|"indexes vectors"| node_qdrant
node_chunk_embed -->|"embeds"| node_ai_providers
node_repositories -->|"Prisma"| node_postgres
node_rag_service -->|"retrieves context"| node_retrieval
node_retrieval -->|"filtered search"| node_qdrant
node_retrieval -->|"reranks"| node_ai_providers
node_rag_service -->|"generates answer"| node_ai_providers
node_rag_service -->|"persists generation &amp; citations"| node_repositories

click node_spa "https://github.com/ijahangirabbas/chaibook-llm/blob/main/frontend/src/main.tsx"
click node_client_routes "https://github.com/ijahangirabbas/chaibook-llm/blob/main/frontend/src/app/router.tsx"
click node_notebook_views "https://github.com/ijahangirabbas/chaibook-llm/blob/main/frontend/src/app/pages/Notebook/NotebookPage.tsx"
click node_client_transport "https://github.com/ijahangirabbas/chaibook-llm/blob/main/frontend/src/services/api.service.ts"
click node_api_runtime "https://github.com/ijahangirabbas/chaibook-llm/blob/main/backend/src/server.ts"
click node_v1_routes "https://github.com/ijahangirabbas/chaibook-llm/blob/main/backend/src/routes/v1/index.ts"
click node_auth_tenancy "https://github.com/ijahangirabbas/chaibook-llm/blob/main/backend/src/middlewares/auth.middleware.ts"
click node_sse_chat "https://github.com/ijahangirabbas/chaibook-llm/blob/main/backend/src/controllers/chat.controller.ts"
click node_source_service "https://github.com/ijahangirabbas/chaibook-llm/blob/main/backend/src/services/source.service.ts"
click node_ingestion_queue "https://github.com/ijahangirabbas/chaibook-llm/blob/main/backend/src/queue/ingestion.queue.ts"
click node_worker "https://github.com/ijahangirabbas/chaibook-llm/blob/main/backend/src/worker.ts"
click node_loaders "https://github.com/ijahangirabbas/chaibook-llm/blob/main/backend/src/loaders/loader.factory.ts"
click node_chunk_embed "https://github.com/ijahangirabbas/chaibook-llm/blob/main/backend/src/loaders/base.loader.ts"
click node_rag_service "https://github.com/ijahangirabbas/chaibook-llm/blob/main/backend/src/services/rag.service.ts"
click node_retrieval "https://github.com/ijahangirabbas/chaibook-llm/blob/main/backend/src/services/vector.service.ts"
click node_postgres "https://github.com/ijahangirabbas/chaibook-llm/blob/main/backend/prisma/schema.prisma"
click node_object_storage "https://github.com/ijahangirabbas/chaibook-llm/blob/main/backend/src/services/s3.service.ts"
click node_qdrant "https://github.com/ijahangirabbas/chaibook-llm/blob/main/backend/src/vectorstore/qdrant.store.ts"
click node_ai_providers "https://github.com/ijahangirabbas/chaibook-llm/blob/main/backend/src/config/embeddings.config.ts"
click node_clerk "https://github.com/ijahangirabbas/chaibook-llm/blob/main/backend/src/lib/clerk.auth.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_spa,node_client_routes,node_notebook_views,node_client_transport toneBlue
class node_api_runtime,node_v1_routes,node_auth_tenancy,node_controllers,node_sse_chat,node_rag_service,node_retrieval toneAmber
class node_source_service,node_ingestion_queue,node_worker,node_loaders,node_chunk_embed toneMint
class node_repositories,node_postgres,node_redis,node_object_storage,node_qdrant,node_ai_providers,node_clerk toneRose
```

## Components

### Browser SPA

- [React SPA](https://github.com/ijahangirabbas/chaibook-llm/blob/main/frontend/src/main.tsx): Vite/React · `frontend/src/main.tsx`
- [Routes & layouts](https://github.com/ijahangirabbas/chaibook-llm/blob/main/frontend/src/app/router.tsx): client routing · `frontend/src/app/router.tsx`
- [Notebook, source & chat views](https://github.com/ijahangirabbas/chaibook-llm/blob/main/frontend/src/app/pages/Notebook/NotebookPage.tsx): UI workflows · `frontend/src/app/pages/Notebook/NotebookPage.tsx`
- [API transport & state](https://github.com/ijahangirabbas/chaibook-llm/blob/main/frontend/src/services/api.service.ts): client boundary · Handles API calls and shared application state. · `frontend/src/services/api.service.ts`

### API Runtime

- [Express API](https://github.com/ijahangirabbas/chaibook-llm/blob/main/backend/src/server.ts): Node runtime · Can run independently or alongside the worker. · `backend/src/server.ts`
- [v1 REST/SSE routes](https://github.com/ijahangirabbas/chaibook-llm/blob/main/backend/src/routes/v1/index.ts): HTTP boundary · `backend/src/routes/v1/index.ts`
- [Auth & workspace guard](https://github.com/ijahangirabbas/chaibook-llm/blob/main/backend/src/middlewares/auth.middleware.ts): middleware · Verifies Clerk JWTs and enforces workspace scope. · `backend/src/middlewares/auth.middleware.ts`
- **Controllers**: API operations · Notebook, source, search, chunk, chat, and user operations.
- [Streaming chat boundary](https://github.com/ijahangirabbas/chaibook-llm/blob/main/backend/src/controllers/chat.controller.ts): SSE · `backend/src/controllers/chat.controller.ts`
- [RAG orchestration](https://github.com/ijahangirabbas/chaibook-llm/blob/main/backend/src/services/rag.service.ts): service · Builds bounded context and streams cited answers. · `backend/src/services/rag.service.ts`
- [Vector retrieval & rerank](https://github.com/ijahangirabbas/chaibook-llm/blob/main/backend/src/services/vector.service.ts): retrieval layer · Filters by tenant/notebook, then reranks and diversifies candidates. · `backend/src/services/vector.service.ts`

### Async Indexing

- [Source orchestration](https://github.com/ijahangirabbas/chaibook-llm/blob/main/backend/src/services/source.service.ts): service · Stores source material, creates metadata, and defers indexing. · `backend/src/services/source.service.ts`
- [Ingestion queue](https://github.com/ijahangirabbas/chaibook-llm/blob/main/backend/src/queue/ingestion.queue.ts): BullMQ queue · `backend/src/queue/ingestion.queue.ts`
- [Indexing worker](https://github.com/ijahangirabbas/chaibook-llm/blob/main/backend/src/worker.ts): Node worker · Consumes jobs and advances source lifecycle status. · `backend/src/worker.ts`
- [Content loaders](https://github.com/ijahangirabbas/chaibook-llm/blob/main/backend/src/loaders/loader.factory.ts): loader factory · Selects PDF, text, web, YouTube, and caption extraction. · `backend/src/loaders/loader.factory.ts`
- [Chunk & embed](https://github.com/ijahangirabbas/chaibook-llm/blob/main/backend/src/loaders/base.loader.ts): indexing stage · Persists extracted chunks and creates embeddings. · `backend/src/loaders/base.loader.ts`

### Data & Providers

- **Repositories**: persistence boundary · Preserves workspace isolation and soft deletion.
- [PostgreSQL / Prisma](https://github.com/ijahangirabbas/chaibook-llm/blob/main/backend/prisma/schema.prisma): system of record · Stores metadata, statuses, quotas, chunks, conversations, and citations. · `backend/prisma/schema.prisma`
- **Redis**: queue backend
- [S3-compatible storage](https://github.com/ijahangirabbas/chaibook-llm/blob/main/backend/src/services/s3.service.ts): raw source storage · `backend/src/services/s3.service.ts`
- [Qdrant](https://github.com/ijahangirabbas/chaibook-llm/blob/main/backend/src/vectorstore/qdrant.store.ts): vector index · Retrieval index, not the relational authority. · `backend/src/vectorstore/qdrant.store.ts`
- [Embedding, rerank & chat providers](https://github.com/ijahangirabbas/chaibook-llm/blob/main/backend/src/config/embeddings.config.ts): AI providers · Jina/OpenAI embeddings and reranking; Groq/OpenAI chat. · `backend/src/config/embeddings.config.ts`
- [Clerk](https://github.com/ijahangirabbas/chaibook-llm/blob/main/backend/src/lib/clerk.auth.ts): identity provider · `backend/src/lib/clerk.auth.ts`

## Connections

- React SPA → Routes & layouts: boots
- Routes & layouts → Notebook, source & chat views: renders
- Notebook, source & chat views → API transport & state: uses
- API transport & state → v1 REST/SSE routes: REST / SSE
- Express API → v1 REST/SSE routes: mounts
- v1 REST/SSE routes → Auth & workspace guard: guards with
- Auth & workspace guard → Clerk: verifies JWT
- Auth & workspace guard → Controllers: authorizes
- Controllers → Source orchestration: creates sources
- Controllers → Streaming chat boundary: chat requests
- Streaming chat boundary → RAG orchestration: streams
- Source orchestration → S3-compatible storage: stores raw files
- Source orchestration → Repositories: creates metadata
- Source orchestration → Ingestion queue: enqueues
- Ingestion queue → Redis: uses
- Indexing worker → Ingestion queue: consumes
- Indexing worker → Content loaders: extracts via
- Content loaders → Chunk & embed: content
- Chunk & embed → Repositories: persists chunks
- Chunk & embed → Qdrant: indexes vectors
- Chunk & embed → Embedding, rerank & chat providers: embeds
- Repositories → PostgreSQL / Prisma: Prisma
- RAG orchestration → Vector retrieval & rerank: retrieves context
- Vector retrieval & rerank → Qdrant: filtered search
- Vector retrieval & rerank → Embedding, rerank & chat providers: reranks
- RAG orchestration → Embedding, rerank & chat providers: generates answer
- RAG orchestration → Repositories: persists generation & citations