system-design · intermediate

Design WhatsApp — 1:1 and Group Messaging

Start here

Design WhatsApp (simplified) means:

• Users send text messages 1:1 and in groups
• Online recipients get messages quickly
• Offline recipients receive messages later
• Optional: last-seen, delivery/read receipts, multi-device

What you will learn

1. Clarify chat MVP vs voice/video/status.
2. Design gateway connections (WebSocket/long poll).
3. Route messages via user sessions.
4. Store messages for offline and history.
5. Fan-out group messages without O(n²) disasters.
6. Discuss receipts, order, and multi-device.

Words you need before we begin

Requirements

Functional MVP

• 1:1 chat
• Group chat (bounded size for MVP, e.g. 256)
• Offline delivery
• Message history pagination

Non-functional

• Low latency for online delivery
• High durability (messages not lost)
• High connection count

Scale assumptions (example)

• 1B users, 100M online peak
• 20 messages/user/day average → large aggregate QPS
• Groups fan-out dominates complexity

High-level design

flowchart LR
  U1[User A] --> GW[Connection gateways]
  U2[User B] --> GW
  GW --> Chat[Chat service]
  Chat --> Sess[(Session directory)]
  Chat --> Store[(Message store)]
  Chat --> Q[Per-user inbox / queue]
  GW --> Push[Push notifications]

Step-by-step design

Step 1 — Connections

Mobile keeps WebSocket to a gateway. Gateways are many; a session directory maps userId → gatewayId/connectionId (and device ids).

Step 2 — Send 1:1

1. A sends message with clientMsgId.
2. Chat service persists message.
3. Lookup B’s active sessions.
4. If online, push to gateway(s); if offline, leave in inbox and trigger mobile push notification.
5. Ack to A (server received).

Step 3 — Offline inbox

When B connects, drain inbox / fetch since cursor. Mark delivered.

Step 4 — Groups

Options:

• Write fan-out: expand members, enqueue to each inbox (simple reads; heavy writes for large groups).
• Read fan-out: store once per group; members pull group stream (lighter writes; more read logic).

Step 5 — Ordering

Per-chat monotonic server timestamps or sequence numbers. Client shows pending until ack. Do not assume global order across chats.

Step 6 — Receipts

Separate events: server-ack, device-delivered, read. Treat as messages/events themselves with care for privacy settings.

Step 7 — Multi-device

Session directory holds multiple devices; fan-out to all devices; sync cursors per device.

Failure modes

Trade-offs

Common mistakes

1. One giant WebSocket server.
2. No client message ids.
3. Ignoring multi-device.
4. Perfect global ordering.
5. Building full E2E crypto in 45 minutes—mention, do not implement.

Check your understanding

1. What does the session directory store?
2. How does offline delivery work?
3. Why clientMsgId?
4. Name two group fan-out strategies.
5. What fails when a gateway process dies?

Practice

1. Sequence diagram for 1:1 offline recipient.
2. Estimate connections for 50M online users.
3. Design inbox schema keys.
4. Discuss read receipts privacy.
5. Role-play interview with timer.

Deeper production notes

Backpressure

Gateways must limit slow consumers; otherwise memory buffers explode.

Push notifications

APNs/FCM integration is a separate unreliable path—dedupe with in-app delivery.

Additional teaching scenarios

Scenario A — 10× peak

Scenario B — partial outage

Scenario C — interview wrap

Revision summary

• Chat = connections + durable messages + routing.
• Session directory finds online devices.
• Persist for reliability; fan-out groups carefully.
• Idempotency and reconnect are mandatory.

Glossary

Abbreviations and terminology

• WS — WebSocket
• E2E — End-to-end encryption
• FCM/APNs — Mobile push providers

What to learn next

1. Chat system design
2. WebSockets
3. Message queues
4. Design notification service

Extra teaching notes

When you apply this lesson, write the user-visible success metric first, then the failure mode you fear most. Design the smallest mechanism that protects that metric under partial failure. Prefer explicit timeouts, idempotency, and ownership over adding more infrastructure boxes.

In interviews or design reviews, narrate assumptions, request paths, and trade-offs out loud. A correct-enough design with clear failure handling beats a buzzword diagram without numbers. Revisit the worked example and restate it for a different domain to prove you own the ideas, not the template wording.

Extra teaching notes

When you apply this lesson, write the user-visible success metric first, then the failure mode you fear most. Design the smallest mechanism that protects that metric under partial failure. Prefer explicit timeouts, idempotency, and ownership over adding more infrastructure boxes.

In interviews or design reviews, narrate assumptions, request paths, and trade-offs out loud. A correct-enough design with clear failure handling beats a buzzword diagram without numbers. Revisit the worked example and restate it for a different domain to prove you own the ideas, not the template wording.

Extra teaching notes

When you apply this lesson, write the user-visible success metric first, then the failure mode you fear most. Design the smallest mechanism that protects that metric under partial failure. Prefer explicit timeouts, idempotency, and ownership over adding more infrastructure boxes.

In interviews or design reviews, narrate assumptions, request paths, and trade-offs out loud. A correct-enough design with clear failure handling beats a buzzword diagram without numbers. Revisit the worked example and restate it for a different domain to prove you own the ideas, not the template wording.

Extra teaching notes

When you apply this lesson, write the user-visible success metric first, then the failure mode you fear most. Design the smallest mechanism that protects that metric under partial failure. Prefer explicit timeouts, idempotency, and ownership over adding more infrastructure boxes.

In interviews or design reviews, narrate assumptions, request paths, and trade-offs out loud. A correct-enough design with clear failure handling beats a buzzword diagram without numbers. Revisit the worked example and restate it for a different domain to prove you own the ideas, not the template wording.

Extra teaching notes

When you apply this lesson, write the user-visible success metric first, then the failure mode you fear most. Design the smallest mechanism that protects that metric under partial failure. Prefer explicit timeouts, idempotency, and ownership over adding more infrastructure boxes.

In interviews or design reviews, narrate assumptions, request paths, and trade-offs out loud. A correct-enough design with clear failure handling beats a buzzword diagram without numbers. Revisit the worked example and restate it for a different domain to prove you own the ideas, not the template wording.

Interview and production field guide for this topic

Use this section as deliberate practice, not filler. Rewrite the worked example for a second domain you know well—fintech, education, logistics, or media. Keep the same skeleton: requirements, estimates, high-level diagram, request path, data model, scale lever, failure modes, and trade-offs. If you cannot fill every section without copying buzzwords, you do not yet own the design.

Numbers to force yourself to state

Always speak order-of-magnitude figures: peak QPS, storage growth per day, fan-out factor, connection counts, or queue depth. Wrong numbers that are explicit beat silent hand-waving. Correct the numbers when the interviewer or teammate challenges them; that is collaboration, not failure.

Failure minute

Set a timer for sixty seconds and list only failures: timeouts, duplicates, hot keys, dependency outages, bad deploys, and data corruption paths. For each, name detection and first mitigation. Designs that only describe the happy path are incomplete for production and weak in interviews.

Ownership and operability

Name the dashboard, the alert, the runbook section, and the team that pages. If any are blank, the system will train you during an incident. Prefer progressive delivery: canaries, flags, and rollback notes written before the change lands.

Consistency and retries

State whether the design assumes at-least-once delivery, whether handlers are idempotent, and where unique constraints live. Retries without idempotency are how double charges, double messages, and duplicate fan-out jobs appear. Timeouts without bounds are how thread pools die.

What good looks like in a review

A strong design review or interview answer clarifies scope, makes assumptions audible, draws a minimal path, deepens one or two bottlenecks, and closes with trade-offs and evolution. Use that bar on design-whatsapp round 0 every time you revisit it.

Interview and production field guide for this topic

Use this section as deliberate practice, not filler. Rewrite the worked example for a second domain you know well—fintech, education, logistics, or media. Keep the same skeleton: requirements, estimates, high-level diagram, request path, data model, scale lever, failure modes, and trade-offs. If you cannot fill every section without copying buzzwords, you do not yet own the design.

Numbers to force yourself to state

Always speak order-of-magnitude figures: peak QPS, storage growth per day, fan-out factor, connection counts, or queue depth. Wrong numbers that are explicit beat silent hand-waving. Correct the numbers when the interviewer or teammate challenges them; that is collaboration, not failure.

Failure minute

Set a timer for sixty seconds and list only failures: timeouts, duplicates, hot keys, dependency outages, bad deploys, and data corruption paths. For each, name detection and first mitigation. Designs that only describe the happy path are incomplete for production and weak in interviews.

Ownership and operability

Name the dashboard, the alert, the runbook section, and the team that pages. If any are blank, the system will train you during an incident. Prefer progressive delivery: canaries, flags, and rollback notes written before the change lands.

Consistency and retries

State whether the design assumes at-least-once delivery, whether handlers are idempotent, and where unique constraints live. Retries without idempotency are how double charges, double messages, and duplicate fan-out jobs appear. Timeouts without bounds are how thread pools die.

What good looks like in a review

A strong design review or interview answer clarifies scope, makes assumptions audible, draws a minimal path, deepens one or two bottlenecks, and closes with trade-offs and evolution. Use that bar on design-whatsapp round 1 every time you revisit it.

FAQ from first-time learners

Q: Kafka for every message?
A: Possible for fan-out pipelines; also discuss simpler queues—justify.

Q: SQL for messages?
A: Possible with partitioning by chatId; many designs use wide-column/log stores—justify access patterns.

Q: Exactly-once chat?
A: Aim for at-least-once + dedupe ids.

Track: Distributed Systems

Previous: Design Uber — Matching Riders and Drivers

Next: Design YouTube — Upload, Process, and Stream Video

By Shubham Jain

All articles · Study paths

Shubham Jain · Learning Lab