# iwindy/cherry-studio architecture

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

- Interactive diagram: https://gitdiagram.com/iwindy/cherry-studio
- Repository: https://github.com/iwindy/cherry-studio

## Overview

Cherry Studio is a cross-platform AI desktop client. Its principal workflow is selecting an assistant or model, sending a conversation turn, and receiving a response from a cloud or local provider. The repository also supports knowledge-base ingestion and search, MCP tools, resource management, and document-oriented UI features. The excerpts show details for knowledge processing and AI-provider/plugin internals; many application-level links are not sampled, so those are marked unverified rather than treated as observed calls.

Main entry points: [`src/main/ai/runtime`](https://github.com/iwindy/cherry-studio/tree/main/src/main/ai/runtime) (AI runtime), [`packages/aiCore/src/core/runtime/pluginEngine.ts`](https://github.com/iwindy/cherry-studio/blob/main/packages/aiCore/src/core/runtime/pluginEngine.ts) (Plugin engine), [`src/renderer/hooks/useConversationTurnController.ts`](https://github.com/iwindy/cherry-studio/blob/main/src/renderer/hooks/useConversationTurnController.ts) (Conversation turn), [`packages/aiCore/src/core/agents/createAgent.ts`](https://github.com/iwindy/cherry-studio/blob/main/packages/aiCore/src/core/agents/createAgent.ts) (Agent core)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_conversation["Conversations and AI"]
  node_turn["Conversation turn"]
  node_ai_runtime["AI runtime"]
  node_agent_core["Agent core<br/>[createAgent.ts]"]
  node_plugin_engine["Plugin engine<br/>[pluginEngine.ts]"]
  node_plugin_manager["Plugin manager<br/>[manager.ts]"]
end

subgraph group_knowledge["Knowledge management"]
  node_knowledge_ingestion["Document ingestion"]
  node_knowledge_files["Knowledge file storage<br/>[pathStorage.ts]"]
  node_knowledge_query["Knowledge search"]
  node_knowledge_store[("Knowledge index")]
end

subgraph group_integrations["Providers and integrations"]
  node_provider_registry["Provider registry<br/>[registry-loader.ts]"]
  node_provider_extensions["Provider extensions"]
  node_local_models["Local models"]
  node_mcp["MCP servers<br/>[agentMcpServers.ts]"]
  node_remote_protocol["Remote protocol<br/>[connection.ts]"]
end

subgraph group_experience["Desktop experience"]
  node_resource_catalog["Resource catalog"]
  node_history["Conversation history"]
  node_markdown["Markdown rendering<br/>[markdown.tsx]"]
  node_file_storage["File management<br/>[FileStorage.ts]"]
end

node_user(("Desktop user"))

node_user -.->|"sends turn"| node_turn
node_turn -.->|"requests response"| node_ai_runtime
node_ai_runtime -.->|"runs agent"| node_agent_core
node_agent_core -.->|"uses runtime"| node_plugin_engine
node_plugin_engine -->|"executes hooks"| node_plugin_manager
node_plugin_engine -.->|"resolves model"| node_provider_extensions
node_provider_extensions -.->|"uses catalog"| node_provider_registry
node_ai_runtime -.->|"supports local models"| node_local_models
node_ai_runtime -.->|"uses MCP tools"| node_mcp
node_user -.->|"adds documents"| node_knowledge_ingestion
node_knowledge_ingestion -->|"copies and checks files"| node_knowledge_files
node_user -.->|"searches knowledge"| node_knowledge_query
node_knowledge_query -->|"queries index"| node_knowledge_store
node_user -.->|"manages resources"| node_resource_catalog
node_user -.->|"reviews conversations"| node_history
node_ai_runtime -.->|"renders response"| node_markdown
node_user -.->|"manages files"| node_file_storage
node_ai_runtime -.->|"supports remote access"| node_remote_protocol

click node_turn "https://github.com/iwindy/cherry-studio/blob/main/src/renderer/hooks/useConversationTurnController.ts"
click node_ai_runtime "https://github.com/iwindy/cherry-studio/tree/main/src/main/ai/runtime"
click node_agent_core "https://github.com/iwindy/cherry-studio/blob/main/packages/aiCore/src/core/agents/createAgent.ts"
click node_plugin_engine "https://github.com/iwindy/cherry-studio/blob/main/packages/aiCore/src/core/runtime/pluginEngine.ts"
click node_plugin_manager "https://github.com/iwindy/cherry-studio/blob/main/packages/aiCore/src/core/plugins/manager.ts"
click node_provider_registry "https://github.com/iwindy/cherry-studio/blob/main/packages/provider-registry/src/registry-loader.ts"
click node_provider_extensions "https://github.com/iwindy/cherry-studio/blob/main/packages/aiCore/src/core/providers/core/ExtensionRegistry.ts"
click node_local_models "https://github.com/iwindy/cherry-studio/tree/main/src/main/ai/localModel"
click node_mcp "https://github.com/iwindy/cherry-studio/blob/main/src/main/ai/runtime/agentMcpServers.ts"
click node_knowledge_ingestion "https://github.com/iwindy/cherry-studio/blob/main/src/main/features/knowledge/ingestion/KnowledgeIngestionService.ts"
click node_knowledge_files "https://github.com/iwindy/cherry-studio/blob/main/src/main/features/knowledge/pathStorage.ts"
click node_knowledge_query "https://github.com/iwindy/cherry-studio/blob/main/src/main/features/knowledge/query/KnowledgeQueryService.ts"
click node_knowledge_store "https://github.com/iwindy/cherry-studio/tree/main/src/main/features/knowledge/pipeline/vectorstore"
click node_resource_catalog "https://github.com/iwindy/cherry-studio/blob/main/src/renderer/hooks/resourceCatalog/useResourceCatalogController.ts"
click node_history "https://github.com/iwindy/cherry-studio/blob/main/src/renderer/components/history/useHistoryRecordsController.ts"
click node_markdown "https://github.com/iwindy/cherry-studio/blob/main/packages/ui/src/components/composites/markdown/markdown.tsx"
click node_file_storage "https://github.com/iwindy/cherry-studio/blob/main/src/main/services/FileStorage.ts"
click node_remote_protocol "https://github.com/iwindy/cherry-studio/blob/main/packages/remote-protocol/src/connection.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_turn,node_ai_runtime,node_agent_core,node_plugin_engine,node_plugin_manager,node_user toneBlue
class node_knowledge_ingestion,node_knowledge_files,node_knowledge_query,node_knowledge_store toneAmber
class node_provider_registry,node_provider_extensions,node_local_models,node_mcp,node_remote_protocol toneMint
class node_resource_catalog,node_history,node_markdown,node_file_storage toneRose
```

## Components

### Conversations and AI

- [Conversation turn](https://github.com/iwindy/cherry-studio/blob/main/src/renderer/hooks/useConversationTurnController.ts): `src/renderer/hooks/useConversationTurnController.ts`
- [AI runtime](https://github.com/iwindy/cherry-studio/tree/main/src/main/ai/runtime): `src/main/ai/runtime`
- [Agent core](https://github.com/iwindy/cherry-studio/blob/main/packages/aiCore/src/core/agents/createAgent.ts): `packages/aiCore/src/core/agents/createAgent.ts`
- [Plugin engine](https://github.com/iwindy/cherry-studio/blob/main/packages/aiCore/src/core/runtime/pluginEngine.ts): `packages/aiCore/src/core/runtime/pluginEngine.ts`
- [Plugin manager](https://github.com/iwindy/cherry-studio/blob/main/packages/aiCore/src/core/plugins/manager.ts): `packages/aiCore/src/core/plugins/manager.ts`

### Knowledge management

- [Document ingestion](https://github.com/iwindy/cherry-studio/blob/main/src/main/features/knowledge/ingestion/KnowledgeIngestionService.ts): `src/main/features/knowledge/ingestion/KnowledgeIngestionService.ts`
- [Knowledge file storage](https://github.com/iwindy/cherry-studio/blob/main/src/main/features/knowledge/pathStorage.ts): `src/main/features/knowledge/pathStorage.ts`
- [Knowledge search](https://github.com/iwindy/cherry-studio/blob/main/src/main/features/knowledge/query/KnowledgeQueryService.ts): `src/main/features/knowledge/query/KnowledgeQueryService.ts`
- [Knowledge index](https://github.com/iwindy/cherry-studio/tree/main/src/main/features/knowledge/pipeline/vectorstore): `src/main/features/knowledge/pipeline/vectorstore`

### Providers and integrations

- [Provider registry](https://github.com/iwindy/cherry-studio/blob/main/packages/provider-registry/src/registry-loader.ts): `packages/provider-registry/src/registry-loader.ts`
- [Provider extensions](https://github.com/iwindy/cherry-studio/blob/main/packages/aiCore/src/core/providers/core/ExtensionRegistry.ts): `packages/aiCore/src/core/providers/core/ExtensionRegistry.ts`
- [Local models](https://github.com/iwindy/cherry-studio/tree/main/src/main/ai/localModel): `src/main/ai/localModel`
- [MCP servers](https://github.com/iwindy/cherry-studio/blob/main/src/main/ai/runtime/agentMcpServers.ts): `src/main/ai/runtime/agentMcpServers.ts`
- [Remote protocol](https://github.com/iwindy/cherry-studio/blob/main/packages/remote-protocol/src/connection.ts): `packages/remote-protocol/src/connection.ts`

### Desktop experience

- [Resource catalog](https://github.com/iwindy/cherry-studio/blob/main/src/renderer/hooks/resourceCatalog/useResourceCatalogController.ts): `src/renderer/hooks/resourceCatalog/useResourceCatalogController.ts`
- [Conversation history](https://github.com/iwindy/cherry-studio/blob/main/src/renderer/components/history/useHistoryRecordsController.ts): `src/renderer/components/history/useHistoryRecordsController.ts`
- [Markdown rendering](https://github.com/iwindy/cherry-studio/blob/main/packages/ui/src/components/composites/markdown/markdown.tsx): `packages/ui/src/components/composites/markdown/markdown.tsx`
- [File management](https://github.com/iwindy/cherry-studio/blob/main/src/main/services/FileStorage.ts): `src/main/services/FileStorage.ts`

### Other components

- **Desktop user**

## Connections

- Desktop user → Conversation turn: sends turn
- Conversation turn → AI runtime: requests response
- AI runtime → Agent core: runs agent
- Agent core → Plugin engine: uses runtime
- Plugin engine → Plugin manager: executes hooks (evidence: `packages/aiCore/src/core/runtime/pluginEngine.ts`)
- Plugin engine → Provider extensions: resolves model
- Provider extensions → Provider registry: uses catalog
- AI runtime → Local models: supports local models
- AI runtime → MCP servers: uses MCP tools (evidence: `src/main/ai/runtime/claudeCode/ClaudeCodeWarmQueryManager.ts`)
- Desktop user → Document ingestion: adds documents
- Document ingestion → Knowledge file storage: copies and checks files (evidence: `src/main/features/knowledge/ingestion/KnowledgeIngestionService.ts`)
- Desktop user → Knowledge search: searches knowledge
- Knowledge search → Knowledge index: queries index (evidence: `src/main/features/knowledge/query/KnowledgeQueryService.ts`)
- Desktop user → Resource catalog: manages resources
- Desktop user → Conversation history: reviews conversations
- AI runtime → Markdown rendering: renders response
- Desktop user → File management: manages files
- AI runtime → Remote protocol: supports remote access
