Design: chat and messaging

The prompt

"Design WhatsApp" or "design a chat app" looks like a WebSocket problem. The harder parts are elsewhere: putting messages in one order, never showing one twice when a phone retries on a bad connection, and catching up a device that was offline for a week.

1. Requirements

Functional: send and receive messages in one-to-one and group chats; history on every device; sent, delivered and read indicators; online status and "last seen".

Non-functional: under 500 ms delivery to online recipients; every message in the same order for every member; no duplicates and no lost messages; history kept indefinitely.

Out of scope: voice and video calls, media processing (13.01 Direct-to-storage uploads), end-to-end encryption (with it, the server stores ciphertext it can't read; the design below barely changes).

2. Estimates

3. Entities and API

Conversation { id, members[], last_seq }
Message      { conversation_id, seq, client_msg_id, sender_id, body, sent_at }     primary key (conversation_id, seq)
ReadState    { user_id, conversation_id, read_up_to_seq }

WebSocket ← { type: "send", conversation_id, client_msg_id, body }
          → { type: "ack", client_msg_id, seq }
          → { type: "message", conversation_id, seq, sender_id, body }
GET /conversations/{id}/messages?after_seq=N&limit=100                  catch up after being offline

4. High-level design

5. Deep dives

export async function sendMessage(db: pg.Pool, conversationId: number, clientMsgId: string, senderId: number, body: string) {
  const client = await db.connect();
  try {
    const dup = await client.query("SELECT seq FROM messages WHERE conversation_id = $1 AND client_msg_id = $2", [
      conversationId,
      clientMsgId,
    ]);
    if (dup.rowCount) return Number(dup.rows[0].seq); // a retry: same message, same number
    await client.query("BEGIN");
    const { rows } = await client.query(
      "UPDATE conversations SET last_seq = last_seq + 1 WHERE id = $1 RETURNING last_seq",
      [conversationId],
    );
    const seq = Number(rows[0].last_seq);
    await client.query(
      "INSERT INTO messages (conversation_id, seq, client_msg_id, sender_id, body) VALUES ($1, $2, $3, $4, $5)",
      [conversationId, seq, clientMsgId, senderId, body],
    );
    await client.query("COMMIT");
    return seq;
  } catch (err: any) {
    await client.query("ROLLBACK"); // also undoes the sequence increment, so no gap
    if (err.code === "23505") return sendMessage(db, conversationId, clientMsgId, senderId, body); // raced a retry
    throw err;
  } finally {
    client.release();
  }
}

The messages table has PRIMARY KEY (conversation_id, seq) and UNIQUE (conversation_id, client_msg_id). Tested on Postgres 16: 50 messages sent to one conversation at once got sequence numbers 1 to 50 with no gaps. Retrying message 7 twice at the same moment returned its original number both times. A new message sent three times at once (a phone retrying on a flaky network) was stored once, as number 51, and the counter stayed at 51: the losing attempts rolled back their increments. 500 messages into one conversation took 120 ms; the row lock on the conversation serialises its writes, which is fine for a group of 500 and a reason to avoid one counter for a channel of millions.

Receipts and presence. "Read" isn't a flag per message per reader: it's one number per member per conversation, read_up_to_seq, updated as they scroll. "Delivered" works the same way. Presence uses heartbeats with a timeout and is shown only to people who have the chat open (12.02 Presence).

Very large groups. Above a few thousand members, fan-out per message becomes the cost. Systems like Slack route each channel to a stateful channel server that pushes to the gateways subscribed to it.

6. Wrap-up

What breaks first: reconnect storms when a gateway restarts and 100,000 clients reconnect at once, so clients back off with jitter and gateways drain slowly (12.01 Millions of WebSocket connections); then hot conversations, a single group whose owner instance and partition get every write.

Recap

Interview questions