# judejulius/chatbotstudio architecture

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

- Interactive diagram: https://gitdiagram.com/judejulius/chatbotstudio
- Repository: https://github.com/judejulius/chatbotstudio

## Overview

Chatbot Studio lets an operator configure and test an agent, then publish that same agent as a branded website chatbot or connect it to WhatsApp. The principal path is Studio configuration → backend agent/chat runtime → model and knowledge/tool integrations → persisted conversation → published widget response. Separate product branches cover orchestration, quality, and operations. The README documents these capabilities; sampled runtime excerpts confirm provider resolution, RAG lookup, tool execution, persistence, evaluation, and streaming, but not every subsystem’s internal wiring.

Main entry points: [`backend/chat_engine.py`](https://github.com/judejulius/chatbotstudio/blob/master/backend/chat_engine.py) (Turn engine), [`backend/main.py`](https://github.com/judejulius/chatbotstudio/blob/master/backend/main.py) (API service), [`backend/routers/agents_router.py`](https://github.com/judejulius/chatbotstudio/blob/master/backend/routers/agents_router.py) (Agent endpoints), [`backend/routers/chat_router.py`](https://github.com/judejulius/chatbotstudio/blob/master/backend/routers/chat_router.py) (Chat endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Agent authoring"]
  node_studio["Agent Studio<br/>[page.tsx]"]
  node_customizer["Chatbot customizer<br/>[page.tsx]"]
  node_agents["Agent endpoints<br/>[agents_router.py]"]
end

subgraph group_runtime["Conversation runtime"]
  node_chat["Chat endpoints<br/>[chat_router.py]"]
  node_engine["Turn engine<br/>[chat_engine.py]"]
  node_providers["Model providers"]
  node_knowledge["Knowledge retrieval<br/>[rag_service.py]"]
  node_tools["Agent tools<br/>[builtin_tools.py]"]
  node_mcp["MCP integration<br/>[mcp_client.py]"]
end

subgraph group_channels["Publishing channels"]
  node_widget["Embeddable widget<br/>[index.js]"]
  node_widget_api["Widget endpoints<br/>[widget_router.py]"]
  node_whatsapp["WhatsApp channel"]
  node_bridge["WhatsApp bridge<br/>[index.js]"]
end

subgraph group_quality["Quality and orchestration"]
  node_teams["Teams and workflows<br/>[dag_executor.py]"]
  node_evaluations["Evaluation suites<br/>[eval_engine.py]"]
  node_observability["Analytics and traces"]
end

subgraph group_platform["Platform services"]
  node_api["API service<br/>[main.py]"]
  node_records[("Conversation records<br/>[database.py]")]
  node_auth["Authentication<br/>[auth_router.py]"]
  node_database[("Database<br/>[database.py]")]
end

node_operator(("Studio operator"))
node_model_service{{"Model provider service"}}
node_visitor(("Website visitor"))

node_operator -->|"configures agent"| node_studio
node_studio -->|"saves configuration"| node_agents
node_customizer -->|"publishes channel"| node_agents
node_agents -->|"uses API"| node_api
node_api -->|"dispatches request"| node_chat
node_chat -->|"runs turn"| node_engine
node_engine -->|"resolves model"| node_providers
node_providers -->|"sends prompts"| node_model_service
node_engine -->|"retrieves context"| node_knowledge
node_engine -->|"executes calls"| node_tools
node_engine -.->|"uses MCP tools"| node_mcp
node_engine -->|"persists messages"| node_records
node_visitor -->|"chats through"| node_widget
node_widget -->|"streams turns"| node_widget_api
node_widget_api -->|"starts turn"| node_chat
node_whatsapp -->|"exchanges messages"| node_bridge
node_teams -->|"runs agent"| node_engine
node_evaluations -->|"tests responses"| node_providers
node_evaluations -->|"stores runs"| node_database
node_observability -->|"reads metrics"| node_database
node_auth -->|"reads and writes users"| node_database
node_api -->|"dispatches auth"| node_auth

click node_studio "https://github.com/judejulius/chatbotstudio/blob/master/frontend/app/dashboard/studio/page.tsx"
click node_customizer "https://github.com/judejulius/chatbotstudio/blob/master/frontend/app/(authenticated)/chatbots/page.tsx"
click node_api "https://github.com/judejulius/chatbotstudio/blob/master/backend/main.py"
click node_agents "https://github.com/judejulius/chatbotstudio/blob/master/backend/routers/agents_router.py"
click node_chat "https://github.com/judejulius/chatbotstudio/blob/master/backend/routers/chat_router.py"
click node_engine "https://github.com/judejulius/chatbotstudio/blob/master/backend/chat_engine.py"
click node_providers "https://github.com/judejulius/chatbotstudio/blob/master/backend/llm/provider_factory.py"
click node_knowledge "https://github.com/judejulius/chatbotstudio/blob/master/backend/rag_service.py"
click node_tools "https://github.com/judejulius/chatbotstudio/blob/master/backend/builtin_tools.py"
click node_mcp "https://github.com/judejulius/chatbotstudio/blob/master/backend/mcp_client.py"
click node_records "https://github.com/judejulius/chatbotstudio/blob/master/backend/database.py"
click node_widget "https://github.com/judejulius/chatbotstudio/blob/master/widget/src/index.js"
click node_widget_api "https://github.com/judejulius/chatbotstudio/blob/master/backend/routers/widget_router.py"
click node_whatsapp "https://github.com/judejulius/chatbotstudio/blob/master/backend/services/whatsapp_service.py"
click node_bridge "https://github.com/judejulius/chatbotstudio/blob/master/wa-bridge/index.js"
click node_teams "https://github.com/judejulius/chatbotstudio/blob/master/backend/dag_executor.py"
click node_evaluations "https://github.com/judejulius/chatbotstudio/blob/master/backend/eval_engine.py"
click node_observability "https://github.com/judejulius/chatbotstudio/blob/master/backend/routers/analytics_router.py"
click node_auth "https://github.com/judejulius/chatbotstudio/blob/master/backend/routers/auth_router.py"
click node_database "https://github.com/judejulius/chatbotstudio/blob/master/backend/database.py"

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_studio,node_customizer,node_agents toneBlue
class node_chat,node_engine,node_providers,node_knowledge,node_tools,node_mcp toneAmber
class node_widget,node_widget_api,node_whatsapp,node_bridge toneMint
class node_teams,node_evaluations,node_observability toneRose
class node_api,node_records,node_auth,node_database,node_operator,node_model_service,node_visitor toneIndigo
```

## Components

### Agent authoring

- [Agent Studio](https://github.com/judejulius/chatbotstudio/blob/master/frontend/app/dashboard/studio/page.tsx): `frontend/app/dashboard/studio/page.tsx`
- [Chatbot customizer](https://github.com/judejulius/chatbotstudio/blob/master/frontend/app/(authenticated)/chatbots/page.tsx): `frontend/app/(authenticated)/chatbots/page.tsx`
- [Agent endpoints](https://github.com/judejulius/chatbotstudio/blob/master/backend/routers/agents_router.py): `backend/routers/agents_router.py`

### Conversation runtime

- [Chat endpoints](https://github.com/judejulius/chatbotstudio/blob/master/backend/routers/chat_router.py): `backend/routers/chat_router.py`
- [Turn engine](https://github.com/judejulius/chatbotstudio/blob/master/backend/chat_engine.py): `backend/chat_engine.py`
- [Model providers](https://github.com/judejulius/chatbotstudio/blob/master/backend/llm/provider_factory.py): `backend/llm/provider_factory.py`
- [Knowledge retrieval](https://github.com/judejulius/chatbotstudio/blob/master/backend/rag_service.py): `backend/rag_service.py`
- [Agent tools](https://github.com/judejulius/chatbotstudio/blob/master/backend/builtin_tools.py): `backend/builtin_tools.py`
- [MCP integration](https://github.com/judejulius/chatbotstudio/blob/master/backend/mcp_client.py): `backend/mcp_client.py`

### Publishing channels

- [Embeddable widget](https://github.com/judejulius/chatbotstudio/blob/master/widget/src/index.js): `widget/src/index.js`
- [Widget endpoints](https://github.com/judejulius/chatbotstudio/blob/master/backend/routers/widget_router.py): `backend/routers/widget_router.py`
- [WhatsApp channel](https://github.com/judejulius/chatbotstudio/blob/master/backend/services/whatsapp_service.py): `backend/services/whatsapp_service.py`
- [WhatsApp bridge](https://github.com/judejulius/chatbotstudio/blob/master/wa-bridge/index.js): `wa-bridge/index.js`

### Quality and orchestration

- [Teams and workflows](https://github.com/judejulius/chatbotstudio/blob/master/backend/dag_executor.py): `backend/dag_executor.py`
- [Evaluation suites](https://github.com/judejulius/chatbotstudio/blob/master/backend/eval_engine.py): `backend/eval_engine.py`
- [Analytics and traces](https://github.com/judejulius/chatbotstudio/blob/master/backend/routers/analytics_router.py): `backend/routers/analytics_router.py`

### Platform services

- [API service](https://github.com/judejulius/chatbotstudio/blob/master/backend/main.py): `backend/main.py`
- [Conversation records](https://github.com/judejulius/chatbotstudio/blob/master/backend/database.py): `backend/database.py`
- [Authentication](https://github.com/judejulius/chatbotstudio/blob/master/backend/routers/auth_router.py): `backend/routers/auth_router.py`
- [Database](https://github.com/judejulius/chatbotstudio/blob/master/backend/database.py): `backend/database.py`

### Other components

- **Studio operator**
- **Model provider service**
- **Website visitor**

## Connections

- Studio operator → Agent Studio: configures agent
- Agent Studio → Agent endpoints: saves configuration
- Chatbot customizer → Agent endpoints: publishes channel
- Agent endpoints → API service: uses API
- API service → Chat endpoints: dispatches request
- Chat endpoints → Turn engine: runs turn
- Turn engine → Model providers: resolves model
- Model providers → Model provider service: sends prompts
- Turn engine → Knowledge retrieval: retrieves context
- Turn engine → Agent tools: executes calls
- Turn engine → MCP integration: uses MCP tools
- Turn engine → Conversation records: persists messages
- Website visitor → Embeddable widget: chats through
- Embeddable widget → Widget endpoints: streams turns
- Widget endpoints → Chat endpoints: starts turn
- WhatsApp channel → WhatsApp bridge: exchanges messages
- Teams and workflows → Turn engine: runs agent
- Evaluation suites → Model providers: tests responses
- Evaluation suites → Database: stores runs
- Analytics and traces → Database: reads metrics
- Authentication → Database: reads and writes users
- API service → Authentication: dispatches auth