System Design: Design a Messenger Web App — Real-Time Chat Architecture at Scale

MessengerApp
├── AppShell (responsive layout: sidebar + main panel)
│   ├── ConversationSidebar
│   │   ├── SearchBar (conversations + messages search)
│   │   ├── ConversationList (virtualized)
│   │   │   └── ConversationItem
│   │   │       ├── UserAvatar (online indicator dot)
│   │   │       ├── LastMessage (preview + timestamp)
│   │   │       ├── UnreadBadge (count)
│   │   │       └── TypingIndicator ("typing...")
│   │   └── NewConversationButton
│   └── ChatPanel
│       ├── ChatHeader (name, avatar, online status, actions)
│       ├── MessageList (reverse infinite scroll, virtualized)
│       │   ├── DateSeparator ("Today", "Yesterday", dates)
│       │   ├── MessageGroup (consecutive messages from same sender)
│       │   │   └── MessageBubble
│       │   │       ├── TextContent (with link detection)
│       │   │       ├── ImageContent (lightbox on click)
│       │   │       ├── FileAttachment (download button)
│       │   │       ├── VoiceNote (waveform + play button)
│       │   │       ├── LinkPreview (OG metadata card)
│       │   │       ├── ReplyContext (quoted message preview)
│       │   │       ├── ReactionBar (emoji reactions below message)
│       │   │       ├── MessageStatus (sent/delivered/read ticks)
│       │   │       └── MessageContextMenu (reply, react, forward, delete)
│       │   ├── TypingBubble (animated dots)
│       │   └── ScrollToBottom (floating button with unread count)
│       └── ComposerBar
│           ├── EmojiPicker
│           ├── AttachmentMenu (image, file, voice)
│           ├── TextInput (auto-resize, mentions autocomplete)
│           ├── VoiceRecorder (waveform, timer)
│           └── SendButton
├── ConnectionManager (WebSocket lifecycle)
├── NotificationManager (push + in-app)
└── OfflineManager (IndexedDB + sync queue)

class ConnectionManager {
  private ws: WebSocket | null = null;
  private reconnectDelay = 1000;
  private maxReconnectDelay = 30000;
  private heartbeatInterval: number | null = null;
  private pendingAcks = new Map<string, PendingMessage>();
  private messageBuffer: WSMessage[] = [];
  private connectionState: "connecting" | "connected" | "reconnecting" | "disconnected" = "disconnected";
  
  connect() {
    this.connectionState = "connecting";
    this.ws = new WebSocket(this.buildUrl());
    
    this.ws.onopen = () => {
      this.connectionState = "connected";
      this.reconnectDelay = 1000; // Reset backoff
      
      // Start heartbeat (detect dead connections)
      this.heartbeatInterval = window.setInterval(() => {
        if (this.ws?.readyState === WebSocket.OPEN) {
          this.ws.send(JSON.stringify({ type: "ping" }));
        }
      }, 30000);
      
      // Flush buffered messages (sent while disconnected)
      this.flushBuffer();
      
      // Request missed messages since last connection
      this.requestMissedMessages();
      
      this.emit("connected");
    };
    
    this.ws.onmessage = (event) => {
      const message: WSMessage = JSON.parse(event.data);
      this.handleMessage(message);
    };
    
    this.ws.onclose = (event) => {
      clearInterval(this.heartbeatInterval!);
      
      if (event.code !== 1000) { // Abnormal close
        this.connectionState = "reconnecting";
        this.scheduleReconnect();
      } else {
        this.connectionState = "disconnected";
      }
      
      this.emit("disconnected");
    };
  }
  
  private handleMessage(message: WSMessage) {
    switch (message.type) {
      case "message":
        // Deduplicate (same message might arrive twice after reconnect)
        if (this.processedIds.has(message.id)) return;
        this.processedIds.add(message.id);
        
        // Send delivery acknowledgment
        this.sendAck(message.id);
        
        // Dispatch to store
        store.dispatch(addMessage(message.payload));
        break;
      
      case "ack":
        // Server confirmed receipt of our message
        const pending = this.pendingAcks.get(message.messageId);
        if (pending) {
          pending.resolve();
          this.pendingAcks.delete(message.messageId);
          store.dispatch(updateMessageStatus(message.messageId, "delivered"));
        }
        break;
      
      case "typing":
        store.dispatch(setTypingIndicator(
          message.conversationId, 
          message.userId, 
          message.isTyping
        ));
        break;
      
      case "read_receipt":
        store.dispatch(updateReadReceipt(
          message.conversationId,
          message.userId,
          message.lastReadMessageId
        ));
        break;
      
      case "presence":
        store.dispatch(updatePresence(message.userId, message.status));
        break;
      
      case "pong":
        // Heartbeat response — connection is alive
        break;
    }
  }
  
  send(message: OutgoingMessage): Promise<void> {
    return new Promise((resolve, reject) => {
      const messageId = crypto.randomUUID();
      
      if (this.connectionState !== "connected") {
        // Buffer for later delivery
        this.messageBuffer.push({ ...message, id: messageId });
        // Still resolve — optimistic UI shows the message immediately
        resolve();
        return;
      }
      
      // Track pending ack with timeout
      this.pendingAcks.set(messageId, {
        resolve,
        reject,
        timeout: setTimeout(() => {
          // No ack within 10s — assume failed, will retry
          this.pendingAcks.delete(messageId);
          this.messageBuffer.push({ ...message, id: messageId });
        }, 10000)
      });
      
      this.ws!.send(JSON.stringify({ ...message, id: messageId }));
    });
  }
  
  private scheduleReconnect() {
    setTimeout(() => {
      this.connect();
      this.reconnectDelay = Math.min(
        this.reconnectDelay * 2,
        this.maxReconnectDelay
      );
    }, this.reconnectDelay + Math.random() * 1000); // Jitter to prevent thundering herd
  }
  
  private async requestMissedMessages() {
    // On reconnect, ask server for messages since our last received ID
    const lastMessageId = store.getState().lastReceivedMessageId;
    this.ws!.send(JSON.stringify({
      type: "sync",
      since: lastMessageId,
    }));
  }
}

interface MessengerStore {
  // === Normalized entities ===
  messages: Record<string, Message>;
  conversations: Record<string, Conversation>;
  users: Record<string, User>;
  
  // === Conversation list state ===
  conversationList: {
    orderedIds: string[];           // Sorted by last message time
    filter: "all" | "unread" | "groups";
    searchQuery: string;
    searchResults: string[];        // Conversation IDs matching search
  };
  
  // === Active chat state ===
  activeChat: {
    conversationId: string | null;
    messageIds: string[];           // Ordered messages for current chat
    hasOlderMessages: boolean;
    isLoadingOlder: boolean;
    replyingTo: string | null;      // Message ID being replied to
    draft: string;                  // Unsent text
    scrollPosition: number;
    unreadAnchorId: string | null;  // First unread message
  };
  
  // === Real-time state ===
  presence: Record<string, {
    status: "online" | "away" | "offline";
    lastSeen: string;
  }>;
  typingIndicators: Record<string, {   // conversationId -> users typing
    userIds: string[];
    timeouts: Record<string, number>;  // Auto-clear after 5s
  }>;
  
  // === Offline queue ===
  offlineQueue: QueuedMessage[];
  syncState: {
    lastSyncTimestamp: string;
    isSyncing: boolean;
  };
  
  // === Connection state ===
  connection: {
    status: "connected" | "connecting" | "reconnecting" | "disconnected";
    latency: number;                // Measured via heartbeat
  };
}

interface Message {
  id: string;
  localId: string;              // Client-generated ID for optimistic matching
  conversationId: string;
  senderId: string;
  type: "text" | "image" | "file" | "voice" | "system";
  content: string;
  
  // Media
  attachments: Attachment[];
  linkPreviews: LinkPreview[];
  
  // Threading
  replyToId: string | null;
  threadId: string | null;
  
  // Reactions
  reactions: Record<string, string[]>;  // emoji -> userIds
  
  // Status tracking
  status: "sending" | "sent" | "delivered" | "read" | "failed";
  
  // Timestamps
  createdAt: string;            // Server timestamp (for ordering)
  localCreatedAt: string;       // Client timestamp (for display)
  editedAt: string | null;
  deletedAt: string | null;
  
  // Ordering
  sequenceNumber: number;       // Monotonically increasing per conversation
}

interface Conversation {
  id: string;
  type: "direct" | "group";
  name: string | null;          // null for 1:1 (derive from other user)
  avatarUrl: string | null;
  participantIds: string[];
  
  // Derived/cached data
  lastMessageId: string | null;
  lastMessagePreview: string;
  lastMessageTimestamp: string;
  
  // Read tracking
  myLastReadMessageId: string | null;
  unreadCount: number;
  
  // Group-specific
  adminIds: string[];
  isMuted: boolean;
  pinnedMessageIds: string[];
  
  // Drafts (persist across sessions)
  draft: string;
}

// The ordering problem:
// User A sends "Yes" at T=100ms (their clock)
// User B sends "Want to meet?" at T=99ms (their clock is 1ms ahead)
// Server receives A first, B second
// 
// If you sort by sender timestamp: B appears before A (wrong context)
// If you sort by server timestamp: A appears before B (correct)
// But server timestamp means displayed time doesn’t match sender’s clock

// Solution: Hybrid ordering with Lamport-style sequence numbers
interface MessageOrdering {
  // Use server-assigned sequence number for ORDER
  sequenceNumber: number;
  // Use server receive time for GROUP (date separators)
  serverTimestamp: string;
  // Use sender’s local time for DISPLAY ("2:34 PM")
  displayTimestamp: string;
}

function sortMessages(messages: Message[]): Message[] {
  return [...messages].sort((a, b) => {
    // Primary: sequence number (server-assigned, monotonic)
    if (a.sequenceNumber !== b.sequenceNumber) {
      return a.sequenceNumber - b.sequenceNumber;
    }
    // Tiebreaker: server timestamp
    return new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime();
  });
}

// GET /api/v1/conversations?limit=20&cursor={cursor}
interface ConversationListResponse {
  conversations: ConversationDTO[];
  users: UserDTO[];               // Participants denormalized
  nextCursor: string | null;
}

// GET /api/v1/conversations/{id}/messages?limit=50&before={messageId}
interface MessageHistoryResponse {
  messages: MessageDTO[];
  hasMore: boolean;
  // Read receipt data for this conversation
  readReceipts: Record<string, string>;  // userId -> lastReadMessageId
}

// Client -> Server
type ClientWSMessage =
  | { type: "send_message"; id: string; conversationId: string; content: string; attachments?: Attachment[]; replyToId?: string }
  | { type: "typing_start"; conversationId: string }
  | { type: "typing_stop"; conversationId: string }
  | { type: "mark_read"; conversationId: string; messageId: string }
  | { type: "react"; messageId: string; emoji: string }
  | { type: "delete_message"; messageId: string; forEveryone: boolean }
  | { type: "sync"; since: string }  // Request missed messages
  | { type: "ping" };

// Server -> Client
type ServerWSMessage =
  | { type: "message"; payload: MessageDTO }
  | { type: "ack"; messageId: string; serverTimestamp: string; sequenceNumber: number }
  | { type: "typing"; conversationId: string; userId: string; isTyping: boolean }
  | { type: "read_receipt"; conversationId: string; userId: string; lastReadMessageId: string }
  | { type: "presence"; userId: string; status: "online" | "away" | "offline" }
  | { type: "reaction"; messageId: string; userId: string; emoji: string; action: "add" | "remove" }
  | { type: "message_deleted"; messageId: string; deletedFor: "me" | "everyone" }
  | { type: "sync_batch"; messages: MessageDTO[]; hasMore: boolean }
  | { type: "pong" };

async function sendMessage(conversationId: string, content: string, replyToId?: string) {
  const localId = crypto.randomUUID();
  const localTimestamp = new Date().toISOString();
  
  // Step 1: Optimistic insert (instant)
  const optimisticMessage: Message = {
    id: localId,       // Temporary ID
    localId,
    conversationId,
    senderId: currentUserId,
    type: "text",
    content,
    attachments: [],
    linkPreviews: [],
    replyToId: replyToId || null,
    threadId: null,
    reactions: {},
    status: "sending",
    createdAt: localTimestamp,
    localCreatedAt: localTimestamp,
    editedAt: null,
    deletedAt: null,
    sequenceNumber: Infinity, // Sort to bottom until server assigns real number
  };
  
  store.dispatch(addMessage(optimisticMessage));
  
  // Step 2: Clear draft
  store.dispatch(clearDraft(conversationId));
  
  // Step 3: Scroll to bottom
  scrollToBottom("smooth");
  
  // Step 4: Play send sound
  playSendSound();
  
  // Step 5: Send via WebSocket (or queue if offline)
  try {
    const ack = await connectionManager.send({
      type: "send_message",
      id: localId,
      conversationId,
      content,
      replyToId,
    });
    
    // Step 6: Update with server-confirmed data
    store.dispatch(confirmMessage({
      localId,
      serverId: ack.messageId,
      serverTimestamp: ack.serverTimestamp,
      sequenceNumber: ack.sequenceNumber,
      status: "sent",
    }));
  } catch (error) {
    // Step 7: Mark as failed (show retry button)
    store.dispatch(updateMessageStatus(localId, "failed"));
  }
}

// Step 8: When the OTHER user sends a read receipt
// that includes our message, update to "read"
function handleReadReceipt(conversationId: string, userId: string, lastReadMessageId: string) {
  const conversation = store.getState().conversations[conversationId];
  if (conversation.type === "direct") {
    // Mark all messages up to lastReadMessageId as "read"
    const messageIds = store.getState().activeChat.messageIds;
    const lastReadIndex = messageIds.indexOf(lastReadMessageId);
    
    for (let i = 0; i <= lastReadIndex; i++) {
      const msg = store.getState().messages[messageIds[i]];
      if (msg.senderId === currentUserId && msg.status !== "read") {
        store.dispatch(updateMessageStatus(messageIds[i], "read"));
      }
    }
  }
}

class TypingIndicatorManager {
  private typingTimeout: number | null = null;
  private isCurrentlyTyping = false;
  private TYPING_DEBOUNCE = 2000; // ms
  private TYPING_TIMEOUT = 5000;  // Auto-clear if no update
  
  // Called on every keystroke in the composer
  handleInput(conversationId: string) {
    if (!this.isCurrentlyTyping) {
      // First keystroke — send typing_start
      this.isCurrentlyTyping = true;
      connectionManager.send({
        type: "typing_start",
        conversationId,
      });
    }
    
    // Reset the stop timer on every keystroke
    if (this.typingTimeout) clearTimeout(this.typingTimeout);
    this.typingTimeout = window.setTimeout(() => {
      this.stopTyping(conversationId);
    }, this.TYPING_DEBOUNCE);
  }
  
  private stopTyping(conversationId: string) {
    this.isCurrentlyTyping = false;
    connectionManager.send({
      type: "typing_stop",
      conversationId,
    });
  }
  
  // Receiving side — handle incoming typing indicators
  handleRemoteTyping(conversationId: string, userId: string, isTyping: boolean) {
    if (isTyping) {
      // Add user to typing set
      store.dispatch(addTypingUser(conversationId, userId));
      
      // Auto-clear after timeout (in case we miss the stop event)
      const timeoutId = window.setTimeout(() => {
        store.dispatch(removeTypingUser(conversationId, userId));
      }, this.TYPING_TIMEOUT);
      
      store.dispatch(setTypingTimeout(conversationId, userId, timeoutId));
    } else {
      store.dispatch(removeTypingUser(conversationId, userId));
    }
  }
}

// Display component for group typing
function TypingIndicator({ conversationId }: Props) {
  const typingUsers = useStore(s => s.typingIndicators[conversationId]?.userIds || []);
  const users = useStore(s => s.users);
  
  if (typingUsers.length === 0) return null;
  
  const names = typingUsers.map(id => users[id]?.firstName || "Someone");
  
  let text: string;
  if (names.length === 1) text = `${names[0]} is typing`;
  else if (names.length === 2) text = `${names[0]} and ${names[1]} are typing`;
  else text = `${names[0]} and ${names.length - 1} others are typing`;
  
  return (

// Chat messages are loaded NEWEST first, scroll UPWARD for older
// This is the reverse of a normal infinite scroller

function MessageList({ conversationId }: Props) {
  const containerRef = useRef<HTMLDivElement>(null);
  const [isAtBottom, setIsAtBottom] = useState(true);
  const prevScrollHeight = useRef(0);
  
  // Load older messages when scrolling to TOP
  const loadOlderMessages = useCallback(async () => {
    const container = containerRef.current!;
    const prevHeight = container.scrollHeight;
    prevScrollHeight.current = prevHeight;
    
    await fetchOlderMessages(conversationId);
    
    // After DOM update: maintain scroll position
    requestAnimationFrame(() => {
      const newHeight = container.scrollHeight;
      const addedHeight = newHeight - prevHeight;
      container.scrollTop += addedHeight;
    });
  }, [conversationId]);
  
  // Auto-scroll to bottom on new messages (only if already at bottom)
  useEffect(() => {
    if (isAtBottom) {
      scrollToBottom("smooth");
    } else {
      // Show "New messages" floating button
      setHasNewMessages(true);
    }
  }, [latestMessageId]);
  
  // Track whether user is at bottom
  const handleScroll = useCallback(() => {
    const container = containerRef.current!;
    const { scrollTop, scrollHeight, clientHeight } = container;
    const distanceFromBottom = scrollHeight - scrollTop - clientHeight;
    
    setIsAtBottom(distanceFromBottom < 50);
    
    // Near top — load older messages
    if (scrollTop < 200 && hasOlderMessages && !isLoadingOlder) {
      loadOlderMessages();
    }
  }, [hasOlderMessages, isLoadingOlder]);
  
  return (

class OfflineManager {
  private db: IDBDatabase;
  
  async init() {
    this.db = await openDB("messenger", 3, {
      upgrade(db, oldVersion) {
        if (oldVersion < 1) {
          const messageStore = db.createObjectStore("messages", { keyPath: "id" });
          messageStore.createIndex("by-conversation", "conversationId");
          messageStore.createIndex("by-timestamp", ["conversationId", "sequenceNumber"]);
          
          db.createObjectStore("conversations", { keyPath: "id" });
          db.createObjectStore("outbox", { keyPath: "localId" });
        }
        if (oldVersion < 2) {
          db.createObjectStore("drafts", { keyPath: "conversationId" });
        }
        if (oldVersion < 3) {
          const msgStore = db.transaction("messages").objectStore("messages");
          msgStore.createIndex("by-content", "content"); // For search
        }
      }
    });
  }
  
  // Save messages to IndexedDB for offline access
  async cacheMessages(messages: Message[]) {
    const tx = this.db.transaction("messages", "readwrite");
    for (const msg of messages) {
      await tx.objectStore("messages").put(msg);
    }
    await tx.done;
  }
  
  // Load cached messages when offline or for instant display
  async getCachedMessages(conversationId: string, limit = 50): Promise<Message[]> {
    const tx = this.db.transaction("messages", "readonly");
    const index = tx.objectStore("messages").index("by-timestamp");
    
    const range = IDBKeyRange.bound(
      [conversationId, 0],
      [conversationId, Infinity]
    );
    
    const messages: Message[] = [];
    let cursor = await index.openCursor(range, "prev"); // Newest first
    
    while (cursor && messages.length < limit) {
      messages.push(cursor.value);
      cursor = await cursor.continue();
    }
    
    return messages.reverse(); // Return in chronological order
  }
  
  // Queue messages for sending when back online
  async queueOutgoingMessage(message: QueuedMessage) {
    await this.db.put("outbox", message);
  }
  
  // Sync outbox when connection restores
  async syncOutbox() {
    const outbox = await this.db.getAll("outbox");
    
    // Sort by creation time to maintain order
    outbox.sort((a, b) => a.createdAt - b.createdAt);
    
    for (const message of outbox) {
      try {
        await connectionManager.send({
          type: "send_message",
          ...message,
        });
        await this.db.delete("outbox", message.localId);
      } catch (error) {
        // Stop syncing on first failure (maintain order)
        break;
      }
    }
  }
  
  // Persist drafts across sessions
  async saveDraft(conversationId: string, text: string) {
    await this.db.put("drafts", { conversationId, text, updatedAt: Date.now() });
  }
  
  async getDraft(conversationId: string): Promise<string> {
    const draft = await this.db.get("drafts", conversationId);
    return draft?.text || "";
  }
}

// Problem: Scrolling through 100 unread messages would send 100 read receipts
// Solution: Batch and debounce

class ReadReceiptManager {
  private pendingReceipts = new Map<string, string>(); // convId -> lastReadMsgId
  private flushTimer: number | null = null;
  private FLUSH_DELAY = 1000; // ms
  
  markAsRead(conversationId: string, messageId: string) {
    // Only track the LATEST read message per conversation
    this.pendingReceipts.set(conversationId, messageId);
    
    // Debounce the flush
    if (this.flushTimer) clearTimeout(this.flushTimer);
    this.flushTimer = window.setTimeout(() => this.flush(), this.FLUSH_DELAY);
  }
  
  private flush() {
    for (const [conversationId, messageId] of this.pendingReceipts) {
      connectionManager.send({
        type: "mark_read",
        conversationId,
        messageId,
      });
      
      // Update local unread count
      store.dispatch(clearUnreadCount(conversationId));
    }
    this.pendingReceipts.clear();
  }
  
  // Use IntersectionObserver to detect which messages are visible
  observeMessages(containerEl: HTMLElement) {
    const observer = new IntersectionObserver(
      (entries) => {
        for (const entry of entries) {
          if (entry.isIntersecting) {
            const messageId = entry.target.getAttribute("data-message-id");
            const convId = entry.target.getAttribute("data-conversation-id");
            if (messageId && convId) {
              this.markAsRead(convId, messageId);
            }
          }
        }
      },
      { root: containerEl, threshold: 0.5 }
    );
    
    return observer;
  }
}

// Detect URLs in message input and fetch previews
class LinkPreviewManager {
  private cache = new Map<string, LinkPreview>();
  private fetchController: AbortController | null = null;
  
  async detectAndFetch(text: string): Promise<LinkPreview | null> {
    const urlRegex = /(https?:\/\/[^\s]+)/g;
    const urls = text.match(urlRegex);
    if (!urls) return null;
    
    const url = urls[urls.length - 1]; // Use last URL typed
    
    // Check cache
    if (this.cache.has(url)) return this.cache.get(url)!;
    
    // Cancel previous fetch
    this.fetchController?.abort();
    this.fetchController = new AbortController();
    
    try {
      const response = await fetch(`/api/v1/link-preview?url=${encodeURIComponent(url)}`, {
        signal: this.fetchController.signal,
      });
      const preview: LinkPreview = await response.json();
      this.cache.set(url, preview);
      return preview;
    } catch {
      return null;
    }
  }
}

interface LinkPreview {
  url: string;
  title: string;
  description: string;
  image: string | null;
  siteName: string;
  favicon: string | null;
}

class NotificationManager {
  private permission: NotificationPermission = "default";
  
  async requestPermission() {
    if ("Notification" in window) {
      this.permission = await Notification.requestPermission();
    }
  }
  
  notify(message: Message) {
    // Do not notify if:
    // 1. Tab is focused and chat is active
    // 2. Conversation is muted
    // 3. Message is from current user
    if (document.hasFocus() && 
        store.getState().activeChat.conversationId === message.conversationId) {
      return;
    }
    
    const conversation = store.getState().conversations[message.conversationId];
    if (conversation.isMuted) return;
    if (message.senderId === currentUserId) return;
    
    // Play notification sound
    this.playSound();
    
    // Update tab title with unread count
    const totalUnread = this.getTotalUnreadCount();
    document.title = totalUnread > 0 ? `(${totalUnread}) Messenger` : "Messenger";
    
    // Update favicon with badge
    this.updateFavicon(totalUnread);
    
    // Browser notification
    if (this.permission === "granted") {
      const sender = store.getState().users[message.senderId];
      const notification = new Notification(sender.name, {
        body: this.getPreviewText(message),
        icon: sender.avatarUrl,
        tag: message.conversationId, // Replace previous notification from same convo
        silent: true, // We already played our sound
      });
      
      notification.onclick = () => {
        window.focus();
        navigateToConversation(message.conversationId);
        notification.close();
      };
      
      // Auto-dismiss after 5s
      setTimeout(() => notification.close(), 5000);
    }
  }
  
  private playSound() {
    const audio = new Audio("/sounds/notification.mp3");
    audio.volume = 0.3;
    audio.play().catch(() => {}); // Ignore autoplay restrictions
  }
}