[RFC] 142 - Message Entity Separation: Three-Layer Message Architecture

[arvinxx]

📋 Summary

This RFC proposes a clean separation of message entities into three distinct types, each serving a specific purpose in the LobeChat architecture:

1. DB Message - Optimized for database persistence
2. UI Message - Optimized for frontend rendering
3. LLM Message - Optimized for AI provider consumption

This separation follows the principle of separation of concerns, enabling better scalability, maintainability, and flexibility for future business requirements.

🎯 Motivation

Current Problems

Previously, we used a single ChatMessage type across all layers of the application, which led to several issues:

1. Tight Coupling: Database schema, UI components, and LLM integration all depended on the same type, making changes risky and difficult
2. Bloated Types: The single type contained fields needed only in specific contexts (e.g., UI-only fields stored in DB)
3. Limited Flexibility: Adding new features often required changing the core message type, affecting all layers
4. Poor Performance: Storing UI-specific data in the database increased storage costs and query complexity
5. Unclear Responsibilities: It was unclear which layer "owned" certain fields and transformations

Benefits of Separation

By introducing three distinct message types, we achieve:

• Clear Boundaries: Each layer has its own optimized data structure
• Better Performance: Database stores only essential data; UI only processes what it needs
• Easier Extension: New features can be added to specific layers without affecting others
• Type Safety: TypeScript can enforce correct usage at each layer
• Maintainability: Changes to one layer don't ripple through the entire system

📐 Design

1. DB Message (DBMessageItem)

Purpose: Optimized for database persistence using relational database capabilities.

Location: packages/types/src/message/db/item.ts

Key Characteristics:

• Flat structure optimized for relational database storage
• Uses proper database types (e.g., Date instead of number for timestamps)
• Contains only fields that need to be persisted
• Leverages database relationships (foreign keys, joins) for complex data

Type Definition:

export interface DBMessageItem {
  // Core fields
  id: string;
  userId: string;
  content: string | null;
  role: string;

  // Timestamps
  createdAt: Date;
  updatedAt: Date;

  // Relationships
  sessionId: string | null;
  topicId: string | null;
  threadId: string | null;
  parentId: string | null;

  // Group chat
  agentId: string | null;

  // Metadata
  model: string | null;
  provider: string | null;
  metadata?: MessageMetadata | null;

  // Features
  favorite: boolean | null;
  reasoning: ModelReasoning | null;
  search: GroundingSearch | null;
  tools: any | null;
  error: any | null;

  // Observability
  traceId: string | null;
  observationId: string | null;
  quotaId: string | null;
  clientId: string | null;
}

Benefits:

• Efficient querying with proper indexes
• Easy to establish relationships between entities
• Normalized data structure reduces redundancy
• Media files (images, videos) stored in separate tables with proper foreign keys

2. UI Message (UIChatMessage)

Purpose: Optimized for frontend rendering and user interaction.

Location: packages/types/src/message/ui/chat.ts

Key Characteristics:

• Rich structure with nested data for easy rendering
• Contains computed/derived fields for UI convenience
• Uses JavaScript-friendly types (e.g., number for timestamps)
• Includes UI-specific metadata (e.g., loading states, error display info)

Type Definition:

export interface UIChatMessage {
  // Core fields
  id: string;
  content: string;
  role: UIMessageRoleType; // 'user' | 'assistant' | 'tool' | 'system' | 'supervisor'

  // Timestamps (number for easy JS manipulation)
  createdAt: number;
  updatedAt: number;

  // Metadata for display
  meta: MetaData;
  metadata?: MessageMetadata | null;

  // Rich media (denormalized for easy rendering)
  fileList?: ChatFileItem[];
  imageList?: ChatImageItem[];
  videoList?: ChatVideoItem[];

  // UI-specific features
  children?: AssistantContentBlock[];  // Grouped tool messages
  chunksList?: ChatFileChunk[];        // RAG chunks for display
  extra?: ChatMessageExtra;            // Extended UI data

  // Tool integration
  tools?: ChatToolPayload[];
  plugin?: ChatPluginPayload;
  pluginState?: any;
  pluginError?: any;

  // Group chat
  groupId?: string;
  agentId?: string | 'supervisor';
  targetId?: string | null;  // DM target

  // Thread support
  threadId?: string | null;
  parentId?: string;

  // Advanced features
  error?: ChatMessageError | null;
  reasoning?: ModelReasoning | null;
  search?: GroundingSearch | null;

  // RAG
  ragQuery?: string | null;
  ragQueryId?: string | null;
  ragRawQuery?: string | null;

  // Relationships
  sessionId?: string;
  topicId?: string;
  quotaId?: string;

  // Observability
  traceId?: string;
  observationId?: string;
  tool_call_id?: string;

  // Legacy (deprecated)
  files?: string[];  // Will be removed after migration
}

Benefits:

• All data needed for rendering is immediately available (no extra queries)
• Nested structures match React component hierarchies
• Easy to add UI-only features without database changes
• Type-safe with UI-specific enums and interfaces

3. LLM Message

Purpose: Optimized for consumption by AI providers (OpenAI, Anthropic, etc.).

Location: Transformations in packages/prompts and src/services/chat

Key Characteristics:

• Follows provider-specific formats (OpenAI message format, Anthropic format, etc.)
• Contains only information relevant to LLM generation
• Transforms UI message structure into provider-expected format
• Handles provider-specific features (function calling, vision, etc.)

Transformation Example:

// Transform UIChatMessage to OpenAI format
function toOpenAIMessage(uiMessage: UIChatMessage): OpenAIChatMessage {
  return {
    role: uiMessage.role,
    content: uiMessage.content,
    // Transform tool calls
    tool_calls: uiMessage.tools?.map(tool => ({
      id: tool.id,
      type: 'function',
      function: {
        name: tool.name,
        arguments: JSON.stringify(tool.arguments),
      },
    })),
    // Add images for vision models
    ...(uiMessage.imageList?.length && {
      content: [
        { type: 'text', text: uiMessage.content },
        ...uiMessage.imageList.map(img => ({
          type: 'image_url',
          image_url: { url: img.url },
        })),
      ],
    }),
  };
}

Benefits:

• Clean separation between internal representation and provider format
• Easy to support new providers with different message formats
• Can optimize for each provider's specific capabilities
• Keeps provider-specific logic isolated

🔄 Data Flow

Write Path (User sends a message)

User Input
  ↓
Create UIChatMessage (client)
  ↓
Transform to DBMessage
  ↓
Save to Database
  ↓
Return DBMessage
  ↓
Transform to UIChatMessage
  ↓
Display in UI

Read Path (Load conversation)

Database Query
  ↓
Fetch DBMessages + Relations (joins)
  ↓
Transform to UIChatMessages
  ↓
Render in UI Components

AI Generation Path

UIChatMessages (conversation history)
  ↓
Apply Context Engineering (filter, transform)
  ↓
Transform to LLM Messages (provider-specific)
  ↓
Send to AI Provider
  ↓
Receive LLM Response
  ↓
Create UIChatMessage from response
  ↓
Save as DBMessage
  ↓
Display in UI

🎁 Benefits

For Developers

1. Type Safety: TypeScript enforces correct usage at each layer
2. Clear Contracts: Each layer has well-defined input/output types
3. Easier Testing: Can test each layer independently with appropriate fixtures
4. Better IDE Support: Autocomplete shows only relevant fields for each context

For Database

1. Optimized Schema: Only store what needs to be persisted
2. Better Queries: Relational structure enables efficient joins
3. Reduced Storage: No UI-only data in database
4. Easier Migrations: Schema changes don't affect UI layer

For UI

1. Rich Data: All display data readily available
2. Flexible Structure: Easy to add UI-only features
3. Performance: No extra queries for related data
4. Simpler Components: Data structure matches component hierarchy

For LLM Integration

1. Provider Flexibility: Easy to support different providers
2. Optimized Payloads: Send only what each provider needs
3. Feature Parity: Can use provider-specific capabilities
4. Easier Testing: Mock LLM responses with provider-specific formats

⚠️ Considerations

Transformation Overhead

Issue: Converting between types adds runtime cost.

Mitigation:

• Transformations are simple field mappings (negligible cost)
• Can be optimized with memoization if needed
• Batch transformations for multiple messages
• Benefits of clean architecture outweigh minimal overhead

Keeping Types in Sync

Issue: Changes to one type may need to propagate to others.

Mitigation:

• Shared common types in packages/types/src/message/common
• Clear documentation of field ownership
• Tests ensure transformations are complete
• TypeScript catches missing field errors

Learning Curve

Issue: Developers need to understand three different types.

Mitigation:

• Clear naming: DBMessageItem, UIChatMessage, OpenAIChatMessage
• Documentation with examples
• Transformation utilities hide complexity
• IDE autocomplete guides usage