cherry-studio/packages/shared/data/README.md

Cherry Studio Shared Data

This directory contains shared data structures and API type definitions for the Cherry Studio application. It includes both persistent data schemas and API contract definitions.

📁 File Organization

Persistent Data (Root Level)

• preferences.ts - User preference data schema and default values
• preferenceTypes.ts - TypeScript types for preference system

API Types (api/ subdirectory)

• api/index.ts - Barrel export file providing clean imports for all API types
• api/apiTypes.ts - Core request/response types and API infrastructure
• api/apiModels.ts - Business entity types and Data Transfer Objects (DTOs)
• api/apiSchemas.ts - Complete API endpoint definitions with type mappings
• api/errorCodes.ts - Error handling utilities and standardized error codes

🏗️ Architecture Overview

These files are part of the Renderer-Main Virtual Data Acquisition Architecture that enables:

• Type-safe IPC communication between Electron processes
• RESTful API patterns within the Electron application
• Standardized error handling across the application
• Future extensibility to standalone API servers

🔄 Classification Status

Important: These files are NOT classified in the data refactor system because they are:

• ✅ Type definitions - Not actual data storage
• ✅ Compile-time artifacts - Exist only during TypeScript compilation
• ✅ Framework infrastructure - Enable the data API architecture
• ✅ Development tools - Similar to interfaces in other languages

📖 Usage Examples

Basic Imports

// Import API types from the api subdirectory
import { 
  Topic, 
  CreateTopicDto, 
  DataRequest, 
  ApiSchemas,
  ErrorCode 
} from '@shared/data/api'

// Import specific groups
import type { TopicTypes, MessageTypes } from '@shared/data/api'

// Import preferences
import type { UserPreferences } from '@shared/data/preferences'

API Schema Usage

import type { ApiSchemas, ApiResponse } from '@shared/data/api'

// Get the response type for a specific endpoint
type TopicsListResponse = ApiResponse<'/topics', 'GET'>
// Result: PaginatedResponse<Topic>

type CreateTopicResponse = ApiResponse<'/topics', 'POST'>  
// Result: Topic

Error Handling

import { DataApiErrorFactory, ErrorCode, isDataApiError } from '@shared/data/api'

// Create standardized errors
const notFoundError = DataApiErrorFactory.notFound('Topic', '123')
const validationError = DataApiErrorFactory.validation({
  title: ['Title is required']
})

// Check if error is a Data API error
if (isDataApiError(error)) {
  console.log(`Error ${error.code}: ${error.message}`)
}

Request/Response Types

import type { DataRequest, DataResponse, PaginatedResponse, Topic } from '@shared/data/api'

// Type-safe request construction
const request: DataRequest = {
  id: 'req_123',
  method: 'GET',
  path: '/topics',
  params: { page: 1, limit: 10 }
}

// Type-safe response handling
const response: DataResponse<PaginatedResponse<Topic>> = {
  id: 'req_123',
  status: 200,
  data: {
    items: [...],
    total: 100,
    page: 1,
    pageCount: 10,
    hasNext: true,
    hasPrev: false
  }
}

🔧 Development Guidelines

Adding New Domain Models

1. Add the interface to api/apiModels.ts
2. Create corresponding DTOs (Create/Update)
3. Export from api/index.ts
4. Update API schemas if needed

// In api/apiModels.ts
export interface NewEntity {
  id: string
  name: string
  createdAt: string
  updatedAt: string
}

export interface CreateNewEntityDto {
  name: string
}

Adding New API Endpoints

1. Add endpoint definition to api/apiSchemas.ts
2. Include JSDoc comments with examples
3. Ensure all types are properly referenced

// In api/apiSchemas.ts
export interface ApiSchemas {
  /**
   * New entity endpoint
   * @example GET /entities?page=1&limit=10
   */
  '/entities': {
    /** List all entities */
    GET: {
      query?: PaginationParams
      response: PaginatedResponse<NewEntity>
    }
  }
}

Type Safety Best Practices

• Always use import type for type-only imports
• Leverage the type helpers (ApiResponse, ApiParams, etc.)
• Use the barrel export for clean imports
• Document complex types with JSDoc comments

🔗 Related Files

Main Process Implementation

• src/main/data/DataApiService.ts - Main process data service
• src/main/data/api/ - Controllers, services, and routing

Renderer Process Implementation

• src/renderer/src/data/DataApiService.ts - Renderer API client
• src/renderer/src/data/hooks/ - React hooks for data fetching

Shared Data Types

• packages/shared/data/api/ - API contract definitions
• packages/shared/data/preferences.ts - User preference schemas

Architecture Documentation

• .claude/data-request-arch.md - Complete architecture documentation
• CLAUDE.md - Project development guidelines

🚀 Future Enhancements

The type system is designed to support:

• HTTP API Server - Types can be reused for standalone HTTP APIs
• GraphQL Integration - Schema can be mapped to GraphQL resolvers
• Real-time Subscriptions - WebSocket/SSE event types are defined
• Advanced Caching - Cache-related types are ready for implementation

---

This README is part of the Cherry Studio data refactor project. For more information, see the project documentation in .claude/ directory.