docs/README.md
| Document | Description |
|---|---|
| Contributing | How to contribute code |
| App Update Architecture | How clients check for updates through the managed release service, with channels and the release history feed |
| 🌿 Branching Strategy | Branch model for contributions, pull request guidelines, and version tag management targeting main |
| 🖥️ Develop | Developer environment setup covering IDE configuration, Windows symlink support, and project install steps |
| Feishu Notification Script | CLI script that sends Feishu webhook card notifications from GitHub Actions workflows, with command reference |
| Linux Packaging | Linux packaging flow using pinned better-sqlite3 prebuilds, with build commands and prebuild update steps |
| Test Plan | The Test Plan process for beta and rc testing, covering user participation and maintainer PR workflow |
| Document | Description |
|---|---|
| AI Reference | Entry point mapping the AI pipeline docs, src/main/ai code layout, chat-turn flow, runtimes, and key invariants |
| Adapter Family | How each endpoint config's adapterFamily field selects the @ai-sdk package, and the two write paths that set it |
| Adding an Agent Runtime | Operational checklist for adding an agent runtime via a capability descriptor and a main-process driver package |
| Agent Loop | The Agent class wrapping single-pass AI SDK streaming with composeHooks-merged hook contributions and error semantics |
| Agent Prompt Layers | Precedence and lifecycle of agent prompt sources — System Prompt, workspace system.md, SOUL.md persona, and variables |
| Agent Session Runtime | Host/driver split for agent sessions — turn lifecycle, follow-up queue, resume tokens, and shared prompt materializer |
| AI Usage Records | Immutable ai_usage_record analytics — capture ownership, frozen attribution snapshots, and MessageStats projection |
| Chat Attachments | Per-attachment routing to native file parts or capped extracted text, with read_file paging for truncated overflow |
| Core Architecture | End-to-end chat turn flow from renderer IPC transport through AiStreamManager and Agent loop to persistence |
| Execution Overlay | Renderer stream overlay — TopicStreamSubscription demux by execution and anchor feeding readUIMessageStream snapshots |
| Image-Generation Parameterized Architecture | Data-driven image-generation params — registry supports to form fields, canonical bag to vendor wire via WireProfile |
| IPC Transport | IpcChatTransport bridging useChat to Main over ai.stream.* IpcApi routes, with dispatch ack coordination and detach vs abort |
| Model Retry & Fallback | User-configurable same-model retry plus fallback models via ai-retry wrapModel, driven by chat.retry.* preferences |
| Observability | OTel tracing for AI calls and agent runtimes — Cherry roots, SDK adapters, runtime spans, local projection, and sinks |
| Params Pipeline | buildAgentParams and the RequestFeature model composing plugins, tools, hooks, and provider quirks per request |
| Provider Resolution | Endpoint resolution chain from provider.endpointConfigs and adapterFamily to the AI SDK provider id and variants |
| AiStreamManager | AiStreamManager active-stream registry — listener fan-out, reconnect replay, abort, steering, and persistence triggers |
| Tool Approval | Main-as-writer tool approval through ai.tool.respond_approval, approval-requested parts, and persistent MCP decisions |
| Tool Registry | Unified aiSdk ToolEntry registry — built-in web/kb tools, MCP sync, meta-tools, and deferred exposition |
| Document | Description |
|---|---|
| API Gateway Reference | Local HTTP gateway for OpenAI, Anthropic, Gemini, Cherry REST, and MCP-compatible clients |
| Document | Description |
|---|---|
| Architecture Overview | Cross-process architecture entry point covering the Electron process model, data flow, data systems, and monorepo map |
Main Process Architecture (src/main) | Canonical reference for src/main top-level directories, the closed category set, and inter-directory dependency rules |
| Naming Conventions | Authoritative naming rules for files, directories, and identifiers, including singular/plural and barrel policies |
| Renderer Architecture | Canonical reference for the src/renderer type-by-domain layout and its strictly downward dependency layering |
Shared Layer Architecture (src/shared / @shared) | Defines what belongs in the @shared cross-process primitive layer, its closed top-level set, and import rules |
| Document | Description |
|---|---|
| BinaryManager Reference | Lifecycle service that acquires third-party CLI binaries through mise, with tool registry, snapshots, and IPC |
| Document | Description |
|---|---|
| Chat Reference | Current chat-domain map covering shared renderer modules, page-owned adapters, rich clipboard, and the message tree |
| Composer Rich Clipboard | Private clipboard format that preserves composer tokens across copy/paste between message surfaces and the composer |
| Message Tree | Message-tree model for topic chat: adjacency list, virtual root, sibling groups, invariants, delete semantics |
| Document | Description |
|---|---|
| Command System | Current command-backed action model across shared definitions, renderer and main handlers, keybindings, and menus |
| Command System — Usage | How to consume command UI and hooks, register handlers and context keys, build menus, and add a command |
| Document | Description |
|---|---|
| Components Reference | Entry point for component references covering code block rendering, code execution, image previews, and data-ui |
| Code Block Rendering | How CodeBlock classifies Markdown code and CodeBlockView renders the fenced-code workbench across streaming states |
| Code Execution | Current Python code-block execution path through CodeBlockView, PyodideService, and the Pyodide Web Worker |
| Image Preview Components | Current Mermaid, PlantUML, SVG, and Graphviz preview pipeline with sanitized Shadow DOM rendering and shared controls |
| UI Semantic Contract | The data-ui semantic selector contract for themes, tests, and automation, and its build-time generation pipeline |
| Document | Description |
|---|---|
| Data System Reference | Entry point for Cherry Studio data systems - decision guide across BootConfig, Cache, Preference, DataApi, app_state |
| API Design Guidelines | RESTful path, status code, Zod DTO, and scope/side-effect boundary rules for designing DataApi endpoints |
| Data API Type System | DataApi type system reference - request/response types, path resolution, pagination types, and error handling |
| App State System Overview | app_state SQLite table for durable owner-private completion and reconciliation markers |
| Default Values & Nullability | Rules for column nullability and single-source default placement across DB, Drizzle, Zod, and service layers |
| Layered Preset Configuration Pattern | Current preset layering patterns for Preference-backed catalogs and SQLite-backed entities |
| Boot Config System Overview | Synchronous file-based BootConfig system for process-level settings loaded before the app lifecycle starts |
| Boot Config Schema Guide | How to add boot config keys to the auto-generated schema, plus the V1-to-V2 boot config migration pipeline |
| Cache System Overview | Three-tier cache architecture (memory, shared, persist) - key types, design invariants, process responsibilities |
| Cache Schema Guide | Adding fixed and template cache keys to the cache schemas - naming rules and fixed/template/casual selection |
| Cache Usage Guide | Cache usage examples - useCache/useSharedCache/usePersistCache hooks and direct CacheService APIs per tier |
| DataApi in Main Process | Implementing DataApi handlers and services in main - HandlersFor typing, cross-service table access, adapters |
| DataApi in Renderer | Renderer DataApi usage - useQuery, useMutation, useInfiniteQuery hooks and data change notifications |
| DataApi System Overview | DataApi architecture for SQLite-backed business data - typed IPC pipeline from renderer client to main handlers |
| Ordering Guide | Fractional-indexing ordering spec for sortable resources - orderKey column, order endpoints, and useReorder hook |
| Pagination Guide | Canonical pagination spec - offset vs cursor (keyset) modes, wire contract, server codec, and renderer hooks |
| Database Construction (Build, Migrations, Custom SQL, FTS5) | How the SQLite DB is built at boot - drizzle migrations, CUSTOM_SQL_STATEMENTS replay, FTS5 fts_rowid, rebuilds |
| Database Schema Guidelines | Database schema authoring patterns - file organization, naming, column helpers, write serialization (withWriteTx) |
| Database Seeding Guide | Seeding architecture - SeedRunner journal in app_state, execution policies, version strategies, adding seeders |
| Preference System Overview | Preference architecture - generated key schema, SQLite ownership, BootConfig routing, renderer cache, and cross-window sync |
| Preference Schema Guide | How to add Preference keys through the data-classify generator without editing generated schemas |
| Preference Usage Guide | Current usePreference, useMultiplePreferences, and direct PreferenceService APIs |
| Migration V2 (Main Process) | One-shot v1-to-v2 migration engine - upgrade gate, migrator contracts, data source readers, status tracking |
| Document | Description |
|---|---|
| Performance Diagnostics | Opt-in main-process performance instrumentation gated by CS_DIAGNOSTICS, with signals and CPU profile capture |
| Document | Description |
|---|---|
| File Reference | Entry point for current FileManager, directory-tree, cleanup, watcher, and directory-search references |
| File Module Architecture | Current file-domain boundaries, shared types, renderer transports, and business-reference ownership |
| Directory Tree Architecture | Live directory-tree snapshots, watcher mutations, IpcApi ownership, and renderer mirror lifecycle |
| File Entry Cleanup | Scan-based cleanup of unreferenced file entries using the per-entry cleanup policy |
| FileManager Architecture | Current FileManager storage, lifecycle, atomic-write, watcher, dangling-cache, and orphan-cleanup behavior |
| Fuzzy Search for Directory Listings | Current list and fuzzy-search behavior for the legacy directory-listing IPC methods |
| Document | Description |
|---|---|
| Internationalization (i18n) Guide | i18n workflow covering locale catalogs, the en-us source of truth, automation scripts, and translation practices |
| Document | Description |
|---|---|
| IpcApi Reference | Entry point for IpcApi docs — subsystem boundary, naming quick reference, migration status, and doc navigation |
| IpcApi Migration Guide | Per-domain migration of legacy ipcMain and preload channels into IpcApi schemas, handlers, and renderer call sites |
| IpcApi Overview | Why IpcApi is an independent RPC channel beside REST DataApi — layering, trust boundary, IpcContext, error model |
| IpcApi Schema Guide | Authoring IpcApi schemas — per-domain files, route and event naming rules, derived types, ESLint key enforcement |
| IpcApi Usage | Adding an IpcApi request route or main-to-renderer event — schema, handler, broadcast and send, useIpcOn subscribe |
| Document | Description |
|---|---|
| Job & Scheduler | Entry point for the job and scheduler docs — doc map and quick navigation for JobManager and SchedulerService |
| Concurrency & Locks (Four-Layer Model) | Four-layer lock model for JobManager dispatch — write transactions, queue mutex, concurrency caps, business locks |
| Handler Authoring | Writing a JobHandler — onInit registration timing, minimal echo example, and JobRegistry type binding |
| Migration Checklist | Per-handler checklist for migrating existing background services to JobManager — recovery, queues, tests, data moves |
| Job & Scheduler — Architecture Overview | Job and scheduler architecture — two-service split, DB-driven dispatch, six-state machine, and startup recovery |
| Scheduler Usage — Decision Tree | Decision tree for choosing JobManager, SchedulerService, BaseService.registerInterval, or a raw timer |
| Document | Description |
|---|---|
| Knowledge Reference | Entry point for the current Knowledge backend, ingestion workflow, retrieval, and operation guards |
| Knowledge Service | Current Knowledge backend - persistence, IPC, ingestion, retrieval, Concept IDs, and agent tools |
| Knowledge Operation Guards | Guard and recovery semantics for Knowledge add, delete, reindex, and embedding-enable operations |
| Knowledge Workflow Architecture | Knowledge workflow architecture: scheduling model, durable JobManager jobs, per-base mutation lock, crash semantics |
| Knowledge Storage and Retrieval Implementation | Current Knowledge storage and retrieval implementation - raw files, per-base index schema, invariants, and migration validation |
| Document | Description |
|---|---|
| Cherry Studio LAN Transfer Protocol Specification | LAN transfer protocol spec for desktop-mobile sync covering mDNS discovery, TCP handshake, and file transfer |
| Document | Description |
|---|---|
| Lifecycle & Application Reference | Entry point for lifecycle docs — pattern decision table, doc navigation, and lifecycle vs direct-import singleton rules |
| Application Overview | How the Application orchestrator registers services, runs the three-phase bootstrap, and controls runtime shutdown |
| Lifecycle Decision Guide | Decision framework for whether a main-process service belongs in the lifecycle system or stays a plain singleton |
| Lifecycle Migration Guide | Converting legacy singleton, raw-new, and free-function services to lifecycle decorators and registry entries |
| Lifecycle Overview | Lifecycle internals — bootstrap phases, hooks, service states, events, and parallel initialization ordering |
| Lifecycle Usage Guide | Code examples for lifecycle decorators, IPC and timer helpers, error handling, conditional activation, pause/resume |
| Document | Description |
|---|---|
| How to use the LoggerService | How to log through the unified LoggerService in main and renderer, with levels, contexts, and env filtering |
| Document | Description |
|---|---|
| Provider & Model Reference | Home for provider and model reference docs covering the preset registry and its merge with user data |
| Provider & Model Registry System | How preset provider and model registry data is loaded, normalized, seeded, and merged with user data |
| Document | Description |
|---|---|
| Security Reference | Home for security reference docs covering safe main-process handling of untrusted network input |
| Remote Fetch Safety | SSRF-safe rules for main-process fetches of untrusted URLs, with DNS pinning and private-address rejection |
| Document | Description |
|---|---|
| Testing Reference | Home for testing reference docs covering frontend test policy and the SQLite database test harness |
| Database Testing Guide | How to test SQLite-backed main-process code with the setupTestDatabase harness and production migrations |
| Frontend Testing Guidelines | Normative test rules for renderer, packages/ui, and E2E code covering layer choice, mocking, and review gates |
| Document | Description |
|---|---|
| WindowManager Reference | Entry point for WindowManager docs — configuration layers, bounds persistence, runtime setters, and doc navigation |
| WindowManager API Reference | Full WindowManager method tables — open/close/create/destroy, window ops, queries, broadcast, pools, behavior setters |
| Window Migration Guide | Migrating direct BrowserWindow creation to WindowManager — WindowType enum, registry entry, and open/close call sites |
| WindowManager Overview | WindowManager architecture — core type relationships, the three lifecycle modes, and the event timing contract |
| Window Platform Configuration | Per-window platform configuration — static platformOverrides, declarative behavior layer, and macOS quirks patches |
| WindowManager Usage Guide | Consumer guide for WindowManager — registering window types, opening windows, event hooks, and useWindowInitData |
| Warmup Mechanics | Warmup state machine for pooled and singleton windows — idle queue, GC ticks, standby vs recycle axes, reuse IPC |