Eve library

Real-Time Chat Synchronization Architecture

Guide

Revision 1

On this page

Overview#

This document outlines the architecture for real-time chat synchronization between web and mobile platforms in the Lilith meditation platform.

Current State Analysis#

Existing Infrastructure#

  • Web Platform: SSE streaming, WebSocket client, offline sync queue
  • Mobile Platform: ChatScreen with VoiceChatInterface, streaming support
  • Backend: WebSocket server, SSE streaming, thread management API

Identified Gaps#

  1. No shared state between web and mobile clients
  2. No cross-platform real-time event system
  3. No conflict resolution for concurrent operations
  4. Limited offline synchronization across platforms
  5. No unified read status and message delivery tracking

Architecture Design#

1. Message Bus Layer#

typescript
interface MessageBusEvent {
  id: string;
  type: 'message_sent' | 'message_read' | 'thread_updated' | 'user_typing';
  userId: string;
  threadId: string;
  timestamp: string;
  data: any;
  platforms: ('web' | 'mobile')[];
}

interface MessageBus {
  publish(event: MessageBusEvent): Promise<void>;
  subscribe(
    userId: string,
    callback: (event: MessageBusEvent) => void
  ): () => void;
  getUnreadEvents(userId: string, platform: string): Promise<MessageBusEvent[]>;
}

2. Synchronization Service#

typescript
interface SyncService {
  // Real-time synchronization
  syncMessage(messageId: string, platforms: string[]): Promise<void>;
  syncThreadState(threadId: string): Promise<void>;
  syncUserState(userId: string): Promise<void>;

  // Conflict resolution
  resolveMessageConflict(conflict: MessageConflict): Promise<Resolution>;

  // Offline synchronization
  queueOfflineOperation(operation: SyncOperation): Promise<void>;
  processOfflineQueue(userId: string): Promise<void>;
}

3. Shared State Manager#

typescript
interface SharedChatState {
  threads: Map<string, ThreadState>;
  messages: Map<string, MessageState>;
  userPresence: Map<string, PresenceState>;
  lastSyncTime: Map<string, number>;
}

interface StateManager {
  getState(userId: string): Promise<SharedChatState>;
  updateState(userId: string, updates: StateUpdate): Promise<void>;
  subscribeToStateChanges(
    userId: string,
    callback: (state: SharedChatState) => void
  ): () => void;
}

Implementation Components#

1. WebSocket Connection Manager (Mobile)#

typescript
class MobileWebSocketManager {
  private ws: WebSocket | null = null;
  private reconnectAttempts = 0;
  private maxReconnectAttempts = 5;
  private heartbeatInterval: NodeJS.Timeout | null = null;

  async connect(userId: string): Promise<void>;
  async disconnect(): Promise<void>;
  private sendHeartbeat(): void;
  private handleReconnect(): void;
  private handleMessage(event: MessageEvent): void;
}

2. Cross-Platform Event System#

typescript
class CrossPlatformEventSystem {
  private eventQueue: MessageBusEvent[] = [];
  private subscribers: Map<string, Set<(event: MessageBusEvent) => void>> =
    new Map();

  publish(event: MessageBusEvent): void;
  subscribe(
    eventType: string,
    callback: (event: MessageBusEvent) => void
  ): () => void;
  processEventQueue(): void;
  private broadcastToPlatforms(event: MessageBusEvent): void;
}

3. Conflict Resolution Engine#

typescript
class ConflictResolver {
  resolveMessageConflict(
    localMessage: ChatMessage,
    remoteMessage: ChatMessage,
    conflictType: 'edit' | 'delete' | 'status'
  ): Resolution {
    switch (conflictType) {
      case 'edit':
        return this.resolveEditConflict(localMessage, remoteMessage);
      case 'delete':
        return this.resolveDeleteConflict(localMessage, remoteMessage);
      case 'status':
        return this.resolveStatusConflict(localMessage, remoteMessage);
    }
  }

  private resolveEditConflict(
    local: ChatMessage,
    remote: ChatMessage
  ): Resolution {
    // Last-write-wins with timestamp comparison
    return local.updated_at > remote.updated_at
      ? { action: 'keep_local', data: local }
      : { action: 'use_remote', data: remote };
  }
}

4. Offline Sync Manager#

typescript
class OfflineSyncManager {
  private operationQueue: SyncOperation[] = [];
  private isOnline = navigator.onLine;

  queueOperation(operation: SyncOperation): void;
  async processQueue(): Promise<void>;
  private async syncOperation(operation: SyncOperation): Promise<void>;
  private handleOnlineStatusChange(): void;
}

Data Flow#

Message Sending Flow#

  1. User Action: User sends message on any platform
  2. Local Optimistic Update: Message immediately appears in local UI
  3. Event Publishing: Message event published to message bus
  4. Cross-Platform Sync: Event broadcasted to all user's connected platforms
  5. Backend Persistence: Message saved to conversation service
  6. Conflict Resolution: Any conflicts resolved using timestamps
  7. State Update: All platforms update their local state

Message Reading Flow#

  1. Read Action: User reads message on platform A
  2. Read Status Event: Read status event published
  3. Cross-Platform Sync: Read status synced to platform B
  4. UI Update: Platform B updates message read status
  5. Notification Clear: Platform B clears corresponding notifications

Offline Flow#

  1. Offline Detection: Platform detects offline status
  2. Local Operations: Operations queued locally
  3. Sync Queue: Operations added to sync queue
  4. Reconnection: Platform comes back online
  5. Queue Processing: Offline operations processed in order
  6. Conflict Resolution: Any conflicts with server state resolved

Technical Specifications#

WebSocket Events#

typescript
interface WebSocketEvents {
  // Message events
  'message:sent': {
    messageId: string;
    threadId: string;
    content: string;
    timestamp: string;
  };
  'message:updated': { messageId: string; content: string; timestamp: string };
  'message:read': { messageId: string; userId: string; timestamp: string };

  // Thread events
  'thread:created': { threadId: string; title: string; timestamp: string };
  'thread:updated': {
    threadId: string;
    updates: Partial<Thread>;
    timestamp: string;
  };
  'thread:deleted': { threadId: string; timestamp: string };

  // Presence events
  'user:online': { userId: string; platform: string; timestamp: string };
  'user:offline': { userId: string; platform: string; timestamp: string };
  'user:typing': { userId: string; threadId: string; timestamp: string };

  // Sync events
  'sync:state': { userId: string; state: SharedChatState; timestamp: string };
  'sync:conflict': { conflict: MessageConflict; resolution: Resolution };
}

State Synchronization Schema#

typescript
interface SyncState {
  userId: string;
  threads: {
    [threadId: string]: {
      lastMessageId: string;
      unreadCount: number;
      lastSyncTime: string;
      platformStates: {
        web: { lastReadMessageId: string; lastSeenTime: string };
        mobile: { lastReadMessageId: string; lastSeenTime: string };
      };
    };
  };
  messages: {
    [messageId: string]: {
      readBy: {
        [userId: string]: {
          platforms: ('web' | 'mobile')[];
          readAt: string;
        };
      };
      editHistory: Array<{
        content: string;
        editedBy: string;
        editedAt: string;
        platform: string;
      }>;
    };
  };
}

Implementation Roadmap#

Phase 1: Core Infrastructure#

  1. WebSocket connection manager for mobile
  2. Cross-platform event system
  3. Basic message synchronization

Phase 2: Advanced Features#

  1. Conflict resolution engine
  2. Offline synchronization manager
  3. Read status synchronization

Phase 3: Optimization & Monitoring#

  1. Performance monitoring
  2. Connection health monitoring
  3. Analytics and metrics

Phase 4: Testing & Validation#

  1. Comprehensive E2E tests
  2. Performance testing
  3. Security validation

Security Considerations#

  1. Authentication: All WebSocket connections authenticated with JWT tokens
  2. Authorization: Users can only sync their own messages and threads
  3. Rate Limiting: WebSocket events rate-limited per user
  4. Data Validation: All sync events validated before processing
  5. Encryption: All WebSocket communications use TLS/WSS

Performance Optimizations#

  1. Message Batching: Multiple messages batched in single sync events
  2. Delta Sync: Only sync changed data, not full state
  3. Compression: WebSocket messages compressed when possible
  4. Connection Pooling: Reuse WebSocket connections across sessions
  5. Caching: Frequently accessed data cached locally

Monitoring & Observability#

  1. Connection Metrics: Track WebSocket connection health and uptime
  2. Sync Latency: Measure time between cross-platform sync events
  3. Conflict Rates: Monitor frequency and resolution of conflicts
  4. Offline Queue Size: Track size of offline operation queues
  5. Error Rates: Monitor sync errors and failures

Fallback Strategies#

  1. Polling Fallback: If WebSocket fails, fall back to HTTP polling
  2. Local Storage: Critical state stored locally for offline access
  3. Manual Refresh: Users can manually trigger sync if needed
  4. Conflict UI: User interface for resolving conflicts automatically
  5. Partial Sync: Sync what's possible if full sync fails