Loading…

Understanding the problem

Many teams need to reach the same users: accounts sends login codes, orders sends shipping updates, marketing sends promotions. A notification system is the one service they all call: it finds where each user can be reached, applies what they want, renders the words and hands each message to a provider. The hard parts are off the happy path: failing providers, retrying callers, campaigns competing with login codes, and users who change their minds while a message waits.

The practice brief sets the scope below. Confirm the three tiers early (urgent, transactional, marketing), because they drive quiet hours, retries and capacity, and confirm that the provider rates are contracted limits.

Functional requirements

CoreAny team's service can send a notification to a user by category (for example "login code", "order shipped", "promotion"), in the user's language (12 are supported).
CoreDeliver by mobile push, email, SMS and an in-app inbox, depending on the category and what the user has.
CoreUsers choose which categories they get on which channels, and set quiet hours in their own time zone; marketing goes only to users who opted in.
CoreSchedule a notification for later, and send a campaign to an audience of up to 100 million users; a running campaign can be stopped.
CoreSenders can look up the status of each notification, and see sent, delivered and opened counts for each campaign.
Below the lineBuilding campaign audiences (a campaign names an audience that already exists).
Below the lineThe template editor.
Below the lineA/B tests.
Below the lineWeb push and voice calls.
Below the lineDigests that fold several notifications into one.Useful, but it adds per-user state and timing on top of the core flow.
Below the lineChoosing the best time to send for each user.A ranking problem of its own; the platform only honours a send window it is given.

Non-functional requirements

DurabilityEvery notification the service accepts reaches a final status on each channel (sent to the provider, delivered where the channel reports it, failed, or skipped because of the user's choices), and its sender can see which.
ConsistencyA retried request or a replayed event never creates a second notification, and the platform never re-sends a message a provider has confirmed taking.
LatencyLogin codes and security alerts reach the provider within about 5 seconds at the 99th percentile, even during the biggest campaign; order and account updates within 30 seconds; marketing can take hours.
AvailabilityAccepting notifications stays available (99.99%), even when a whole region is down.
Cost

Scale

From the briefNumbers here are given in the practice brief.

ScaleAbout 500 million users, in every time zone.
ScaleAbout 5 billion sends a day: about 75% push, 20% email, 4% in-app only and 1% SMS (mostly login codes).
ScaleThe busiest hour runs at about three times the average.
ScaleContracted provider rates (this problem's givens): push 200,000 a second; email 50,000 a second; SMS 2,000 a second. There are two email providers and two SMS providers, and either one of a pair can carry its channel's full rate on its own.
ScaleLogin codes alone can reach about 1,000 SMS a second at the busiest moment.
ScaleThe largest campaign goes to 100 million users. The service runs in several regions.

Out of scope

Out of scopeChoosing who is in an audience, and ad targeting.
Out of scopeChecking message content for spam.
Out of scopeBilling teams for what they send.

Check yourself

Why rule out exactly-once delivery loudly?
Show answerHide answer
A timed-out provider call may or may not have sent the message. The honest design retries (at-least-once), uses keys and status checks to make repeats rare, and says so.

The numbers that shape the design

Illustrative exampleNumbers here are illustrative: round figures to reason with, not measurements.

Start from the brief’s givens and set each channel against its contracted rate. The point is which numbers change the design, not the exact figures.

Back of the envelope from the brief

Quantity	Value	What it means
Sends	Brief: 5 billion a day; about 58,000 a second	5 billion divided by 86,400 seconds.
Busiest hour	About 175,000 a second	The brief’s three times the average.
Push at the peak	About 131,000 of a contracted 200,000 a second	About 75% of sends; roughly 70,000 a second of room.
Email at the peak	About 35,000 of 50,000 a second	About 20% of sends.
SMS at the peak	About 1,750 of 2,000 a second	About 1% of sends, and login codes alone reach about 1,000 a second: almost no room.
In-app at the peak	About 7,000 a second	About 4%, written to our own inbox store.
A 100 million push campaign	About 24 minutes	In the push room at the peak; hours by email, days by SMS.
Delivery history	About 225 TB before copies	90 days at an illustrative 500 bytes a record.

Architecture diagramWhere the busiest hour meets the provider limits

Read:Learn: Numbers and capacity estimation

Try it: The numbers that shape the designGuided practice · Notification service, Notification platform · Senior

Check yourself

Which single number most shapes this design?
Show answerHide answer
SMS at the busiest hour: about 1,750 of 2,000 texts a second, with login codes needing about 1,000. It forces separate queues per tier and a reserved share of the provider’s rate.

Core entities

One notification goes to several places, each with its own fate: the push to the tablet can fail while the email arrives. So the model keeps one delivery record per channel and address. Settings, devices and addresses are small and read on every send; the delivery log is huge, write-heavy and expires after the brief’s 90 days.

The records that matter

Entity	Key fields	Why it exists
Notification	`notification_id`, `caller`, `category`, `template_id`, `values`, `user_id`, `tier`	What the calling team asked for.
Delivery	`notification_id`, `channel`, `address`, `status`, `provider`, `attempts`	One per channel and address, each with its own status.
Device and address	`user_id`, `device_id`, `push_token`, `last_seen`; `user_id`, `channel`, `address`	Where the user can be reached; tokens change and die.
Setting	`user_id`, `category`, `channel`, `enabled`, plus quiet hours and time zone	What the user wants, per kind of message and channel.
Request key	`caller`, `key`, `notification_id`	Lets a retried request find the first notification.
Template and campaign	`template_id`, `channel`, `locale`, `version`; `campaign_id`, `status`	The words per channel and language, and one record per campaign.

Architecture diagramThe records and where they live

Read:Learn: Data model design Learn: Storage choice justification Learn: Apache Cassandra

Try it: Notifications, people and their devicesGuided practice · Notification service, Notification platform · Senior

Check yourself

Why not keep one status column on the notification?
Show answerHide answer
Because one notification becomes several deliveries that succeed and fail independently, and the sender needs to see each one.

The API

Callers send a category, the recipient, a template and its values, and the platform renders each channel’s form in the user’s language, with a default when a translation is missing.

The send takes a key the caller picks once and reuses on every retry. The service records the key with the notification in one step that refuses a second copy, so two copies arriving together cannot both win, and a repeat gets the first notification back. Stripe’s API works the same way: the first result is saved and returned for later requests with the same key, and keys can be pruned after 24 hours (Stripe docs (opens in a new tab)).

A compact contract

Call	Request	Response	Errors
`POST /v1/notifications`	`Idempotency-Key`; `category`, `user_id`, `template_id`, `values`	`202` with `notification_id`; a repeat returns the same id	`400`; `403` category not allowed; `429`
`GET /v1/notifications/{id}`	Caller auth	Each delivery’s channel, status and reason	`404`
`POST /v1/campaigns`, `…/{id}/stop`	Audience, template, send window	`201` with `campaign_id`; stop answers `202`	`400`, `404`
`POST /v1/devices`	App auth; `platform`, `push_token`	`201`; replaces the device’s old token	`400`
`GET /v1/inbox`, `PUT /v1/settings`	App auth	Inbox items with an unread count; the user’s settings	`400`, `401`

Architecture diagramA retried request finds the first notification

Read:Learn: Idempotency and retries Learn: API contract design

Try it: What a team sends, and what it gets backGuided practice · Notification service, Notification platform · Senior

Check yourself

The API looks the key up, and inserts it if it is missing. What goes wrong?
Show answerHide answer
Two copies arriving together both find nothing and both insert, so the user gets two texts (for a login code, two different codes). Record the key in one step that refuses a duplicate, such as a unique constraint or a conditional put.

High-level design

Two flows carry the design: sending, with no provider call on the caller’s path, and the in-app inbox, the one channel the platform runs itself.

Accept a request, then send it on each channel

The API calls no provider on the caller’s path: it records the key, queues the request and replies. Each channel’s workers call their providers through an adapter, so a channel can use more than one provider, and a slow email provider backs up only the email queue.

The orders service calls POST /v1/notifications with a key, the category, the user and the values.
The API records the key, writes to the accepted queue and replies 202 with the notification id.
The router finds the user’s devices, addresses and settings, and renders each channel.
It puts one job on each channel’s queue; workers send through that channel’s providers and write the status.

Architecture diagramAccept, then send on each channel

The API only accepts; each channel has its own queue, workers and providers, so a slow provider backs up only its own channel.

Diagram as text

Components: Orders service (Service); Notification API (API gateway); Accepted queue (Queue); Router (Service); Settings and devices (Cache); Push queue (Queue); Email queue (Queue); SMS queue (Queue); In-app queue (Queue); Push workers (Worker); Email workers (Worker); SMS workers (Worker); In-app workers (Worker); APNs and FCM (External API); Email providers (External API); SMS providers (External API); Inbox store (NoSQL DB). Connections: Orders service → Notification API (POST); Notification API → Accepted queue (write, then 202); Accepted queue → Router; Router → Settings and devices (look up); Router → Push queue; Router → Email queue; Router → SMS queue (a job per channel); Router → In-app queue; Push queue → Push workers; Email queue → Email workers; SMS queue → SMS workers; In-app queue → In-app workers; Push workers → APNs and FCM; Email workers → Email providers; SMS workers → SMS providers; In-app workers → Inbox store.

Read:Learn: High-level architecture Learn: Producer-consumer / work queue

Try it: A shipping update, end to endGuided practice · Notification service, Notification platform · Senior

Check yourself

The email provider starts taking two seconds per message. What happens to a login code sent by SMS at that moment?
Show answerHide answer
Nothing: it goes on the SMS queue and SMS workers send it. Only the email queue backs up.

The in-app inbox

In-app has no outside provider, and it must be there whenever the app opens, on any device. In-app workers store each item in the user’s inbox, newest first, with read state and an unread count. If the app is open, the item also goes down the connection it already keeps, such as a WebSocket. Reading on one device marks the item read on the server, so the count drops everywhere.

Architecture diagramThe in-app inbox

Design a notification system

The answer in two minutes

Also asked as

What interviewers look for

The decisions that matter

Understanding the problem

Functional requirements

Non-functional requirements

Scale

Out of scope

The numbers that shape the design

Core entities

The API

High-level design

Accept a request, then send it on each channel

The in-app inbox

Sign in with Google to read the rest

Practise this

The answer in two minutes

Also asked as

What interviewers look for

The decisions that matter

01Understanding the problem

Functional requirements

Non-functional requirements

Scale

Out of scope

02The numbers that shape the design

03Core entities

04The API

05High-level design

Accept a request, then send it on each channel

The in-app inbox

Sign in with Google to read the rest

12Practise this

Understanding the problem

The numbers that shape the design

Core entities

The API

High-level design

Practise this