Architecture Overview

Note: main is undergoing a major v2 architecture refactoring (v1 and v2 coexist). This document is updated as it progresses; some sections describe the target architecture rather than the current state.

This is the cross-process entry point to Cherry Studio's architecture: the Electron process model, data flow, the data systems, the monorepo structure, and a map to the detailed per-process and per-subsystem references. Per-process directory layout and dependency rules live in their own documents — this page does not duplicate them.

Process Model

Cherry Studio is an Electron app with two app processes (plus preload), each mapping to a src/ root and its top-level directories:

═══ Main Process · Node.js · src/main/ ══════════════════════════════════

  core/       app runtime — IoC container, paths, logger, window, scheduler/jobs
  data/       data layer — Db, Cache, Preference, DataApi, BootConfig
  ai/         AI subsystem — providers, middleware, MCP, agents, streams
  features/   large domain modules    ·    services/  small business services
  ipc/        IpcApi — the typed boundary to the renderer
  (also hosts: Express API server · MCP servers · knowledge / RAG)

                   ↕   IPC over contextBridge   ·   src/preload/

═══ Renderer Process · Chromium · src/renderer/ ═════════════════════════

  windows/     per-window entry roots — Main, Sub, Selection, …
  pages/       route views — Chat, Agent, Settings, …
  features/    domain UI modules
  data hooks   useQuery / useMutation / usePreference / useCache
  ai core      provider middleware
  UI           React 19 · Shadcn UI · Tailwind · TipTap

Data Flow

A typical user interaction follows this path:

User Input (React UI)
  │
  ├── Chat Message ──→ AI Core (provider middleware) ──→ LLM API
  │                        │
  │                        ├── Stream chunks ──→ renderer chat state ──→ UI update
  │                        └── Message blocks ──→ DataApi ──→ SQLite (persist)
  │
  ├── Setting Change ──→ usePreference ──→ IPC ──→ PreferenceService ──→ SQLite
  │                                                    └── broadcast to all windows
  │
  └── Business Data ──→ useQuery / useMutation ──→ IPC ──→ DataApi handler
       (topics, files)                                       │
                                                             ├── Service layer
                                                             ├── Repository layer
                                                             └── SQLite (Drizzle ORM)

Four Data Systems

Cherry Studio uses four data systems, each optimized for different data characteristics:

System	Storage	Timing	Use Case
BootConfig	JSON file	Pre-lifecycle (sync)	Chromium flags, hardware accel
Cache	Memory (per-process) / Shared (Main-relayed) / Persist (renderer localStorage)	Runtime	Temp data, UI state, cross-window coordination
Preference	SQLite	Post-lifecycle	User settings (theme, language)
DataApi	SQLite (Drizzle)	Post-lifecycle	Business data (topics, messages)

See Data System Reference for detailed architecture, decision flowcharts, and usage patterns.

Service Lifecycle

Main-process services that own long-lived resources or persistent side effects run on an IoC container with a phased bootstrap (Background → BeforeReady → WhenReady), registered one line each in src/main/core/application/serviceRegistry.ts and resolved via application.get('ServiceName'). See Lifecycle Reference for the phases, decorators, and migration guide; see Main Process Architecture for where services sit in the directory layout.

AI Core Architecture

The AI pipeline selects a provider, runs a middleware chain (context, knowledge, tools), streams via the Vercel AI SDK, and emits typed message blocks (text, code, image, tool-call). See AI Reference for the full pipeline and data flow.

Monorepo Structure

cherry-studio
├── src/
│   ├── main/                    # Main process (Node.js) — directory layout in ./main-process-architecture.md
│   │
│   ├── renderer/                # Renderer process (React) — directory layout in ./renderer-architecture.md
│   │
│   ├── preload/                 # Preload scripts (IPC bridge)
│   │
│   └── shared/                  # Cross-process primitives: types, schemas/contracts, pure logic — layout in ./shared-layer-architecture.md
│
├── packages/
│   ├── ui/                      #   @cherrystudio/ui (Shadcn + Tailwind)
│   ├── aiCore/                  #   @cherrystudio/ai-core
│   ├── ai-sdk-provider/         #   Custom AI SDK providers
│   ├── provider-registry/       #   Provider registry
│   ├── mcp-trace/               #   OpenTelemetry tracing
│   └── extension-table-plus/    #   TipTap table extension
│
├── docs/                        # Documentation (this directory)
│   ├── guides/                  #   How-to guides
│   └── references/              #   Technical references
│
└── scripts/                     # Build, lint, i18n, and CI scripts

Main-process and renderer code is organized by feature (features/ — high-cohesion domain modules) versus type-bucket (services/, utils/, components/, hooks/ — small, independent pieces); see Naming Conventions §4.10 for the placement rule. src/shared/ is the cross-process primitive layer — types, schemas/contracts, and pure logic importable by both main and renderer, depending on no app code (being cross-process is the entry gate). Full layering and dependency rules live in the per-process docs below.

Reference Map

Where to go for detail. The three process docs own per-process directory layout and dependency rules; subsystem internals live in their own references.

Area	Reference
Main-process directory charters & dependency rules	Main Process Architecture
Renderer directory layering & dependency rules	Renderer Architecture
Cross-process primitives (`@shared`)	Shared Layer Architecture
Naming (files, directories, identifiers)	Naming Conventions
Data systems (BootConfig / Cache / Preference / DataApi)	Data System Reference
IPC (IpcApi)	IPC Reference
Service lifecycle (IoC, phased bootstrap)	Lifecycle Reference
Window manager (multi-window, pooling)	Window Manager Reference
Scheduler & jobs	Job & Scheduler Reference
AI subsystem	AI Reference
Path registry	paths/README

Cherry Studio runs multiple windows (main window, sub-windows, selection toolbar, …), all managed by WindowManager and communicating through IPC and shared state (Cache, Preference); see the Window Manager Reference.