CherryStudio v2: Data & UI Refactoring

[0xfullex]

CherryStudio v2 including Data Refactoring and UI Refactoring.

This is the largest code refactoring project in Cherry Studio's history

Guide

Production Plan

The v2 is scheduled for release in v2.0.0.

• All existing (non-data&ui-refactoring) features will be fully released by v2.0.0 or earlier.
• Starting from v1.6.0, only bug fixes (and Agent feature in v1.7.0) will be deployed, with no other features or refactoring releases, to ensure a stable environment for data&ui refactoring.
• After the v2.0.0 data&ui refactoring release, intensive bug fixes related to the refactoring will follow. Once the mainline bug fixes are complete, development of other features and refactoring will resume.

Contribution

Welcome developers to refactor the features or modules they have maintained according to the new data architecture and UI architecture, which will greatly accelerate our refactoring efforts.

If you'd like to optimize existing code, please submit your changes via a PR to the v2 branch.

We will ultimately use the merge commits method to merge v2 into the main branch, which will preserve each of your PR commits and count them toward your contributions.

Data Refactoring

Coordinator: @0xfullex

Fundamentally transforming the data architecture of Cherry Studio (including data structures, storage, transmission, and usage). After the refactoring, Cherry Studio's data performance, stability, and security will be significantly improved.

Since the data affects all features and modules, this means all features and modules will also undergo refactoring and optimization alongside the data changes.

Run & Test

Currently in the testing phase, data migration will occur automatically, but no additions, deletions, or modifications will be made to the original data.
This means both old and new data coexist, and you can switch back to other branches at any time without issues or concerns.

To test the data migration process again, you can delete the cherrystudio.sqlite file in the data directory.

Progress

Overall progress: 23%

Category	Difficulty	Workload %	Architecture Design	Architecture Implementation	Code Migration	Test	Documentation
Runtime/Cache	Medium	10%	✅	✅	90%
Preferences	High	30%	✅	✅	WIP: 30%
User Data	Very High	45%	50%	30%
Migrations	High	10%	30%	30%	30%
Backups	Medium	5%

File Structure

Note: Data refactoring is still in progress, and related APIs may change before the v2 launch.

For renderer use: README.md

src/renderer/src/data/
├── DataApiService.ts       # User Data API querying service
├── PreferenceService.ts    # Preferences management
├── CacheService.ts         # Three-tier caching system
└── hooks/
    ├── useDataApi.ts       # React hooks for user data operations
    ├── usePreference.ts    # React hooks for preferences
    └── useCache.ts         # React hooks for caching

For main use: README.md

src/main/data/
├── api/                    # Data API framework
│   ├── core/              # Core API infrastructure
│   │   ├── ApiServer.ts   # Request routing and handler execution
│   │   ├── MiddlewareEngine.ts # Request/response middleware
│   │   └── adapters/      # Communication adapters
│   ├── handlers/          # API endpoint implementations
│   └── index.ts          # API framework exports
├── services/                  # Business logic layer
├── repositories/              # Data access layer (selective usage)
├── db/                    # Database layer
│   ├── schemas/          # Drizzle table definitions
│   ├── seeding/          # Database initialization
│   └── DbService.ts      # Database connection and management
├── migrate/              # Data migration system
│   └── dataRefactor/     # v2 data refactoring migration tools
├── CacheService.ts       # Main process cache management
├── DataApiService.ts     # Data API coordination service
└── PreferenceService.ts  # User preferences management

For shared types: README.md

packages/shared/data/
├── api/                     # Data API type system
│   ├── index.ts            # Barrel exports for clean imports
│   ├── apiSchemas.ts       # API endpoint definitions and mappings
│   ├── apiTypes.ts         # Core request/response infrastructure types
│   ├── apiModels.ts        # Business entity types and DTOs
│   ├── apiPaths.ts         # API path definitions and utilities
│   └── errorCodes.ts       # Standardized error handling
├── cache/                   # Cache system type definitions
│   ├── cacheTypes.ts       # Core cache infrastructure types
│   ├── cacheSchemas.ts     # Cache key schemas and type mappings
│   └── cacheValueTypes.ts  # Cache value type definitions
├── preference/              # Preference system type definitions
      ├── preferenceTypes.ts  # Core preference system types
      └── preferenceSchemas.ts # Preference schemas and default values

UI Refactoring

Coordinator: @MyPrototypeWhat

Migration Strategy Update:

From: antd + styled-components + HeroUI → To: shadcn/ui + Tailwind CSS
Approach: Progressive migration based on component extraction criteria
Design System: Custom CSS variables integrated with Tailwind CSS

Component Extraction Criteria:

Only migrate components that meet our extraction standards (usage ≥ 3, future reusability, etc.)
Focus on primitives, icons, and composites architecture
Prioritize backward compatibility and designer collaboration

Migration Steps

Phase	Status	Main Tasks	Description
Phase 1	✅ Completed	Design System Integration	• Converted design tokens from todocss.css to tokens.css with --cs-* namespace • Created theme.css mapping all design tokens to standard Tailwind classes • Extended Tailwind with semantic spacing (5xs8xl) and radius (4xs3xl) systems • Established two usage modes: full override and selective override • Cleaned up main package's conflicting Shadcn theme definitions
Phase 2	⏳ In Progress	Component Migration and Optimization	• Filter components for migration based on extraction criteria • Remove antd dependencies, replace with shadcn/ui • Remove HeroUI dependencies, replace with shadcn/ui • Remove styled-components, replace with Tailwind CSS + design system variables • Optimize component APIs and type definitions
Phase 3	⏳ To Start	UI Refactoring and Optimization	• Gradually implement UI refactoring with UI designers • Ensure visual consistency and user experience • Performance optimization and code quality improvement

Directory Structure Guide

@packages/ui/
├── src/
│   ├── components/         # Main components directory
│   │   ├── primitives/     # Basic/primitive components (Avatar, ErrorBoundary, Selector, etc.)
│   │   │   └── shadcn-io/  # shadcn/ui components (dropzone, etc.)
│   │   ├── icons/          # Icon components (Icon, FileIcons, etc.)
│   │   └── composites/     # Composite components (CodeEditor, ListItem, etc.)
│   ├── hooks/              # Custom React Hooks
│   ├── styles/             # Global styles and CSS variables
│   ├── types/              # TypeScript type definitions
│   ├── utils/              # Utility functions
│   └── index.ts            # Main export file

Usage Example

After:

import {
  Scrollbar,
  Spinner,
  DividerWithText,
  VisionIcon
} from '@cherrystudio/ui'

// Use components
function MyComponent() {
  return (
    <Scrollbar>
      <DividerWithText text="Divider" />
      <Spinner text="Loading..." />
      <VisionIcon />
    </Scrollbar>
  )
}

Related Refactoring

System	Assignee	PR
App Router	@MyPrototypeWhat	#11460
Shortcuts	@beyondkmp	#11050
Backup	@GeorgeDong32
Knowledge Base	@eeee0717
Notes	@DeJeune
Agents
Provider/Model Info Structure	@DeJeune	#11420