# debjoy26/ragbot-widget architecture

> Architecture diagram of the GitHub repository debjoy26/ragbot-widget, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/debjoy26/ragbot-widget
- Repository: https://github.com/debjoy26/ragbot-widget

## Overview

ragbot_widget provides a branded website RAG widget, a visitor-facing API, and a background ingestion worker sharing Supabase. The main workflow runs from an embedded visitor through session/authentication and chat handling to retrieval and an AI response; separately, document-indexing jobs extract, chunk, embed, and store content for retrieval. The graph preserves the documented chat, history, moderation, caching, handoff, and ingestion capabilities. Several route and service implementations were not sampled, so their internal call relationships are omitted rather than inferred.

Main entry points: [`worker/src/jobs/index-document.ts`](https://github.com/debjoy26/ragbot-widget/blob/main/worker/src/jobs/index-document.ts) (Document indexing), [`api/src/services/chat.ts`](https://github.com/debjoy26/ragbot-widget/blob/main/api/src/services/chat.ts) (Chat orchestration), [`widget/src/widget.ts`](https://github.com/debjoy26/ragbot-widget/blob/main/widget/src/widget.ts) (Widget runtime), [`api/src/app.ts`](https://github.com/debjoy26/ragbot-widget/blob/main/api/src/app.ts) (API assembly)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_widget["Visitor widget"]
  node_widget_runtime["Widget runtime<br/>[widget.ts]"]
  node_widget_ui["Chat interface<br/>[ui.ts]"]
  node_contact_card["Contact card<br/>[contact-card.ts]"]
  node_widget_session["Visitor session<br/>[session.ts]"]
  node_widget_api["API client<br/>[api.ts]"]
end

subgraph group_api["Visitor API"]
  node_api_entry["API assembly<br/>[app.ts]"]
  node_api_server["HTTP server<br/>[server.ts]"]
  node_session_routes["Session routes<br/>[sessions.ts]"]
  node_chat_routes["Chat routes<br/>[chat.ts]"]
  node_history_routes["Conversation routes<br/>[conversations.ts]"]
  node_visitor_auth["Visitor authentication<br/>[auth.ts]"]
  node_limits["Rate and budget limits<br/>[limits.ts]"]
  node_chat_service["Chat orchestration<br/>[chat.ts]"]
  node_retrieval["Knowledge retrieval<br/>[retrieval.ts]"]
  node_llm["LLM orchestration<br/>[llm.ts]"]
  node_moderation["Content moderation<br/>[moderation.ts]"]
  node_cache["Chat and retrieval caches<br/>[answer-cache.ts]"]
end

subgraph group_ai["AI and shared contracts"]
  node_shared_providers["AI provider adapters<br/>[providers.ts]"]
end

subgraph group_worker["Ingestion worker"]
  node_worker_entry["Worker process<br/>[worker.ts]"]
  node_job_runtime["Job runtime<br/>[runtime.ts]"]
  node_job_handlers["Job handlers<br/>[handlers.ts]"]
  node_index_job["Document indexing<br/>[index-document.ts]"]
  node_extract["Text extraction<br/>[extract.ts]"]
  node_chunk["Document chunking<br/>[chunk.ts]"]
  node_worker_storage["Document storage client<br/>[storage.ts]"]
end

subgraph group_data["Shared data"]
  node_supabase[("Supabase database and storage")]
end

node_visitor(("Website visitor"))
node_ai_services{{"AI provider services"}}

node_visitor -->|"opens widget"| node_widget_runtime
node_widget_runtime -->|"renders interface"| node_widget_ui
node_widget_ui -->|"renders card"| node_contact_card
node_widget_runtime -->|"uses session"| node_widget_session
node_widget_runtime -->|"calls API"| node_widget_api
node_widget_api -->|"sends requests"| node_api_entry
node_api_entry -->|"builds server"| node_api_server
node_api_entry -->|"registers routes"| node_chat_routes
node_api_entry -->|"registers routes"| node_history_routes
node_api_server -->|"registers routes"| node_session_routes
node_session_routes -->|"uses authentication"| node_visitor_auth
node_session_routes -->|"checks limits"| node_limits
node_chat_routes -.->|"dispatches chat"| node_chat_service
node_history_routes -.->|"loads conversations"| node_chat_service
node_chat_service -.->|"retrieves context"| node_retrieval
node_chat_service -.->|"generates answer"| node_llm
node_chat_service -.->|"moderates content"| node_moderation
node_chat_service -.->|"uses caches"| node_cache
node_llm -.->|"calls providers"| node_ai_services
node_visitor_auth -->|"checks sessions"| node_supabase
node_retrieval -->|"queries knowledge"| node_supabase
node_worker_entry -->|"starts runtime"| node_job_runtime
node_worker_entry -->|"builds handlers"| node_job_handlers
node_job_handlers -->|"registers handler"| node_index_job
node_job_runtime -->|"claims jobs"| node_supabase
node_index_job -->|"extracts text"| node_extract
node_index_job -->|"chunks document"| node_chunk
node_index_job -->|"reads source files"| node_worker_storage
node_index_job -->|"writes index"| node_supabase
node_worker_storage -->|"accesses objects"| node_supabase
node_index_job -.->|"embeds chunks"| node_ai_services

click node_widget_runtime "https://github.com/debjoy26/ragbot-widget/blob/main/widget/src/widget.ts"
click node_widget_ui "https://github.com/debjoy26/ragbot-widget/blob/main/widget/src/ui.ts"
click node_contact_card "https://github.com/debjoy26/ragbot-widget/blob/main/widget/src/contact-card.ts"
click node_widget_session "https://github.com/debjoy26/ragbot-widget/blob/main/widget/src/session.ts"
click node_widget_api "https://github.com/debjoy26/ragbot-widget/blob/main/widget/src/api.ts"
click node_api_entry "https://github.com/debjoy26/ragbot-widget/blob/main/api/src/app.ts"
click node_api_server "https://github.com/debjoy26/ragbot-widget/blob/main/api/src/server.ts"
click node_session_routes "https://github.com/debjoy26/ragbot-widget/blob/main/api/src/routes/sessions.ts"
click node_chat_routes "https://github.com/debjoy26/ragbot-widget/blob/main/api/src/routes/chat.ts"
click node_history_routes "https://github.com/debjoy26/ragbot-widget/blob/main/api/src/routes/conversations.ts"
click node_visitor_auth "https://github.com/debjoy26/ragbot-widget/blob/main/api/src/services/auth.ts"
click node_limits "https://github.com/debjoy26/ragbot-widget/blob/main/api/src/services/limits.ts"
click node_chat_service "https://github.com/debjoy26/ragbot-widget/blob/main/api/src/services/chat.ts"
click node_retrieval "https://github.com/debjoy26/ragbot-widget/blob/main/api/src/services/retrieval.ts"
click node_llm "https://github.com/debjoy26/ragbot-widget/blob/main/api/src/services/llm.ts"
click node_moderation "https://github.com/debjoy26/ragbot-widget/blob/main/api/src/services/moderation.ts"
click node_cache "https://github.com/debjoy26/ragbot-widget/blob/main/api/src/services/answer-cache.ts"
click node_shared_providers "https://github.com/debjoy26/ragbot-widget/blob/main/shared/src/providers.ts"
click node_worker_entry "https://github.com/debjoy26/ragbot-widget/blob/main/worker/src/worker.ts"
click node_job_runtime "https://github.com/debjoy26/ragbot-widget/blob/main/worker/src/runtime.ts"
click node_job_handlers "https://github.com/debjoy26/ragbot-widget/blob/main/worker/src/handlers.ts"
click node_index_job "https://github.com/debjoy26/ragbot-widget/blob/main/worker/src/jobs/index-document.ts"
click node_extract "https://github.com/debjoy26/ragbot-widget/blob/main/worker/src/lib/extract.ts"
click node_chunk "https://github.com/debjoy26/ragbot-widget/blob/main/worker/src/lib/chunk.ts"
click node_worker_storage "https://github.com/debjoy26/ragbot-widget/blob/main/worker/src/lib/storage.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_widget_runtime,node_widget_ui,node_contact_card,node_widget_session,node_widget_api toneBlue
class node_api_entry,node_api_server,node_session_routes,node_chat_routes,node_history_routes,node_visitor_auth,node_limits,node_chat_service,node_retrieval,node_llm,node_moderation,node_cache toneAmber
class node_shared_providers toneMint
class node_worker_entry,node_job_runtime,node_job_handlers,node_index_job,node_extract,node_chunk,node_worker_storage toneRose
class node_supabase,node_visitor,node_ai_services toneIndigo
```

## Components

### Visitor widget

- [Widget runtime](https://github.com/debjoy26/ragbot-widget/blob/main/widget/src/widget.ts): `widget/src/widget.ts`
- [Chat interface](https://github.com/debjoy26/ragbot-widget/blob/main/widget/src/ui.ts): `widget/src/ui.ts`
- [Contact card](https://github.com/debjoy26/ragbot-widget/blob/main/widget/src/contact-card.ts): `widget/src/contact-card.ts`
- [Visitor session](https://github.com/debjoy26/ragbot-widget/blob/main/widget/src/session.ts): `widget/src/session.ts`
- [API client](https://github.com/debjoy26/ragbot-widget/blob/main/widget/src/api.ts): `widget/src/api.ts`

### Visitor API

- [API assembly](https://github.com/debjoy26/ragbot-widget/blob/main/api/src/app.ts): `api/src/app.ts`
- [HTTP server](https://github.com/debjoy26/ragbot-widget/blob/main/api/src/server.ts): `api/src/server.ts`
- [Session routes](https://github.com/debjoy26/ragbot-widget/blob/main/api/src/routes/sessions.ts): `api/src/routes/sessions.ts`
- [Chat routes](https://github.com/debjoy26/ragbot-widget/blob/main/api/src/routes/chat.ts): `api/src/routes/chat.ts`
- [Conversation routes](https://github.com/debjoy26/ragbot-widget/blob/main/api/src/routes/conversations.ts): `api/src/routes/conversations.ts`
- [Visitor authentication](https://github.com/debjoy26/ragbot-widget/blob/main/api/src/services/auth.ts): `api/src/services/auth.ts`
- [Rate and budget limits](https://github.com/debjoy26/ragbot-widget/blob/main/api/src/services/limits.ts): `api/src/services/limits.ts`
- [Chat orchestration](https://github.com/debjoy26/ragbot-widget/blob/main/api/src/services/chat.ts): `api/src/services/chat.ts`
- [Knowledge retrieval](https://github.com/debjoy26/ragbot-widget/blob/main/api/src/services/retrieval.ts): `api/src/services/retrieval.ts`
- [LLM orchestration](https://github.com/debjoy26/ragbot-widget/blob/main/api/src/services/llm.ts): `api/src/services/llm.ts`
- [Content moderation](https://github.com/debjoy26/ragbot-widget/blob/main/api/src/services/moderation.ts): `api/src/services/moderation.ts`
- [Chat and retrieval caches](https://github.com/debjoy26/ragbot-widget/blob/main/api/src/services/answer-cache.ts): `api/src/services/answer-cache.ts`

### AI and shared contracts

- [AI provider adapters](https://github.com/debjoy26/ragbot-widget/blob/main/shared/src/providers.ts): `shared/src/providers.ts`

### Ingestion worker

- [Worker process](https://github.com/debjoy26/ragbot-widget/blob/main/worker/src/worker.ts): `worker/src/worker.ts`
- [Job runtime](https://github.com/debjoy26/ragbot-widget/blob/main/worker/src/runtime.ts): `worker/src/runtime.ts`
- [Job handlers](https://github.com/debjoy26/ragbot-widget/blob/main/worker/src/handlers.ts): `worker/src/handlers.ts`
- [Document indexing](https://github.com/debjoy26/ragbot-widget/blob/main/worker/src/jobs/index-document.ts): `worker/src/jobs/index-document.ts`
- [Text extraction](https://github.com/debjoy26/ragbot-widget/blob/main/worker/src/lib/extract.ts): `worker/src/lib/extract.ts`
- [Document chunking](https://github.com/debjoy26/ragbot-widget/blob/main/worker/src/lib/chunk.ts): `worker/src/lib/chunk.ts`
- [Document storage client](https://github.com/debjoy26/ragbot-widget/blob/main/worker/src/lib/storage.ts): `worker/src/lib/storage.ts`

### Shared data

- **Supabase database and storage**

### Other components

- **Website visitor**
- **AI provider services**

## Connections

- Website visitor → Widget runtime: opens widget (evidence: `README.md`)
- Widget runtime → Chat interface: renders interface (evidence: `widget/src/widget.ts`)
- Chat interface → Contact card: renders card (evidence: `widget/src/ui.ts`)
- Widget runtime → Visitor session: uses session (evidence: `widget/src/widget.ts`)
- Widget runtime → API client: calls API (evidence: `widget/src/widget.ts`)
- API client → API assembly: sends requests (evidence: `README.md`)
- API assembly → HTTP server: builds server (evidence: `api/src/app.ts`)
- API assembly → Chat routes: registers routes (evidence: `api/src/app.ts`)
- API assembly → Conversation routes: registers routes (evidence: `api/src/app.ts`)
- HTTP server → Session routes: registers routes (evidence: `api/src/server.ts`)
- Session routes → Visitor authentication: uses authentication (evidence: `api/src/routes/sessions.ts`)
- Session routes → Rate and budget limits: checks limits (evidence: `api/src/routes/sessions.ts`)
- Chat routes → Chat orchestration: dispatches chat
- Conversation routes → Chat orchestration: loads conversations
- Chat orchestration → Knowledge retrieval: retrieves context
- Chat orchestration → LLM orchestration: generates answer
- Chat orchestration → Content moderation: moderates content
- Chat orchestration → Chat and retrieval caches: uses caches
- LLM orchestration → AI provider services: calls providers
- Visitor authentication → Supabase database and storage: checks sessions (evidence: `api/src/services/auth.ts`)
- Knowledge retrieval → Supabase database and storage: queries knowledge (evidence: `api/src/services/retrieval.ts`)
- Worker process → Job runtime: starts runtime (evidence: `worker/src/worker.ts`)
- Worker process → Job handlers: builds handlers (evidence: `worker/src/worker.ts`)
- Job handlers → Document indexing: registers handler (evidence: `worker/src/handlers.ts`)
- Job runtime → Supabase database and storage: claims jobs (evidence: `worker/src/runtime.ts`)
- Document indexing → Text extraction: extracts text (evidence: `worker/src/jobs/index-document.ts`)
- Document indexing → Document chunking: chunks document (evidence: `worker/src/jobs/index-document.ts`)
- Document indexing → Document storage client: reads source files (evidence: `worker/src/jobs/index-document.ts`)
- Document indexing → Supabase database and storage: writes index (evidence: `worker/src/jobs/index-document.ts`)
- Document storage client → Supabase database and storage: accesses objects (evidence: `worker/src/lib/storage.ts`)
- Document indexing → AI provider services: embeds chunks