# icanzzzz/chatbox architecture

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

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

## Overview

Chatbox is a cross-platform AI chat client whose primary workflow is configuring a provider, composing a prompt, streaming a model response, and retaining the conversation locally. The repository separates renderer UI, shared application/domain services, and Electron main-process capabilities. README-documented features also include image generation, prompt reuse, and knowledge-base workflows. Several implementation paths were not sampled, so uncertain UI-to-service and IPC connections are omitted or marked unverified rather than inferred.

Main entry points: [`packages/chatbox-core/src/generation/GenerationService.ts`](https://github.com/icanzzzz/chatbox/blob/main/packages/chatbox-core/src/generation/GenerationService.ts) (Generation service), [`src/main/main.ts`](https://github.com/icanzzzz/chatbox/blob/main/src/main/main.ts) (Electron main), [`src/renderer/components/knowledge-base/KnowledgeBase.tsx`](https://github.com/icanzzzz/chatbox/blob/main/src/renderer/components/knowledge-base/KnowledgeBase.tsx) (Knowledge-base UI), [`src/renderer/components/InputBox/InputBox.tsx`](https://github.com/icanzzzz/chatbox/blob/main/src/renderer/components/InputBox/InputBox.tsx) (Prompt composer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Chat experience"]
  node_chat_ui["Chat UI<br/>[MessageList.tsx]"]
  node_composer["Prompt composer<br/>[InputBox.tsx]"]
  node_settings_ui["Provider settings<br/>[ProviderList.tsx]"]
  node_model_selection["Model selection<br/>[index.tsx]"]
end

subgraph group_core["Chatbox core"]
  node_session_service["Session service<br/>[SessionService.ts]"]
  node_session_repository["Session repository port"]
  node_session_storage[("Session metadata storage")]
  node_generation["Generation service"]
  node_model_factory["Model factory<br/>[ModelFactory.ts]"]
  node_provider_impl["Provider models<br/>[volcengine.ts]"]
  node_settings_service["Settings service<br/>[SettingsService.ts]"]
  node_settings_store["Settings storage port"]
end

subgraph group_desktop["Desktop runtime"]
  node_main_process["Electron main<br/>[main.ts]"]
  node_preload["Preload bridge<br/>[index.ts]"]
  node_file_parser["Local file parsing<br/>[file-parser.ts]"]
end

subgraph group_knowledge["Knowledge and tools"]
  node_knowledge_ui["Knowledge-base UI<br/>[KnowledgeBase.tsx]"]
  node_knowledge_handlers["Knowledge IPC handlers<br/>[ipc-handlers.ts]"]
  node_knowledge_db[("Knowledge database<br/>[db.ts]")]
  node_attachment_rag["Session attachment RAG<br/>[ipc-handlers.ts]"]
  node_sandbox["Sandbox execution<br/>[manager.ts]"]
  node_skills["Skills<br/>[ipc-handlers.ts]"]
end

node_user(("User"))
node_external_model{{"LLM provider"}}

node_user -->|"configures provider"| node_settings_ui
node_user -->|"submits prompt"| node_composer
node_user -->|"reads response"| node_chat_ui
node_settings_ui -.->|"saves settings"| node_settings_service
node_model_selection -.->|"selects model"| node_model_factory
node_composer -.->|"starts generation"| node_generation
node_generation -.->|"dispatches request"| node_provider_impl
node_provider_impl -->|"calls model API"| node_external_model
node_generation -->|"streams reply"| node_chat_ui
node_session_service -->|"reads and writes"| node_session_repository
node_session_repository -.->|"stores metadata"| node_session_storage
node_settings_service -.->|"persists settings"| node_settings_store
node_main_process -->|"parses files"| node_file_parser
node_main_process -.->|"exposes bridge"| node_preload
node_knowledge_ui -.->|"requests operations"| node_knowledge_handlers
node_knowledge_handlers -->|"uses database"| node_knowledge_db
node_knowledge_ui -.->|"indexes attachments"| node_attachment_rag
node_user -.->|"runs tool tasks"| node_sandbox
node_user -.->|"uses skills"| node_skills

click node_chat_ui "https://github.com/icanzzzz/chatbox/blob/main/src/renderer/components/chat/MessageList.tsx"
click node_composer "https://github.com/icanzzzz/chatbox/blob/main/src/renderer/components/InputBox/InputBox.tsx"
click node_settings_ui "https://github.com/icanzzzz/chatbox/blob/main/src/renderer/components/settings/provider/ProviderList.tsx"
click node_model_selection "https://github.com/icanzzzz/chatbox/blob/main/src/renderer/components/ModelSelector/index.tsx"
click node_session_service "https://github.com/icanzzzz/chatbox/blob/main/packages/chatbox-core/src/application/session/SessionService.ts"
click node_session_repository "https://github.com/icanzzzz/chatbox/blob/main/packages/chatbox-core/src/ports/session-repository.ts"
click node_session_storage "https://github.com/icanzzzz/chatbox/blob/main/src/renderer/storage/SessionMetaStorage.ts"
click node_generation "https://github.com/icanzzzz/chatbox/blob/main/packages/chatbox-core/src/generation/GenerationService.ts"
click node_model_factory "https://github.com/icanzzzz/chatbox/blob/main/packages/chatbox-core/src/application/model/ModelFactory.ts"
click node_provider_impl "https://github.com/icanzzzz/chatbox/blob/main/src/shared/providers/definitions/models/volcengine.ts"
click node_settings_service "https://github.com/icanzzzz/chatbox/blob/main/packages/chatbox-core/src/application/settings/SettingsService.ts"
click node_settings_store "https://github.com/icanzzzz/chatbox/blob/main/packages/chatbox-core/src/ports/settings-storage.ts"
click node_main_process "https://github.com/icanzzzz/chatbox/blob/main/src/main/main.ts"
click node_preload "https://github.com/icanzzzz/chatbox/blob/main/src/preload/index.ts"
click node_file_parser "https://github.com/icanzzzz/chatbox/blob/main/src/main/file-parser.ts"
click node_knowledge_ui "https://github.com/icanzzzz/chatbox/blob/main/src/renderer/components/knowledge-base/KnowledgeBase.tsx"
click node_knowledge_handlers "https://github.com/icanzzzz/chatbox/blob/main/src/main/knowledge-base/ipc-handlers.ts"
click node_knowledge_db "https://github.com/icanzzzz/chatbox/blob/main/src/main/knowledge-base/db.ts"
click node_attachment_rag "https://github.com/icanzzzz/chatbox/blob/main/src/main/session-attachment-rag/ipc-handlers.ts"
click node_sandbox "https://github.com/icanzzzz/chatbox/blob/main/src/main/sandbox/manager.ts"
click node_skills "https://github.com/icanzzzz/chatbox/blob/main/src/main/skills/ipc-handlers.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_chat_ui,node_composer,node_settings_ui,node_model_selection,node_user toneBlue
class node_session_service,node_session_repository,node_session_storage,node_generation,node_model_factory,node_provider_impl,node_settings_service,node_settings_store toneAmber
class node_main_process,node_preload,node_file_parser toneMint
class node_knowledge_ui,node_knowledge_handlers,node_knowledge_db,node_attachment_rag,node_sandbox,node_skills toneRose
class node_external_model toneIndigo
```

## Components

### Chat experience

- [Chat UI](https://github.com/icanzzzz/chatbox/blob/main/src/renderer/components/chat/MessageList.tsx): `src/renderer/components/chat/MessageList.tsx`
- [Prompt composer](https://github.com/icanzzzz/chatbox/blob/main/src/renderer/components/InputBox/InputBox.tsx): `src/renderer/components/InputBox/InputBox.tsx`
- [Provider settings](https://github.com/icanzzzz/chatbox/blob/main/src/renderer/components/settings/provider/ProviderList.tsx): `src/renderer/components/settings/provider/ProviderList.tsx`
- [Model selection](https://github.com/icanzzzz/chatbox/blob/main/src/renderer/components/ModelSelector/index.tsx): `src/renderer/components/ModelSelector/index.tsx`

### Chatbox core

- [Session service](https://github.com/icanzzzz/chatbox/blob/main/packages/chatbox-core/src/application/session/SessionService.ts): `packages/chatbox-core/src/application/session/SessionService.ts`
- [Session repository port](https://github.com/icanzzzz/chatbox/blob/main/packages/chatbox-core/src/ports/session-repository.ts): `packages/chatbox-core/src/ports/session-repository.ts`
- [Session metadata storage](https://github.com/icanzzzz/chatbox/blob/main/src/renderer/storage/SessionMetaStorage.ts): `src/renderer/storage/SessionMetaStorage.ts`
- [Generation service](https://github.com/icanzzzz/chatbox/blob/main/packages/chatbox-core/src/generation/GenerationService.ts): `packages/chatbox-core/src/generation/GenerationService.ts`
- [Model factory](https://github.com/icanzzzz/chatbox/blob/main/packages/chatbox-core/src/application/model/ModelFactory.ts): `packages/chatbox-core/src/application/model/ModelFactory.ts`
- [Provider models](https://github.com/icanzzzz/chatbox/blob/main/src/shared/providers/definitions/models/volcengine.ts): `src/shared/providers/definitions/models/volcengine.ts`
- [Settings service](https://github.com/icanzzzz/chatbox/blob/main/packages/chatbox-core/src/application/settings/SettingsService.ts): `packages/chatbox-core/src/application/settings/SettingsService.ts`
- [Settings storage port](https://github.com/icanzzzz/chatbox/blob/main/packages/chatbox-core/src/ports/settings-storage.ts): `packages/chatbox-core/src/ports/settings-storage.ts`

### Desktop runtime

- [Electron main](https://github.com/icanzzzz/chatbox/blob/main/src/main/main.ts): `src/main/main.ts`
- [Preload bridge](https://github.com/icanzzzz/chatbox/blob/main/src/preload/index.ts): `src/preload/index.ts`
- [Local file parsing](https://github.com/icanzzzz/chatbox/blob/main/src/main/file-parser.ts): `src/main/file-parser.ts`

### Knowledge and tools

- [Knowledge-base UI](https://github.com/icanzzzz/chatbox/blob/main/src/renderer/components/knowledge-base/KnowledgeBase.tsx): `src/renderer/components/knowledge-base/KnowledgeBase.tsx`
- [Knowledge IPC handlers](https://github.com/icanzzzz/chatbox/blob/main/src/main/knowledge-base/ipc-handlers.ts): `src/main/knowledge-base/ipc-handlers.ts`
- [Knowledge database](https://github.com/icanzzzz/chatbox/blob/main/src/main/knowledge-base/db.ts): `src/main/knowledge-base/db.ts`
- [Session attachment RAG](https://github.com/icanzzzz/chatbox/blob/main/src/main/session-attachment-rag/ipc-handlers.ts): `src/main/session-attachment-rag/ipc-handlers.ts`
- [Sandbox execution](https://github.com/icanzzzz/chatbox/blob/main/src/main/sandbox/manager.ts): `src/main/sandbox/manager.ts`
- [Skills](https://github.com/icanzzzz/chatbox/blob/main/src/main/skills/ipc-handlers.ts): `src/main/skills/ipc-handlers.ts`

### Other components

- **User**
- **LLM provider**

## Connections

- User → Provider settings: configures provider (evidence: `README.md`)
- User → Prompt composer: submits prompt (evidence: `README.md`)
- User → Chat UI: reads response (evidence: `README.md`)
- Provider settings → Settings service: saves settings
- Model selection → Model factory: selects model
- Prompt composer → Generation service: starts generation
- Generation service → Provider models: dispatches request
- Provider models → LLM provider: calls model API (evidence: `src/shared/providers/definitions/models/volcengine.ts`)
- Generation service → Chat UI: streams reply (evidence: `README.md`)
- Session service → Session repository port: reads and writes (evidence: `packages/chatbox-core/src/application/session/SessionService.ts`)
- Session repository port → Session metadata storage: stores metadata
- Settings service → Settings storage port: persists settings
- Electron main → Local file parsing: parses files (evidence: `src/main/main.ts`)
- Electron main → Preload bridge: exposes bridge
- Knowledge-base UI → Knowledge IPC handlers: requests operations
- Knowledge IPC handlers → Knowledge database: uses database (evidence: `src/main/knowledge-base/ipc-handlers.ts`)
- Knowledge-base UI → Session attachment RAG: indexes attachments
- User → Sandbox execution: runs tool tasks
- User → Skills: uses skills
