# cherryhq/cherry-studio architecture

> Architecture diagram of the GitHub repository cherryhq/cherry-studio, 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/cherryhq/cherry-studio
- Repository: https://github.com/cherryhq/cherry-studio

## Overview

Cherry Studio is a cross-platform AI desktop workstation. Users configure providers and models, then chat or run agents; related workflows search local knowledge, create images, use web and automation tools, and manage generated files. The graph keeps these product stages distinct and includes provider/runtime and knowledge ingestion/search layers. README statements establish the product capabilities; sampled source confirms selected provider, knowledge, agent-storage, and web-search relationships. Other feature links are omitted where implementation wiring was not shown.

Main entry points: [`packages/agent-behavior/src/orchestration`](https://github.com/cherryhq/cherry-studio/tree/main/packages/agent-behavior/src/orchestration) (Agent workflows), [`packages/provider-registry/src/providers`](https://github.com/cherryhq/cherry-studio/tree/main/packages/provider-registry/src/providers) (Provider setup), [`src/renderer/hooks/useConversationTurnController.ts`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/hooks/useConversationTurnController.ts) (Conversations), [`packages/aiCore/src/core/runtime/pluginEngine.ts`](https://github.com/cherryhq/cherry-studio/blob/main/packages/aiCore/src/core/runtime/pluginEngine.ts) (AI runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Desktop interaction"]
  node_provider_config["Provider setup"]
  node_conversations["Conversations"]
end

subgraph group_ai["AI and agents"]
  node_assistant_runtime["AI runtime<br/>[pluginEngine.ts]"]
  node_provider_extensions["Provider extensions"]
  node_agents["Agent workflows"]
  node_agent_workspace[("Agent workspace")]
end

subgraph group_knowledge["Knowledge and documents"]
  node_knowledge_ingestion["Knowledge ingestion"]
  node_knowledge_paths[("Knowledge files<br/>[pathStorage.ts]")]
  node_knowledge_search["Knowledge search"]
  node_file_preview["Document preview"]
end

subgraph group_tools["Creative and tools"]
  node_image_creation["Image creation"]
  node_web_search["Web search"]
  node_automation["Automation tools"]
  node_skills_mcp["Skills and MCP<br/>[agentMcpServers.ts]"]
  node_mini_apps_gateway["Mini Apps and gateway"]
end

subgraph group_workspace["Workspace and storage"]
  node_file_library[("File library<br/>[FileStorage.ts]")]
  node_voice["Voice features"]
  node_history["Conversation history"]
  node_backup["Local and WebDAV backup"]
end

node_user(("Desktop user"))

node_user -->|"configures"| node_provider_config
node_provider_config -.->|"selects providers"| node_provider_extensions
node_user -->|"starts chats"| node_conversations
node_conversations -.->|"requests model"| node_assistant_runtime
node_assistant_runtime -->|"resolves models"| node_provider_extensions
node_user -->|"runs tasks"| node_agents
node_agents -->|"uses workspace"| node_agent_workspace
node_user -->|"adds sources"| node_knowledge_ingestion
node_knowledge_ingestion -->|"stores source files"| node_knowledge_paths
node_user -->|"searches knowledge"| node_knowledge_search
node_knowledge_search -->|"reads indexed sources"| node_knowledge_paths
node_user -->|"opens documents"| node_file_preview
node_user -->|"creates images"| node_image_creation
node_user -->|"searches web"| node_web_search
node_user -->|"automates tasks"| node_automation
node_agents -->|"uses tools"| node_automation
node_agents -->|"extends capabilities"| node_skills_mcp
node_user -->|"opens tools"| node_mini_apps_gateway
node_user -->|"manages files"| node_file_library
node_user -->|"dictates and listens"| node_voice
node_user -->|"reviews history"| node_history
node_user -->|"backs up data"| node_backup

click node_provider_config "https://github.com/cherryhq/cherry-studio/tree/main/packages/provider-registry/src/providers"
click node_conversations "https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/hooks/useConversationTurnController.ts"
click node_assistant_runtime "https://github.com/cherryhq/cherry-studio/blob/main/packages/aiCore/src/core/runtime/pluginEngine.ts"
click node_provider_extensions "https://github.com/cherryhq/cherry-studio/blob/main/packages/aiCore/src/core/providers/core/ProviderExtension.ts"
click node_agents "https://github.com/cherryhq/cherry-studio/tree/main/packages/agent-behavior/src/orchestration"
click node_agent_workspace "https://github.com/cherryhq/cherry-studio/blob/main/src/main/ai/agents/AgentWorkspaceStorageService.ts"
click node_knowledge_ingestion "https://github.com/cherryhq/cherry-studio/blob/main/src/main/features/knowledge/ingestion/KnowledgeIngestionService.ts"
click node_knowledge_paths "https://github.com/cherryhq/cherry-studio/blob/main/src/main/features/knowledge/pathStorage.ts"
click node_knowledge_search "https://github.com/cherryhq/cherry-studio/blob/main/src/main/features/knowledge/query/KnowledgeQueryService.ts"
click node_file_preview "https://github.com/cherryhq/cherry-studio/tree/main/packages/file-preview/src"
click node_image_creation "https://github.com/cherryhq/cherry-studio/tree/main/src/renderer"
click node_web_search "https://github.com/cherryhq/cherry-studio/blob/main/packages/web-search/src/createWebSearchClient.ts"
click node_automation "https://github.com/cherryhq/cherry-studio/tree/main/src/main/ai/runtime"
click node_skills_mcp "https://github.com/cherryhq/cherry-studio/blob/main/src/main/ai/runtime/agentMcpServers.ts"
click node_mini_apps_gateway "https://github.com/cherryhq/cherry-studio/tree/main/src/main/features/miniApp"
click node_file_library "https://github.com/cherryhq/cherry-studio/blob/main/src/main/services/FileStorage.ts"
click node_voice "https://github.com/cherryhq/cherry-studio/tree/main/native/system-speech/src"
click node_history "https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/components/history/useHistoryRecordsController.ts"
click node_backup "https://github.com/cherryhq/cherry-studio/tree/main/src/main/services"

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_provider_config,node_conversations,node_user toneBlue
class node_assistant_runtime,node_provider_extensions,node_agents,node_agent_workspace toneAmber
class node_knowledge_ingestion,node_knowledge_paths,node_knowledge_search,node_file_preview toneMint
class node_image_creation,node_web_search,node_automation,node_skills_mcp,node_mini_apps_gateway toneRose
class node_file_library,node_voice,node_history,node_backup toneIndigo
```

## Components

### Desktop interaction

- [Provider setup](https://github.com/cherryhq/cherry-studio/tree/main/packages/provider-registry/src/providers): `packages/provider-registry/src/providers`
- [Conversations](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/hooks/useConversationTurnController.ts): `src/renderer/hooks/useConversationTurnController.ts`

### AI and agents

- [AI runtime](https://github.com/cherryhq/cherry-studio/blob/main/packages/aiCore/src/core/runtime/pluginEngine.ts): `packages/aiCore/src/core/runtime/pluginEngine.ts`
- [Provider extensions](https://github.com/cherryhq/cherry-studio/blob/main/packages/aiCore/src/core/providers/core/ProviderExtension.ts): `packages/aiCore/src/core/providers/core/ProviderExtension.ts`
- [Agent workflows](https://github.com/cherryhq/cherry-studio/tree/main/packages/agent-behavior/src/orchestration): `packages/agent-behavior/src/orchestration`
- [Agent workspace](https://github.com/cherryhq/cherry-studio/blob/main/src/main/ai/agents/AgentWorkspaceStorageService.ts): `src/main/ai/agents/AgentWorkspaceStorageService.ts`

### Knowledge and documents

- [Knowledge ingestion](https://github.com/cherryhq/cherry-studio/blob/main/src/main/features/knowledge/ingestion/KnowledgeIngestionService.ts): `src/main/features/knowledge/ingestion/KnowledgeIngestionService.ts`
- [Knowledge files](https://github.com/cherryhq/cherry-studio/blob/main/src/main/features/knowledge/pathStorage.ts): `src/main/features/knowledge/pathStorage.ts`
- [Knowledge search](https://github.com/cherryhq/cherry-studio/blob/main/src/main/features/knowledge/query/KnowledgeQueryService.ts): `src/main/features/knowledge/query/KnowledgeQueryService.ts`
- [Document preview](https://github.com/cherryhq/cherry-studio/tree/main/packages/file-preview/src): `packages/file-preview/src`

### Creative and tools

- [Image creation](https://github.com/cherryhq/cherry-studio/tree/main/src/renderer): `src/renderer`
- [Web search](https://github.com/cherryhq/cherry-studio/blob/main/packages/web-search/src/createWebSearchClient.ts): `packages/web-search/src/createWebSearchClient.ts`
- [Automation tools](https://github.com/cherryhq/cherry-studio/tree/main/src/main/ai/runtime): `src/main/ai/runtime`
- [Skills and MCP](https://github.com/cherryhq/cherry-studio/blob/main/src/main/ai/runtime/agentMcpServers.ts): `src/main/ai/runtime/agentMcpServers.ts`
- [Mini Apps and gateway](https://github.com/cherryhq/cherry-studio/tree/main/src/main/features/miniApp): `src/main/features/miniApp`

### Workspace and storage

- [File library](https://github.com/cherryhq/cherry-studio/blob/main/src/main/services/FileStorage.ts): `src/main/services/FileStorage.ts`
- [Voice features](https://github.com/cherryhq/cherry-studio/tree/main/native/system-speech/src): `native/system-speech/src`
- [Conversation history](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/components/history/useHistoryRecordsController.ts): `src/renderer/components/history/useHistoryRecordsController.ts`
- [Local and WebDAV backup](https://github.com/cherryhq/cherry-studio/tree/main/src/main/services): `src/main/services`

### Other components

- **Desktop user**

## Connections

- Desktop user → Provider setup: configures (evidence: `README.md`)
- Provider setup → Provider extensions: selects providers
- Desktop user → Conversations: starts chats (evidence: `README.md`)
- Conversations → AI runtime: requests model
- AI runtime → Provider extensions: resolves models (evidence: `packages/aiCore/src/core/runtime/pluginEngine.ts`)
- Desktop user → Agent workflows: runs tasks (evidence: `README.md`)
- Agent workflows → Agent workspace: uses workspace (evidence: `README.md`)
- Desktop user → Knowledge ingestion: adds sources (evidence: `README.md`)
- Knowledge ingestion → Knowledge files: stores source files (evidence: `src/main/features/knowledge/ingestion/KnowledgeIngestionService.ts`)
- Desktop user → Knowledge search: searches knowledge (evidence: `README.md`)
- Knowledge search → Knowledge files: reads indexed sources (evidence: `src/main/features/knowledge/query/KnowledgeQueryService.ts`)
- Desktop user → Document preview: opens documents (evidence: `README.md`)
- Desktop user → Image creation: creates images (evidence: `README.md`)
- Desktop user → Web search: searches web (evidence: `README.md`)
- Desktop user → Automation tools: automates tasks (evidence: `README.md`)
- Agent workflows → Automation tools: uses tools (evidence: `README.md`)
- Agent workflows → Skills and MCP: extends capabilities (evidence: `README.md`)
- Desktop user → Mini Apps and gateway: opens tools (evidence: `README.md`)
- Desktop user → File library: manages files (evidence: `README.md`)
- Desktop user → Voice features: dictates and listens (evidence: `README.md`)
- Desktop user → Conversation history: reviews history (evidence: `README.md`)
- Desktop user → Local and WebDAV backup: backs up data (evidence: `README.md`)
