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#
- No shared state between web and mobile clients
- No cross-platform real-time event system
- No conflict resolution for concurrent operations
- Limited offline synchronization across platforms
- 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#
- User Action: User sends message on any platform
- Local Optimistic Update: Message immediately appears in local UI
- Event Publishing: Message event published to message bus
- Cross-Platform Sync: Event broadcasted to all user's connected platforms
- Backend Persistence: Message saved to conversation service
- Conflict Resolution: Any conflicts resolved using timestamps
- State Update: All platforms update their local state
Message Reading Flow#
- Read Action: User reads message on platform A
- Read Status Event: Read status event published
- Cross-Platform Sync: Read status synced to platform B
- UI Update: Platform B updates message read status
- Notification Clear: Platform B clears corresponding notifications
Offline Flow#
- Offline Detection: Platform detects offline status
- Local Operations: Operations queued locally
- Sync Queue: Operations added to sync queue
- Reconnection: Platform comes back online
- Queue Processing: Offline operations processed in order
- 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#
- WebSocket connection manager for mobile
- Cross-platform event system
- Basic message synchronization
Phase 2: Advanced Features#
- Conflict resolution engine
- Offline synchronization manager
- Read status synchronization
Phase 3: Optimization & Monitoring#
- Performance monitoring
- Connection health monitoring
- Analytics and metrics
Phase 4: Testing & Validation#
- Comprehensive E2E tests
- Performance testing
- Security validation
Security Considerations#
- Authentication: All WebSocket connections authenticated with JWT tokens
- Authorization: Users can only sync their own messages and threads
- Rate Limiting: WebSocket events rate-limited per user
- Data Validation: All sync events validated before processing
- Encryption: All WebSocket communications use TLS/WSS
Performance Optimizations#
- Message Batching: Multiple messages batched in single sync events
- Delta Sync: Only sync changed data, not full state
- Compression: WebSocket messages compressed when possible
- Connection Pooling: Reuse WebSocket connections across sessions
- Caching: Frequently accessed data cached locally
Monitoring & Observability#
- Connection Metrics: Track WebSocket connection health and uptime
- Sync Latency: Measure time between cross-platform sync events
- Conflict Rates: Monitor frequency and resolution of conflicts
- Offline Queue Size: Track size of offline operation queues
- Error Rates: Monitor sync errors and failures
Fallback Strategies#
- Polling Fallback: If WebSocket fails, fall back to HTTP polling
- Local Storage: Critical state stored locally for offline access
- Manual Refresh: Users can manually trigger sync if needed
- Conflict UI: User interface for resolving conflicts automatically
- Partial Sync: Sync what's possible if full sync fails