# chatboxai/chatbox architecture

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

- Interactive diagram: https://gitdiagram.com/chatboxai/chatbox
- Repository: https://github.com/chatboxai/chatbox

## Overview

Chatbox is a local-first AI copilot spanning desktop, web, and mobile clients. The principal workflow is configuring a provider, sending a prompt, and receiving a streamed reply; conversations are retained locally. The map also preserves documented image generation, prompt reuse, and localization, plus repository-supported session persistence, browser, sandbox, MCP, and knowledge-base capabilities. Several of these branches are identified by the tree or README, but their runtime wiring was not sampled; those links are omitted rather than inferred.

Main entry points: [`packages/chatbox-core/src/generation/GenerationService.ts`](https://github.com/chatboxai/chatbox/blob/main/packages/chatbox-core/src/generation/GenerationService.ts) (Generation runtime), [`src/shared/providers/definitions`](https://github.com/chatboxai/chatbox/tree/main/src/shared/providers/definitions) (Model providers), [`src/main/main.ts`](https://github.com/chatboxai/chatbox/blob/main/src/main/main.ts) (Desktop app), [`packages/chatbox-core/src/application/chat/ChatMessageService.ts`](https://github.com/chatboxai/chatbox/blob/main/packages/chatbox-core/src/application/chat/ChatMessageService.ts) (Chat service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Client experience"]
  node_desktop["Desktop app<br/>[main.ts]"]
  node_react["React integration"]
  node_localization["Localization"]
end

subgraph group_ai["AI interaction"]
  node_chat["Chat service"]
  node_generation["Generation runtime"]
  node_model["Model providers"]
  node_image["Image generation"]
  node_copilots["Copilot services"]
end

subgraph group_sessions["Conversation data"]
  node_session["Session services"]
  node_rowrepo["Row repository"]
  node_rowstore["Session row storage"]
  node_localstore[("Renderer storage")]
  node_settings["Settings services"]
  node_backup["Backup transfer"]
end

subgraph group_tools["Tools and knowledge"]
  node_browser["Built-in browser<br/>[controller.ts]"]
  node_sandbox["Execution sandbox<br/>[manager.ts]"]
  node_mcp["MCP tools<br/>[controller.ts]"]
  node_knowledge["Knowledge base"]
  node_search["Session search"]
end

subgraph group_platform["Platform services"]
  node_main["Electron main<br/>[main.ts]"]
  node_fileedits["File edits<br/>[file-edits.ts]"]
end

node_user(("User"))

node_user -->|"uses"| node_desktop
node_desktop -->|"configures provider"| node_model
node_user -->|"sends prompt"| node_chat
node_chat -.->|"starts generation"| node_generation
node_generation -->|"requests reply"| node_model
node_model -->|"streams response"| node_generation
node_generation -.->|"updates conversation"| node_session
node_session -.->|"uses repository"| node_rowrepo
node_rowrepo -->|"uses port"| node_rowstore
node_localstore -.->|"implements port"| node_rowstore
node_user -->|"requests images"| node_image
node_user -->|"uses prompts"| node_copilots
node_user -->|"configures app"| node_settings
node_user -->|"selects language"| node_localization
node_user -.->|"backs up data"| node_backup
node_generation -.->|"uses tools"| node_mcp
node_generation -.->|"uses browser"| node_browser
node_generation -.->|"runs tasks"| node_sandbox
node_generation -.->|"retrieves context"| node_knowledge
node_user -.->|"searches sessions"| node_search
node_main -->|"initializes"| node_knowledge
node_sandbox -->|"writes files"| node_fileedits

click node_desktop "https://github.com/chatboxai/chatbox/blob/main/src/main/main.ts"
click node_react "https://github.com/chatboxai/chatbox/tree/main/packages/chatbox-react/src"
click node_localization "https://github.com/chatboxai/chatbox/tree/main/packages/chatbox-i18n/src"
click node_chat "https://github.com/chatboxai/chatbox/blob/main/packages/chatbox-core/src/application/chat/ChatMessageService.ts"
click node_generation "https://github.com/chatboxai/chatbox/blob/main/packages/chatbox-core/src/generation/GenerationService.ts"
click node_model "https://github.com/chatboxai/chatbox/tree/main/src/shared/providers/definitions"
click node_image "https://github.com/chatboxai/chatbox/tree/main/packages/chatbox-core/src/application/image-generation"
click node_copilots "https://github.com/chatboxai/chatbox/tree/main/packages/chatbox-core/src/application/copilots"
click node_session "https://github.com/chatboxai/chatbox/tree/main/packages/chatbox-core/src/application/session"
click node_rowrepo "https://github.com/chatboxai/chatbox/blob/main/packages/chatbox-core/src/application/session/RowBackedSessionRepository.ts"
click node_rowstore "https://github.com/chatboxai/chatbox/blob/main/packages/chatbox-core/src/ports/session-row-store.ts"
click node_localstore "https://github.com/chatboxai/chatbox/blob/main/src/renderer/storage/SessionRowStorage.ts"
click node_settings "https://github.com/chatboxai/chatbox/tree/main/packages/chatbox-core/src/application/settings"
click node_backup "https://github.com/chatboxai/chatbox/tree/main/packages/chatbox-core/src/backup-export"
click node_browser "https://github.com/chatboxai/chatbox/blob/main/src/main/built-in-browser/controller.ts"
click node_sandbox "https://github.com/chatboxai/chatbox/blob/main/src/main/sandbox/manager.ts"
click node_mcp "https://github.com/chatboxai/chatbox/blob/main/packages/chatbox-core/src/mcp/controller.ts"
click node_knowledge "https://github.com/chatboxai/chatbox/tree/main/src/main/knowledge-base"
click node_search "https://github.com/chatboxai/chatbox/blob/main/packages/chatbox-core/src/application/session/SessionSearchService.ts"
click node_main "https://github.com/chatboxai/chatbox/blob/main/src/main/main.ts"
click node_fileedits "https://github.com/chatboxai/chatbox/blob/main/src/shared/file-edits.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_desktop,node_react,node_localization,node_user toneBlue
class node_chat,node_generation,node_model,node_image,node_copilots toneAmber
class node_session,node_rowrepo,node_rowstore,node_localstore,node_settings,node_backup toneMint
class node_browser,node_sandbox,node_mcp,node_knowledge,node_search toneRose
class node_main,node_fileedits toneIndigo
```

## Components

### Client experience

- [Desktop app](https://github.com/chatboxai/chatbox/blob/main/src/main/main.ts): `src/main/main.ts`
- [React integration](https://github.com/chatboxai/chatbox/tree/main/packages/chatbox-react/src): `packages/chatbox-react/src`
- [Localization](https://github.com/chatboxai/chatbox/tree/main/packages/chatbox-i18n/src): `packages/chatbox-i18n/src`

### AI interaction

- [Chat service](https://github.com/chatboxai/chatbox/blob/main/packages/chatbox-core/src/application/chat/ChatMessageService.ts): `packages/chatbox-core/src/application/chat/ChatMessageService.ts`
- [Generation runtime](https://github.com/chatboxai/chatbox/blob/main/packages/chatbox-core/src/generation/GenerationService.ts): `packages/chatbox-core/src/generation/GenerationService.ts`
- [Model providers](https://github.com/chatboxai/chatbox/tree/main/src/shared/providers/definitions): `src/shared/providers/definitions`
- [Image generation](https://github.com/chatboxai/chatbox/tree/main/packages/chatbox-core/src/application/image-generation): `packages/chatbox-core/src/application/image-generation`
- [Copilot services](https://github.com/chatboxai/chatbox/tree/main/packages/chatbox-core/src/application/copilots): `packages/chatbox-core/src/application/copilots`

### Conversation data

- [Session services](https://github.com/chatboxai/chatbox/tree/main/packages/chatbox-core/src/application/session): `packages/chatbox-core/src/application/session`
- [Row repository](https://github.com/chatboxai/chatbox/blob/main/packages/chatbox-core/src/application/session/RowBackedSessionRepository.ts): `packages/chatbox-core/src/application/session/RowBackedSessionRepository.ts`
- [Session row storage](https://github.com/chatboxai/chatbox/blob/main/packages/chatbox-core/src/ports/session-row-store.ts): `packages/chatbox-core/src/ports/session-row-store.ts`
- [Renderer storage](https://github.com/chatboxai/chatbox/blob/main/src/renderer/storage/SessionRowStorage.ts): `src/renderer/storage/SessionRowStorage.ts`
- [Settings services](https://github.com/chatboxai/chatbox/tree/main/packages/chatbox-core/src/application/settings): `packages/chatbox-core/src/application/settings`
- [Backup transfer](https://github.com/chatboxai/chatbox/tree/main/packages/chatbox-core/src/backup-export): `packages/chatbox-core/src/backup-export`

### Tools and knowledge

- [Built-in browser](https://github.com/chatboxai/chatbox/blob/main/src/main/built-in-browser/controller.ts): `src/main/built-in-browser/controller.ts`
- [Execution sandbox](https://github.com/chatboxai/chatbox/blob/main/src/main/sandbox/manager.ts): `src/main/sandbox/manager.ts`
- [MCP tools](https://github.com/chatboxai/chatbox/blob/main/packages/chatbox-core/src/mcp/controller.ts): `packages/chatbox-core/src/mcp/controller.ts`
- [Knowledge base](https://github.com/chatboxai/chatbox/tree/main/src/main/knowledge-base): `src/main/knowledge-base`
- [Session search](https://github.com/chatboxai/chatbox/blob/main/packages/chatbox-core/src/application/session/SessionSearchService.ts): `packages/chatbox-core/src/application/session/SessionSearchService.ts`

### Platform services

- [Electron main](https://github.com/chatboxai/chatbox/blob/main/src/main/main.ts): `src/main/main.ts`
- [File edits](https://github.com/chatboxai/chatbox/blob/main/src/shared/file-edits.ts): `src/shared/file-edits.ts`

### Other components

- **User**

## Connections

- User → Desktop app: uses (evidence: `README.md`)
- Desktop app → Model providers: configures provider (evidence: `README.md`)
- User → Chat service: sends prompt (evidence: `README.md`)
- Chat service → Generation runtime: starts generation
- Generation runtime → Model providers: requests reply (evidence: `README.md`)
- Model providers → Generation runtime: streams response (evidence: `README.md`)
- Generation runtime → Session services: updates conversation
- Session services → Row repository: uses repository (evidence: `packages/chatbox-core/src/application/session/RowBackedSessionRepository.ts`)
- Row repository → Session row storage: uses port (evidence: `packages/chatbox-core/src/application/session/RowBackedSessionRepository.ts`)
- Renderer storage → Session row storage: implements port
- User → Image generation: requests images (evidence: `README.md`)
- User → Copilot services: uses prompts (evidence: `README.md`)
- User → Settings services: configures app (evidence: `README.md`)
- User → Localization: selects language (evidence: `README.md`)
- User → Backup transfer: backs up data
- Generation runtime → MCP tools: uses tools
- Generation runtime → Built-in browser: uses browser
- Generation runtime → Execution sandbox: runs tasks
- Generation runtime → Knowledge base: retrieves context
- User → Session search: searches sessions
- Electron main → Knowledge base: initializes (evidence: `src/main/main.ts`)
- Execution sandbox → File edits: writes files (evidence: `src/main/sandbox/manager.ts`)
