Design a Notification system

01Concrete scale assumptions

02Architecture decisions and rationale

03Client contracts and data boundaries

1type Notification = { id: string; version: number; category: string;2  title: string; body: string; href?: string;3  createdAt: string; readAt: string | null };4type ReadCommand = { notificationIds: string[]; readAt: string; mutationId: string };

04Failure-mode analysis

05Observability and operations

• Measure accepted, delivered, displayed, opened, dismissed, deduplicated, and failed events per channel and category.
• Track socket connection health, reconnect attempts, cursor catch-up duration, push subscription churn, and preference suppression.
• Correlate event and delivery attempt ids while excluding notification body and other private content from logs.
• Use synthetic notifications and dead-letter monitoring to prove the entire delivery path, not only API uptime.

06Security and accessibility boundaries

• Authorize inbox reads and deep-link destinations independently; an opaque id is not authorization.
• Keep sensitive content out of lock-screen push payloads and escape all sender-controlled text and URLs.
• Use polite live announcements for new items without moving focus; urgent semantics are reserved for genuinely urgent events.
• Make permission, channel, category, digest, mute, and unsubscribe controls clear and keyboard operable.

ANSOne full answer, start to finish

Drive the discussion yourself first. This is one strong answer delivered the way you would say it in the room — a model, not the only correct design.

The key framing: the real-time channel is an accelerator, not the source of truth. A REST or GraphQL API is the durable record, and the socket just makes things feel instant. Say that early, then the rest is about read-state staying consistent across a user's devices and clients reconciling after they have been offline.

1. Step 1 · Clarify

   Ask: 'In-app only, or push notifications too? How many devices per user typically? Do users configure what they get notified about? And how urgent — is a few seconds of delay acceptable?' Assumptions: 'Both in-app and push, two to three devices per user, per-category preferences, and a few seconds of delay is fine for most categories.' Multiple devices is what makes read-state the hard part.

2. Step 2 · Requirements

   User-facing: see new notifications quickly, an accurate unread badge, and marking one read on your phone updates your laptop. Hidden: no duplicates even though delivery is not exactly-once, the unread count stays consistent across devices and tabs, and a client that was offline catches up correctly.

3. Step 3 · Two layers: API of record, socket as accelerator

   'A REST or GraphQL API is the authoritative source for notification state — the list, the read flags, the count. A WebSocket, or Server-Sent Events for the simpler one-way case, pushes new notifications and read-state changes to a user's open clients so they update instantly. But if the socket drops, a fallback poll still converges the client to correct state. The socket is never the only path.'

4. Step 4 · Delivery pipeline

   'When an event happens server-side, the delivery service checks the user's preferences — category, channel, quiet hours — to decide whether to notify in-app, via push, or both. The notification is persisted first, then pushed over the socket to any connected clients, updating their unread count immediately.'

5. Step 5 · Duplicates and read-state

   'Every notification carries a stable event id. Clients upsert by that id rather than assuming the transport delivered it exactly once, so an echo or a replay does not create a second entry. Marking one read sends an update to the server, which broadcasts the new read state to the user's other connected devices so their badges match. The count itself is monotonic and versioned so a stale update cannot decrement it wrongly.'

6. Step 6 · Reconnect

   'A client coming back online does not trust that the socket stream caught it up. It fetches current state from the API — the recent list and the authoritative unread count — and reconciles. Cursor-paginated history is what makes this recovery reliable.'

7. Step 7 · Push payloads and permission

   'Push payloads are minimal and display-safe — a wake-up or a short summary, never sensitive content on a lock screen — and the app fetches the real authorized data when opened. I ask for notification permission only after the user has done something that shows they want notifications, never on first load.'

QAInterview questions and model answers