# mlouie/rag-chatbot architecture

> Architecture diagram of the GitHub repository mlouie/rag-chatbot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mlouie/rag-chatbot
- Repository: https://github.com/mlouie/rag-chatbot

## Overview

The product is a multi-tenant platform for turning uploaded documents into embeddable RAG chatbots. Admins create bots and upload content; the API processes it into searchable chunks. A visitor chats through the widget or dashboard preview, and the API retrieves relevant context and generates a provider-backed answer. Admins can review unanswered questions and add answers to bot knowledge. Source-index references and README claims support the main backend links; frontend/API wiring and unsampled subsystems are shown cautiously.

Main entry points: [`api/api/routers/chat.py`](https://github.com/mlouie/rag-chatbot/blob/main/api/api/routers/chat.py) (Chat routes), [`api/api/routers/unanswered_questions.py`](https://github.com/mlouie/rag-chatbot/blob/main/api/api/routers/unanswered_questions.py) (Question routes), [`api/main.py`](https://github.com/mlouie/rag-chatbot/blob/main/api/main.py) (FastAPI entry), [`api/api/routers/documents.py`](https://github.com/mlouie/rag-chatbot/blob/main/api/api/routers/documents.py) (Document routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_admin["Admin Console"]
  node_dashboard["Admin dashboard<br/>[page.tsx]"]
  node_bot_management["Bot management<br/>[page.tsx]"]
  node_document_admin["Document admin<br/>[page.tsx]"]
  node_question_admin["Question review<br/>[page.tsx]"]
  node_preview["Chat preview<br/>[chat-preview.tsx]"]
end

subgraph group_api["API and Access"]
  node_auth["JWT authentication<br/>[auth.py]"]
  node_api_entry["FastAPI entry<br/>[main.py]"]
  node_bot_routes["Bot routes<br/>[bots.py]"]
  node_document_routes["Document routes<br/>[documents.py]"]
  node_chat_routes["Chat routes<br/>[chat.py]"]
  node_question_routes["Question routes"]
  node_stats_routes["Usage statistics<br/>[stats.py]"]
  node_records["Domain records"]
  node_database[("Postgres and pgvector<br/>[database.py]")]
end

subgraph group_knowledge["Knowledge Pipeline"]
  node_job_processor["Ingestion jobs<br/>[processor.py]"]
  node_document_processor["Document processing<br/>[processor.py]"]
  node_extractor["Text extraction<br/>[extractor.py]"]
  node_chunker["Text chunking<br/>[chunker.py]"]
  node_embedder["Embedding generation<br/>[embedder.py]"]
end

subgraph group_chat["Chat Runtime"]
  node_rag["Retrieval and generation<br/>[service.py]"]
  node_llm_openai["OpenAI provider<br/>[openai_provider.py]"]
  node_llm_anthropic["Anthropic provider"]
end

subgraph group_delivery["Chat Clients"]
  node_widget_entry["Widget initializer<br/>[index.js]"]
  node_widget["Widget chat UI<br/>[widget.js]"]
  node_widget_api["Widget API client<br/>[api.js]"]
end

node_admin_user(("Bot administrator"))
node_visitor(("Website visitor"))

node_admin_user -.->|"manages bots"| node_dashboard
node_dashboard -.->|"opens"| node_bot_management
node_admin_user -.->|"uploads files"| node_document_admin
node_admin_user -.->|"reviews questions"| node_question_admin
node_admin_user -.->|"tests bot"| node_preview
node_api_entry -->|"registers"| node_bot_routes
node_api_entry -->|"registers"| node_document_routes
node_api_entry -->|"registers"| node_chat_routes
node_api_entry -->|"registers"| node_stats_routes
node_api_entry -->|"registers"| node_question_routes
node_bot_routes -->|"authenticates"| node_auth
node_bot_routes -->|"uses sessions"| node_database
node_bot_routes -->|"queries bots"| node_records
node_document_routes -->|"authenticates"| node_auth
node_document_routes -->|"uses sessions"| node_database
node_document_routes -->|"dispatches processing"| node_job_processor
node_document_routes -->|"uses records"| node_records
node_job_processor -.->|"invokes"| node_document_processor
node_document_processor -->|"extracts text"| node_extractor
node_document_processor -->|"splits text"| node_chunker
node_document_processor -->|"embeds chunks"| node_embedder
node_document_processor -->|"updates documents"| node_records
node_chat_routes -->|"authenticates optionally"| node_auth
node_chat_routes -->|"uses sessions"| node_database
node_chat_routes -->|"stores chat records"| node_records
node_chat_routes -->|"requests answers"| node_rag
node_rag -->|"searches vectors"| node_database
node_rag -->|"selects provider"| node_llm_openai
node_rag -->|"selects provider"| node_llm_anthropic
node_question_routes -->|"authenticates"| node_auth
node_question_routes -->|"uses sessions"| node_database
node_question_routes -->|"reads and updates"| node_records
node_question_routes -->|"embeds quick answers"| node_embedder
node_visitor -.->|"loads embed"| node_widget_entry
node_widget_entry -->|"initializes"| node_widget
node_widget -->|"sends messages"| node_widget_api
node_widget_api -.->|"posts chat"| node_chat_routes
node_preview -.->|"tests chat"| node_chat_routes
node_admin_user -.->|"configures bots"| node_bot_routes
node_admin_user -.->|"submits answers"| node_question_routes

click node_dashboard "https://github.com/mlouie/rag-chatbot/blob/main/app/src/app/(dashboard)/dashboard/page.tsx"
click node_bot_management "https://github.com/mlouie/rag-chatbot/blob/main/app/src/app/(dashboard)/bots/page.tsx"
click node_document_admin "https://github.com/mlouie/rag-chatbot/blob/main/app/src/app/(dashboard)/bots/%5Bid%5D/documents/page.tsx"
click node_question_admin "https://github.com/mlouie/rag-chatbot/blob/main/app/src/app/(dashboard)/unanswered-questions/page.tsx"
click node_preview "https://github.com/mlouie/rag-chatbot/blob/main/app/src/components/chat/chat-preview.tsx"
click node_auth "https://github.com/mlouie/rag-chatbot/blob/main/api/api/core/auth.py"
click node_api_entry "https://github.com/mlouie/rag-chatbot/blob/main/api/main.py"
click node_bot_routes "https://github.com/mlouie/rag-chatbot/blob/main/api/api/routers/bots.py"
click node_document_routes "https://github.com/mlouie/rag-chatbot/blob/main/api/api/routers/documents.py"
click node_chat_routes "https://github.com/mlouie/rag-chatbot/blob/main/api/api/routers/chat.py"
click node_question_routes "https://github.com/mlouie/rag-chatbot/blob/main/api/api/routers/unanswered_questions.py"
click node_stats_routes "https://github.com/mlouie/rag-chatbot/blob/main/api/api/routers/stats.py"
click node_records "https://github.com/mlouie/rag-chatbot/tree/main/api/api/models"
click node_database "https://github.com/mlouie/rag-chatbot/blob/main/api/api/core/database.py"
click node_job_processor "https://github.com/mlouie/rag-chatbot/blob/main/api/api/services/jobs/processor.py"
click node_document_processor "https://github.com/mlouie/rag-chatbot/blob/main/api/api/services/document/processor.py"
click node_extractor "https://github.com/mlouie/rag-chatbot/blob/main/api/api/services/document/extractor.py"
click node_chunker "https://github.com/mlouie/rag-chatbot/blob/main/api/api/services/document/chunker.py"
click node_embedder "https://github.com/mlouie/rag-chatbot/blob/main/api/api/services/document/embedder.py"
click node_rag "https://github.com/mlouie/rag-chatbot/blob/main/api/api/services/rag/service.py"
click node_llm_openai "https://github.com/mlouie/rag-chatbot/blob/main/api/api/services/llm/openai_provider.py"
click node_llm_anthropic "https://github.com/mlouie/rag-chatbot/blob/main/api/api/services/llm/anthropic_provider.py"
click node_widget_entry "https://github.com/mlouie/rag-chatbot/blob/main/widget/src/index.js"
click node_widget "https://github.com/mlouie/rag-chatbot/blob/main/widget/src/widget.js"
click node_widget_api "https://github.com/mlouie/rag-chatbot/blob/main/widget/src/api.js"

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_dashboard,node_bot_management,node_document_admin,node_question_admin,node_preview toneBlue
class node_auth,node_api_entry,node_bot_routes,node_document_routes,node_chat_routes,node_question_routes,node_stats_routes,node_records,node_database toneAmber
class node_job_processor,node_document_processor,node_extractor,node_chunker,node_embedder toneMint
class node_rag,node_llm_openai,node_llm_anthropic toneRose
class node_widget_entry,node_widget,node_widget_api,node_admin_user,node_visitor toneIndigo
```

## Components

### Admin Console

- [Admin dashboard](https://github.com/mlouie/rag-chatbot/blob/main/app/src/app/(dashboard)/dashboard/page.tsx): `app/src/app/(dashboard)/dashboard/page.tsx`
- [Bot management](https://github.com/mlouie/rag-chatbot/blob/main/app/src/app/(dashboard)/bots/page.tsx): `app/src/app/(dashboard)/bots/page.tsx`
- [Document admin](https://github.com/mlouie/rag-chatbot/blob/main/app/src/app/(dashboard)/bots/%5Bid%5D/documents/page.tsx): `app/src/app/(dashboard)/bots/[id]/documents/page.tsx`
- [Question review](https://github.com/mlouie/rag-chatbot/blob/main/app/src/app/(dashboard)/unanswered-questions/page.tsx): `app/src/app/(dashboard)/unanswered-questions/page.tsx`
- [Chat preview](https://github.com/mlouie/rag-chatbot/blob/main/app/src/components/chat/chat-preview.tsx): `app/src/components/chat/chat-preview.tsx`

### API and Access

- [JWT authentication](https://github.com/mlouie/rag-chatbot/blob/main/api/api/core/auth.py): `api/api/core/auth.py`
- [FastAPI entry](https://github.com/mlouie/rag-chatbot/blob/main/api/main.py): `api/main.py`
- [Bot routes](https://github.com/mlouie/rag-chatbot/blob/main/api/api/routers/bots.py): `api/api/routers/bots.py`
- [Document routes](https://github.com/mlouie/rag-chatbot/blob/main/api/api/routers/documents.py): `api/api/routers/documents.py`
- [Chat routes](https://github.com/mlouie/rag-chatbot/blob/main/api/api/routers/chat.py): `api/api/routers/chat.py`
- [Question routes](https://github.com/mlouie/rag-chatbot/blob/main/api/api/routers/unanswered_questions.py): `api/api/routers/unanswered_questions.py`
- [Usage statistics](https://github.com/mlouie/rag-chatbot/blob/main/api/api/routers/stats.py): `api/api/routers/stats.py`
- [Domain records](https://github.com/mlouie/rag-chatbot/tree/main/api/api/models): `api/api/models`
- [Postgres and pgvector](https://github.com/mlouie/rag-chatbot/blob/main/api/api/core/database.py): `api/api/core/database.py`

### Knowledge Pipeline

- [Ingestion jobs](https://github.com/mlouie/rag-chatbot/blob/main/api/api/services/jobs/processor.py): `api/api/services/jobs/processor.py`
- [Document processing](https://github.com/mlouie/rag-chatbot/blob/main/api/api/services/document/processor.py): `api/api/services/document/processor.py`
- [Text extraction](https://github.com/mlouie/rag-chatbot/blob/main/api/api/services/document/extractor.py): `api/api/services/document/extractor.py`
- [Text chunking](https://github.com/mlouie/rag-chatbot/blob/main/api/api/services/document/chunker.py): `api/api/services/document/chunker.py`
- [Embedding generation](https://github.com/mlouie/rag-chatbot/blob/main/api/api/services/document/embedder.py): `api/api/services/document/embedder.py`

### Chat Runtime

- [Retrieval and generation](https://github.com/mlouie/rag-chatbot/blob/main/api/api/services/rag/service.py): `api/api/services/rag/service.py`
- [OpenAI provider](https://github.com/mlouie/rag-chatbot/blob/main/api/api/services/llm/openai_provider.py): `api/api/services/llm/openai_provider.py`
- [Anthropic provider](https://github.com/mlouie/rag-chatbot/blob/main/api/api/services/llm/anthropic_provider.py): `api/api/services/llm/anthropic_provider.py`

### Chat Clients

- [Widget initializer](https://github.com/mlouie/rag-chatbot/blob/main/widget/src/index.js): `widget/src/index.js`
- [Widget chat UI](https://github.com/mlouie/rag-chatbot/blob/main/widget/src/widget.js): `widget/src/widget.js`
- [Widget API client](https://github.com/mlouie/rag-chatbot/blob/main/widget/src/api.js): `widget/src/api.js`

### Other components

- **Bot administrator**
- **Website visitor**

## Connections

- Bot administrator → Admin dashboard: manages bots (evidence: `README.md`)
- Admin dashboard → Bot management: opens
- Bot administrator → Document admin: uploads files (evidence: `README.md`)
- Bot administrator → Question review: reviews questions (evidence: `README.md`)
- Bot administrator → Chat preview: tests bot (evidence: `README.md`)
- FastAPI entry → Bot routes: registers (evidence: `api/main.py`)
- FastAPI entry → Document routes: registers (evidence: `api/main.py`)
- FastAPI entry → Chat routes: registers (evidence: `api/main.py`)
- FastAPI entry → Usage statistics: registers (evidence: `api/main.py`)
- FastAPI entry → Question routes: registers (evidence: `api/main.py`)
- Bot routes → JWT authentication: authenticates (evidence: `api/api/routers/bots.py`)
- Bot routes → Postgres and pgvector: uses sessions (evidence: `api/api/routers/bots.py`)
- Bot routes → Domain records: queries bots (evidence: `api/api/routers/bots.py`)
- Document routes → JWT authentication: authenticates (evidence: `api/api/routers/documents.py`)
- Document routes → Postgres and pgvector: uses sessions (evidence: `api/api/routers/documents.py`)
- Document routes → Ingestion jobs: dispatches processing (evidence: `api/api/routers/documents.py`)
- Document routes → Domain records: uses records (evidence: `api/api/routers/documents.py`)
- Ingestion jobs → Document processing: invokes
- Document processing → Text extraction: extracts text (evidence: `api/api/services/document/processor.py`)
- Document processing → Text chunking: splits text (evidence: `api/api/services/document/processor.py`)
- Document processing → Embedding generation: embeds chunks (evidence: `api/api/services/document/processor.py`)
- Document processing → Domain records: updates documents (evidence: `api/api/services/document/processor.py`)
- Chat routes → JWT authentication: authenticates optionally (evidence: `api/api/routers/chat.py`)
- Chat routes → Postgres and pgvector: uses sessions (evidence: `api/api/routers/chat.py`)
- Chat routes → Domain records: stores chat records (evidence: `api/api/routers/chat.py`)
- Chat routes → Retrieval and generation: requests answers (evidence: `api/api/routers/chat.py`)
- Retrieval and generation → Postgres and pgvector: searches vectors (evidence: `api/api/services/rag/service.py`)
- Retrieval and generation → OpenAI provider: selects provider (evidence: `api/api/services/rag/service.py`)
- Retrieval and generation → Anthropic provider: selects provider (evidence: `api/api/services/rag/service.py`)
- Question routes → JWT authentication: authenticates (evidence: `api/api/routers/unanswered_questions.py`)
- Question routes → Postgres and pgvector: uses sessions (evidence: `api/api/routers/unanswered_questions.py`)
- Question routes → Domain records: reads and updates (evidence: `api/api/routers/unanswered_questions.py`)
- Question routes → Embedding generation: embeds quick answers (evidence: `api/api/routers/unanswered_questions.py`)
- Website visitor → Widget initializer: loads embed (evidence: `README.md`)
- Widget initializer → Widget chat UI: initializes (evidence: `widget/src/index.js`)
- Widget chat UI → Widget API client: sends messages (evidence: `widget/src/widget.js`)
- Widget API client → Chat routes: posts chat (evidence: `README.md`)
- Chat preview → Chat routes: tests chat (evidence: `README.md`)
- Bot administrator → Bot routes: configures bots (evidence: `README.md`)
- Bot administrator → Question routes: submits answers (evidence: `README.md`)
