# Real-Time Chat Synchronization Architecture

## 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
