Design a Chat App (Messenger / Slack style)

A frontend system design walkthrough for a real-time chat client. You will learn how to keep a WebSocket healthy, order messages correctly, send instantly with an offline outbox, and keep many tabs in sync.

Frontend system design · Classic design question

After this page you can design the web client of a chat product end to end. You can explain the connection lifecycle, the message state machine, the store and IndexedDB layout, and how unread counts and receipts stay correct.

Correctness contract: a message the user sends is never lost and never shown twice. Messages in a thread always appear in server order. Unread counts and receipts match the server after any reconnect.

Assumptions: a backend that assigns a per conversation sequence number to each message, a WebSocket gateway, and a REST API for history. Users keep the app open in several tabs and lose network often on mobile.

Chat is the classic real-time frontend problem. The UI must feel instant, but the network is slow and unreliable. Two users can send at the same moment. A laptop sleeps and wakes up with a dead socket. A user opens three tabs, and each one wants its own connection. A phone goes through a tunnel with five unsent messages. The client must handle all of this and still show one clean, ordered thread. This page builds the client as a small distributed system with a local database, a sync engine, and a view.

Contents

  1. Concepts to understand first
  2. 1. Clarifying questions and requirements
  3. 2. Scope and budgets
  4. 3. High-level architecture
  5. 4. Data model
  6. 5. Interface and API
  7. 6. Deep dive: WebSocket connection lifecycle
  8. 7. Deep dive: ordering, optimistic send, and the outbox
  9. 8. Deep dive: receipts, typing, and unread counts
  10. 9. Deep dive: conversation list, thread view, and reverse scroll
  11. 10. Deep dive: attachments upload
  12. 11. Deep dive: multi-tab sync and notifications
  13. 12. Failure modes
  14. 13. Trade-offs
  15. 14. 45-minute interview walkthrough
  16. 15. Summary
  17. 16. Common mistakes
  18. Worked example: sending through a tunnel
  19. Code lab: ordering and reconciling messages
  20. Check yourself
  21. Key terms
  22. Further reading

Concepts to understand first

WebSocket

A long lived, two way connection over a single TCP connection. It starts as an HTTP request with an Upgrade header. After that, client and server can both send frames at any time with very small overhead.

Example. new WebSocket("wss://chat.example.com/ws") opens a socket. The server pushes new messages as they happen.

Limit. The browser does not tell you quickly when a socket silently dies. You need your own heartbeat. It also has no built in backpressure in the classic API.

Client generated id

The client creates a unique id for each message before sending, usually with crypto.randomUUID(). The server stores it and echoes it back. It links the optimistic bubble to the server copy and lets the server drop duplicate sends.

Example. The client sends clientId: "c-7f1e" twice after a timeout. The server stores one message and acks both.

Limit. It is not an order. Two client ids say nothing about which message came first.

Server sequence number

The server gives each message in a conversation an increasing number: 1, 2, 3. This number defines the one true order. Clients sort by it. A jump from 41 to 44 tells the client it missed 42 and 43.

Example. Alice and Bob send at the same millisecond. The server accepts Bob first, so Bob gets 88 and Alice gets 89. Everyone sees the same order.

Limit. It needs one ordering point per conversation on the server. Very large channels must shard that carefully.

Outbox

A durable queue of messages the user wrote but the server has not acked. It lives in IndexedDB, so it survives reloads, crashes, and offline periods. The sync engine drains it when the socket is open.

Example. The user sends 3 messages in airplane mode, then closes the tab. On next open, the outbox still has 3 items and sends them in order.

Limit. Old outbox items may no longer make sense. A reply to a deleted message, sent 2 days later, needs a product decision.

BroadcastChannel

A browser API that lets tabs of the same origin send messages to each other. It is the simplest way to share events between tabs without a server round trip.

Example. Tab A receives a new message on its socket. It posts it on new BroadcastChannel("chat"). Tab B updates its thread at once.

Limit. It is fire and forget. A tab that is closed or frozen misses messages, so each tab must also read from IndexedDB.

Reverse scroll list

A chat thread is anchored to the bottom. New messages appear at the bottom, and older history loads at the top as the user scrolls up. The list must keep the user's place when content is added above.

Example. The user scrolls up and 50 older messages load. Without adjustment, the view would jump by 3,000 pixels.

Limit. Most virtual list libraries assume top anchoring. Bottom anchoring with variable heights needs extra work.

1. Clarifying questions and requirements

Functional requirements

Non-functional requirements

Interview

State early that the server owns order through a sequence number, and the client owns instant feedback through client ids and an outbox. This one sentence frames the whole design.

2. Scope and budgets

Devices and network

Message volume

Frame budget

A burst of 20 messages per second must not re-render the whole thread 20 times. Batch incoming messages per animation frame with requestAnimationFrame. That turns 20 renders into at most about 1 per frame, each well under 10 ms. Each message bubble should cost under 1 ms to render.

DOM size

A message bubble has 10 to 30 nodes. A 5,000 message thread without virtualization would be 100,000 nodes. That breaks scroll on any device. Window the thread to about 50 visible bubbles plus overscan.

Bundle budget

Connection budget

If 10 million users each keep 3 tabs open, one socket per tab means 30 million connections. One socket per browser means 10 million. That is a real server cost, and it is a client design choice.

3. High-level architecture

Chat client architecture: the composer sends through a sync engine that writes to an IndexedDB outbox and the message store. A leader tab owns one WebSocket. Acks and new messages flow back into the store. REST fills gaps after reconnect. Attachments upload to object storage. Web Push reaches a Service Worker when no tab is open.
Figure 1. Client architecture. The sync engine is the only network owner. IndexedDB is the local source of truth.

The key idea is local first. The UI reads from the local store, which mirrors IndexedDB. The sync engine moves data between the local database and the server in the background. The view never waits for the network to show something the user did.

Intuition

Think of a post office counter. You hand over a letter and get a receipt at once. The letter sits in the outgoing tray. A courier picks up the tray when the road is open. If the road is closed, the tray waits. Your receipt is never thrown away.

4. Data model

type MsgStatus = "pending" | "sending" | "sent" | "delivered" | "read" | "failed"

interface Message {
  clientId: string          // created on the client, stable forever
  id?: string               // server id, set after ack
  conversationId: string
  seq?: number              // server order, set after ack
  senderId: string
  body: { kind: "text"; text: string } | { kind: "file"; attachmentId: string }
  createdAt: number         // client clock, display only
  serverTime?: number       // server clock, after ack
  status: MsgStatus
  replyToId?: string
}

interface Conversation {
  id: string
  title: string
  memberIds: string[]
  lastSeq: number           // newest seq the client has
  lastReadSeq: number       // my read marker
  unreadCount: number       // derived: messages from others with seq > lastReadSeq
  lastMessagePreview: string
  lastActivityAt: number
  oldestLoadedSeq: number   // for loading history upward
}

interface ClientState {
  conversations: Record<string, Conversation>
  messages: Record<string, Message>          // key = clientId or id
  threadOrder: Record<string, string[]>      // conversationId -> keys sorted by seq, pending last
  typing: Record<string, Record<string, number>>  // convId -> userId -> expiresAt
  connection: "connecting" | "open" | "reconnecting" | "offline"
}

// IndexedDB object stores
// messages:  keyPath "clientId", index ["conversationId", "seq"]
// outbox:    keyPath "clientId", index "createdAt"
// meta:      key "cursor:<conversationId>" -> lastSeq

Notice that pending messages have no seq. They sort after all acked messages, in the order the user wrote them. After the ack, they get their real seq and may move up if someone else's message got an earlier number. This is correct. The server order is the truth.

The compound index ["conversationId", "seq"] makes "give me 50 messages before seq 900 in conversation X" a single fast range query with IDBKeyRange.bound.

5. Interface and API

WebSocket frames

// client -> server
{ "type": "hello", "token": "...", "cursors": { "conv_1": 912, "conv_2": 40 } }
{ "type": "message.send", "clientId": "c-7f1e", "conversationId": "conv_1", "body": {...} }
{ "type": "typing", "conversationId": "conv_1" }
{ "type": "read", "conversationId": "conv_1", "seq": 915 }
{ "type": "ping", "t": 1731760000000 }

// server -> client
{ "type": "ack", "clientId": "c-7f1e", "id": "m_9921", "seq": 916, "serverTime": 1731760000123 }
{ "type": "message.new", "message": { "id": "m_9922", "seq": 917, ... } }
{ "type": "receipt", "conversationId": "conv_1", "userId": "u_2", "kind": "read", "seq": 916 }
{ "type": "typing", "conversationId": "conv_1", "userId": "u_2" }
{ "type": "pong", "t": 1731760000000 }

REST endpoints

GET  /api/conversations?after=<cursor>
GET  /api/conversations/:id/messages?beforeSeq=900&limit=50     // history
GET  /api/conversations/:id/messages?afterSeq=912&limit=200     // gap fill
POST /api/uploads   { name, size, mime }  ->  { attachmentId, uploadUrl }

The hello frame carries the client's latest seq per conversation. The server can then replay what the client missed, or say "too far behind, use REST". This makes reconnect cheap and correct.

Component props

<ThreadView conversationId="conv_1" onLoadOlder={loadOlder} />
<MessageBubble messageKey="c-7f1e" grouped={true} />
<Composer conversationId="conv_1" onSend={send} onTyping={notifyTyping} />

6. Deep dive: WebSocket connection lifecycle

States

Model the connection as a small state machine: connecting, open, reconnecting, offline. Show the state in the UI with a quiet banner such as "Reconnecting". Users then know why messages are not arriving.

Open and authenticate

  1. Open wss://. Never plain ws:// in production.
  2. Send hello with a short lived token and cursors. Avoid putting long lived tokens in the URL, because URLs end up in logs.
  3. Wait for a welcome frame. Only then mark the socket open and drain the outbox.

Heartbeat

A socket can die silently. A NAT box drops it, or the laptop sleeps. The browser may not fire close for minutes. Send an application level ping every 25 seconds. If no pong arrives within 10 seconds, close the socket and reconnect. 25 seconds also keeps most proxies from timing out idle connections, which often happens at 30 to 60 seconds.

Reconnect with backoff and jitter

Reconnect after 0.5 s, then 1 s, 2 s, 4 s, up to 30 s. Add random jitter of up to 50 percent. Without jitter, a server restart makes millions of clients reconnect at the same instant, which can knock the server down again. That is the thundering herd problem.

Also listen to browser signals:

Catch up after reconnect

On reconnect, the hello frame sends the latest seq per conversation. The server replays missing messages. For conversations far behind, the client calls the REST gap fill endpoint. Only after catch up should unread counts be trusted again.

Mistake

Relying on the close event to detect a dead socket. On a sleeping laptop or a phone that changed networks, it may not fire for a long time. Messages pile up on the server while the user sees "connected".

7. Deep dive: ordering, optimistic send, and the outbox

Sending one message: the composer saves it to the IndexedDB outbox and shows a sending bubble. The socket sends it. The server dedupes by clientId and acks with id and seq. The client replaces the temporary message, marks it sent, and deletes it from the outbox. Delivery and read receipts flow back later. Without an ack, the outbox retries with backoff.
Figure 2. Message send lifecycle. The outbox makes the send durable. The ack makes it ordered.

The send path

  1. The user presses Enter. Create clientId with crypto.randomUUID().
  2. Write the message to the outbox in IndexedDB. Only after this write is the message durable.
  3. Add it to the store with status pending. The bubble shows a clock icon or a faded style.
  4. If the socket is open, send the frame and set status sending.
  5. On ack, set id, seq, and serverTime. Set status sent. Delete it from the outbox. Re-sort the thread.
  6. If no ack arrives within about 10 seconds, resend with the same clientId. The server dedupes, so this is safe.
  7. After about 5 failed attempts or a hard error such as "not a member", set status failed. Show "Not sent. Tap to retry". Keep the text.

Order within the outbox

Send outbox items one at a time per conversation, in creation order. Wait for each ack before the next send. If two messages are in flight together and the first is retried, the server could order them backward. A simpler alternative is to send in parallel with a client sequence number per sender, and let the server keep per sender order.

Merging incoming messages

Timestamps

Never order by the client clock. Device clocks can be minutes off. Show createdAt for pending messages so the bubble has a time. After ack, show serverTime. Group bubbles by sender and by gaps of more than about 5 minutes, using server time.

Edits, deletes, and reactions

Treat them as events on a message id, with their own version number. Apply an edit only if its version is newer than the one you have. This makes late or repeated events harmless. Reactions are a set per emoji. Apply them optimistically, with the same snapshot and rollback approach as a like button.

8. Deep dive: receipts, typing, and unread counts

Delivered and read receipts

Use a read marker, not per message flags. The recipient's client sends read with the highest seq it has shown. Every message with a lower seq is read too. This turns 50 receipts into one. In a group, keep the read seq per member. A message is "seen by N" when N members have a read marker at or above its seq.

When is a message read? When the thread is open, the tab is visible, the window has focus, and the message is in the viewport. Use IntersectionObserver on the newest bubbles. Debounce read updates to about once per second, so a fast scroll does not send 30 frames.

Typing indicators

Unread counts

Derive the count, do not increment a counter. unreadCount is the number of messages from others with seq greater than lastReadSeq. Incrementing on each event breaks with duplicates and replays. Deriving from seq is always right after catch up. For conversations with many unread messages, the server sends the count, because the client may not have all messages.

Tip

The read marker is a single integer per user per conversation. It is the cheapest correct way to do receipts, unread counts, and cross device sync at once.

9. Deep dive: conversation list, thread view, and reverse scroll

Conversation list

Thread view and reverse virtualization

Open a thread at the bottom, or at the first unread message if there are many. The list is anchored to the bottom.

A common trick is display: flex with flex-direction: column-reverse on the scroll container. The browser then anchors to the bottom for free, and content added at the top does not shift the view. It has quirks with scrollTop signs across browsers, so test it. Native CSS scroll anchoring through overflow-anchor also helps for history inserts in normal flow.

For virtualization, keep heights by message key, estimate before measuring, and render from the bottom. Prefetch older history when the user is within about one screen of the top, using an IntersectionObserver sentinel.

Jump to a message

Search results and reply links need "jump to seq 1,204". Load a window around that seq through REST, render it as a separate segment, and scroll to the message. The thread now has a gap between this segment and the newest messages. Track loaded ranges as a list of [fromSeq, toSeq] intervals, and fill gaps as the user scrolls.

Accessibility

10. Deep dive: attachments upload

  1. The user picks a file. Show a local preview at once with URL.createObjectURL(file). Revoke the URL later to free memory.
  2. Check size and type on the client for fast feedback. The server must check again.
  3. For images, resize to a sensible maximum, such as 2,048 pixels, in a Web Worker with OffscreenCanvas. This can turn a 6 MB photo into 500 KB.
  4. Ask the server for an upload URL. Upload directly to object storage with a signed URL, so the chat server does not carry the bytes.
  5. Show progress. fetch has no upload progress event in most browsers, so use XMLHttpRequest with upload.onprogress. Allow cancel with xhr.abort().
  6. For files over about 10 MB, use a resumable or chunked protocol, so a dropped connection only resends the last chunk.
  7. After upload, send the chat message with the attachmentId through the normal outbox path.

Store the pending file as a Blob in IndexedDB with the outbox item. Then an upload interrupted by a reload can resume. Without this, an offline image message is lost on reload.

11. Deep dive: multi-tab sync and notifications

One socket per browser

Elect one leader tab to own the WebSocket. The Web Locks API makes this clean. Each tab calls navigator.locks.request("chat-leader", ...). Only one tab holds the lock. When that tab closes, the browser releases the lock and the next tab gets it.

Keeping tabs consistent

Notifications

Interview

Multi-tab is where many candidates stop. Mention leader election with Web Locks, BroadcastChannel for fan out, IndexedDB as shared truth, and one notifier. It shows staff level depth.

12. Failure modes

13. Trade-offs

WebSocket versus SSE plus POST versus long polling

Serial versus parallel outbox

Local first versus server only

Leader tab versus socket per tab

Read receipts per message versus read marker

14. 45-minute interview walkthrough

  1. Minutes 0 to 5. Clarify group size, receipts, message types, offline, encryption, platforms.
  2. Minutes 5 to 9. Requirements and budgets: own message in one frame, 300 ms delivery, no loss, burst batching, connection count math.
  3. Minutes 9 to 15. Architecture: view, store, sync engine, IndexedDB, leader tab, network. Draw it.
  4. Minutes 15 to 20. Data model and protocol: clientId, seq, read marker, hello with cursors, ack frame.
  5. Minutes 20 to 30. Deep dive on send: outbox, optimistic bubble, ack, dedupe, retries, gap fill.
  6. Minutes 30 to 35. Connection lifecycle: heartbeat, backoff with jitter, catch up.
  7. Minutes 35 to 40. Receipts, typing, unread counts derived from seq. Reverse scroll thread.
  8. Minutes 40 to 45. Multi-tab, notifications, failure modes, and metrics: send success rate, time to delivered, reconnect rate, duplicate rate.

15. Summary

16. Common mistakes

Worked example: sending through a tunnel

Alice is on a train. She has one tab open on her phone and one on her laptop at home.

  1. Alice types "Running late" and presses Enter. The client creates clientId c-1, writes it to the outbox, and shows a faded bubble. Time to bubble: 4 ms.
  2. The socket sends the frame. The server stores it with seq 501 and acks. The bubble becomes solid with one check mark. The outbox entry is deleted.
  3. The train enters a tunnel. Alice sends "Maybe 10 min" (c-2) and "Sorry!" (c-3). Both go to the outbox. The heartbeat gets no pong for 10 seconds. The client closes the socket and shows "Reconnecting".
  4. Meanwhile Bob sends "No problem" with seq 502. Alice's phone does not receive it.
  5. The client retries after 0.5 s, 1 s, 2 s, and 4 s, each with jitter. All fail.
  6. The train leaves the tunnel. The online event fires. The client reconnects and sends hello with cursor conv_1: 501.
  7. The server replays seq 502 from Bob. The client inserts it after 501. The thread shows Bob's message above Alice's two pending bubbles.
  8. The outbox drains in order. c-2 gets seq 503, c-3 gets seq 504. Both bubbles turn solid.
  9. Bob's phone receives 503 and 504 and sends a read marker of 504. Alice sees both messages marked read.
  10. Alice's laptop tab at home was leader there. It received 501 to 504 on its own socket, wrote them to IndexedDB, and showed one notification with tag: "conv_1", updated in place each time.
  11. Later Alice opens the laptop. The tab reads the read marker from the server, sees 504 is read on her phone, and clears the badge.

Code lab: ordering and reconciling messages

This model shows the core of the sync engine without a socket. It applies optimistic sends, acks, echoes, replays, and out of order arrivals. It then checks that the thread has no duplicates and is in server order with pending messages last. Save as chat.mjs and run node chat.mjs with Node 18 or newer.

import { randomUUID } from "node:crypto"

function createThread() {
  const byKey = new Map()            // clientId or id -> message
  const seqs = new Set()
  const keyOf = (m) => m.clientId ?? m.id

  function sendLocal(text) {
    const m = { clientId: randomUUID(), text, status: "pending" }
    byKey.set(m.clientId, m)
    return m.clientId
  }
  function onAck({ clientId, id, seq }) {
    const m = byKey.get(clientId)
    if (!m || m.seq) return          // unknown or already acked
    Object.assign(m, { id, seq, status: "sent" })
    noteSeq(seq)
  }
  function onIncoming(msg) {
    const key = keyOf(msg)
    const existing = byKey.get(key)
    if (existing && existing.seq) return   // replay or echo already merged
    byKey.set(key, { ...existing, ...msg, status: msg.status ?? "sent" })
    noteSeq(msg.seq)
  }
  function noteSeq(seq) { seqs.add(seq) }
  function gaps() {                  // ranges of seq we never received
    const out = []
    const max = Math.max(0, ...seqs)
    for (let s = 1; s <= max; s++) {
      if (seqs.has(s)) continue
      const last = out.at(-1)
      if (last && last[1] === s - 1) last[1] = s
      else out.push([s, s])
    }
    return out
  }
  function view() {
    const all = [...byKey.values()]
    const acked = all.filter((m) => m.seq).sort((a, b) => a.seq - b.seq)
    return [...acked, ...all.filter((m) => !m.seq)]
  }
  return { sendLocal, onAck, onIncoming, view, gaps }
}

const t = createThread()
t.onIncoming({ id: "m1", seq: 1, text: "hi from Bob" })
const a = t.sendLocal("hi Bob")
const b = t.sendLocal("are you there?")
t.onIncoming({ id: "m3", seq: 3, text: "Bob again" })      // arrives before acks
t.onAck({ clientId: a, id: "m2", seq: 2 })
t.onIncoming({ clientId: a, id: "m2", seq: 2, text: "hi Bob" })   // echo of own message
t.onIncoming({ id: "m3", seq: 3, text: "Bob again" })      // replay after reconnect
t.onIncoming({ id: "m6", seq: 6, text: "Bob later" })      // gap: 4 and 5 missing

for (const m of t.view()) console.log(m.seq ?? "-", m.status, m.text)
console.log("gaps to fill:", JSON.stringify(t.gaps()))
const texts = t.view().map((m) => m.text)
console.log(new Set(texts).size === texts.length ? "PASS no duplicates" : "FAIL")

Expected output: messages 1, 2, 3, and 6 in order, then "are you there?" as pending at the end. The gap list shows [[4,5]]. Your own message appears only once even though it was acked and echoed. Try calling onAck for b with seq 4 and see it move into place.

Check yourself

  1. Why should the client never order messages by its own timestamp?
    Answer

    Device clocks drift and can be minutes off. Two users would see different orders. The server sequence number gives one order that every client agrees on.

  2. What two problems does a client generated id solve?
    Answer

    It links the optimistic bubble to the server ack and echo, so the message is shown once. It also lets the server dedupe retries, so a resend after a lost ack does not create a duplicate.

  3. Why write to IndexedDB before sending over the socket?
    Answer

    So the message survives a reload, crash, or long offline period. Memory alone loses it. The outbox makes the send durable before the network is involved.

  4. How does the client detect it missed messages?
    Answer

    A new message arrives with a seq greater than lastSeq + 1. The client records the gap and fetches that range through the REST gap fill endpoint.

  5. Why derive unread counts instead of incrementing a counter?
    Answer

    Events can be duplicated or replayed after reconnect. Counting messages from others with seq greater than lastReadSeq is always correct, no matter how many times an event arrives.

  6. How do you keep only one WebSocket for many tabs?
    Answer

    Elect a leader with the Web Locks API. The leader owns the socket, writes to IndexedDB, and broadcasts events on a BroadcastChannel. When it closes, the lock passes to another tab, which opens a new socket.

  7. Older history loads at the top and the view jumps. How do you fix it?
    Answer

    Record scrollHeight and scrollTop before the insert. After render and before paint, set scrollTop to the old value plus the added height. A column-reverse container or native scroll anchoring can also help.

Key terms

WebSocket
A long lived, two way connection between browser and server.
Heartbeat
Periodic ping and pong frames that prove a connection is alive.
Exponential backoff with jitter
Retry delays that double each time, plus randomness to spread out clients.
Client id
A unique id created on the client for each message, used for dedupe and reconciliation.
Sequence number
A server assigned, increasing number that defines message order in a conversation.
Ack
A server frame confirming it stored a message, with its id and sequence number.
Outbox
A durable queue of messages waiting for an ack.
Gap fill
Fetching a missing range of sequence numbers after a jump is detected.
Read marker
The highest sequence number a user has read in a conversation.
BroadcastChannel
Browser API for messaging between same origin tabs.
Web Locks API
Browser API that grants a named lock to one context at a time, useful for leader election.
Web Push
A standard for servers to send messages to a Service Worker even when no tab is open.
role="log"
An ARIA live region role for chat logs and similar growing content.

Further reading

Primary references