Designing a Real-Time Notification Platform.

A Friday evening at the super-app: payments, bill pay, group chats, 50 million users, and every product team sending notifications through whatever queue was closest. (An illustrative scene: the people, times and amounts are made up; each failure is a classic one, and the arithmetic uses this lesson's numbers.)

None of these needs a clever algorithm. Each is a piece of the platform that wasn't there: a priority lane, a preference check at send time, a durable inbox with a live connection, presence that expires by itself, and a channel policy that knows what an SMS costs.

This week builds those pieces as one system. Today is the whole-system view: requirements, numbers, architecture, data model and channel trade-offs. Each of the next four days goes deep on one part.

01Chapter 1: What We're Building#

1.1 The Simple Definition#

A notification platform is one shared service that takes "tell user U about event E" from any team, decides whether, how and when to tell them, and gets it there over the right channel. It has two halves, and this week's title is about the second:

• Store and forward through providers. Push (APNs, FCM), SMS and email: we hand the message to someone else's network, and "delivered" mostly means "a provider accepted it".
• Real time to online users. When the app is open, we hold a connection and push down it ourselves, in under a second. Here we are the provider.

The same tier that pushes "₹2,400 received" to Priya's open browser also carries chat messages and the green "online" dots, so a notification platform and a chat backend share their bottom half.

1.2 Why One Platform#

Every company starts with each team calling Twilio or FCM directly, until users notice the sum of it.

LinkedIn describes exactly this: one team's logic "about how often or to whom to send notifications would have been isolated to that team", which "led to a non-regulated, excessive, and low-quality member notification experience" (LinkedIn Engineering, 2018).

1.3 The Interview Opening#

"Design a notification system" is a common interview prompt, and its trap is that everyone knows roughly what the boxes are. Don't draw them yet. Spend the first five minutes on questions, using FERNS:

02Chapter 2: Requirements#

2.1 The Clarifying Dialogue#

2.2 The Requirements, Written Down#

Read the summary back before designing. It catches misunderstandings while they're cheap.

2.3 Five Classes of Notification#

The most useful thing to write down: notifications are not all the same. Each class has its own clock, channels and tolerance for delay, and the architecture follows from the differences.

The lane column is a preview: Day 2 designs the lanes, and Day 5 makes them hold all the way to the provider.

03Chapter 3: Estimates#

3.1 Before the Numbers#

Two numbers shape this design most: how the 500 million split across channels, and what each channel costs. Guess first.

3.2 The Worked Estimate#

The route matters as much as the volume. Per AWS's documentation, international routes to India are "significantly higher" in price than local routes, and local routes require registering your use case and message templates with TRAI through a DLT portal (AWS End User Messaging docs). An unregistered template doesn't get the local price.

3.3 What We Store#

Rough sizes, to decide where each kind of data lives (assumed record sizes):

Two families. Preferences and tokens are small and read on every send: cache them. Notifications, deliveries and inbox items are big and time-ordered: partition by user and time, and drop old partitions instead of deleting rows.

04Chapter 4: The Whole System#

4.1 The Pieces#

%% title: The real-time notification platform: every piece this week builds
flowchart TD
  SVC@{ icon: "sd:server", label: "Product services<br/>payments, security, chat, marketing" }
  API["Ingest: Send API<br/>validate, idempotency key, 202"]:::core
  OB@{ icon: "tech:postgresql", label: "PostgreSQL<br/>notifications + outbox, one transaction" }
  K@{ icon: "tech:kafka", label: "Kafka priority lanes<br/>critical · transactional · bulk" }
  RT["Pipeline: router<br/>preferences, quiet hours, dedup, schedule"]:::core
  PREF@{ icon: "tech:redis", label: "Redis: preferences + tokens<br/>PostgreSQL behind" }
  PW["Push workers"]:::service
  SW["SMS workers"]:::service
  EW["Email workers"]:::service
  IA["In-app delivery<br/>inbox write, seq per user"]:::core
  APNS@{ icon: "tech:apple", label: "APNs" }
  FCM@{ icon: "tech:firebase", label: "FCM" }
  SMS@{ icon: "sd:sms", label: "SMS providers<br/>registered local routes" }
  EM@{ icon: "tech:sendgrid", label: "Email provider<br/>SendGrid or SES" }
  IB@{ icon: "sd:database", label: "Inbox<br/>per user, ordered by seq" }
  GW@{ icon: "sd:gateway", label: "Real-time gateways<br/>WebSocket and SSE, ~10M sockets" }
  PR["Presence and chat fan-out"]:::service
  DEV@{ icon: "sd:phone", label: "Apps and browsers" }
  SVC --> API
  API --> OB
  OB -->|"outbox relay"| K
  K --> RT
  RT -.->|"lookup"| PREF
  RT --> PW
  RT --> SW
  RT --> EW
  RT --> IA
  PW --> APNS
  PW --> FCM
  SW --> SMS
  EW --> EM
  IA --> IB
  IA -->|"live hint"| GW
  PR --> GW
  GW --> DEV
  class SVC service
  class OB,IB store
  class K queue
  class PREF cache
  class APNS,FCM,SMS,EM external
  class GW edge
  class DEV client

Seven pieces, each with one job:

1. Ingest. The Send API validates {user, type, template, variables} and writes the notification and an outbox row in one transaction (Week 3, Day 2 · Transactional Outbox), then returns 202 Accepted. The caller's idempotency key turns a retry into the same notification, not a second one (Week 2, Day 2 · Idempotency in Practice). Ingest never calls a provider, so the payment service never waits on one.
2. Preferences. Consent, per-category and per-channel switches, quiet hours and device tokens. Read on every send, so cached (Week 4, Day 1 · Caching Patterns); written rarely, but an unsubscribe must apply in seconds.
3. The pipeline. An outbox relay publishes to priority lanes, Kafka topics with their own consumers. The router looks up preferences and tokens, picks channels, applies quiet hours and caps, drops duplicates, holds scheduled sends, and writes one task per channel.
4. Channel workers. One pool per channel, each speaking one provider's protocol within its rate limits. A failure that might heal (a timeout) is retried with backoff; one that won't (an uninstalled app) triggers the fallback channel.
5. The inbox. Every in-app notification is written to a durable per-user inbox with a sequence number before anyone is told. The bell, the unread count and the history all read from it.
6. The real-time gateways. One long-lived WebSocket or SSE connection per online device, ~10M at peak. A connection registry says which gateway holds which user; in-app delivery sends that gateway a small "seq 1184 is ready" hint. Lose the hint and the client resumes from the inbox: the socket is a fast path, never the record.
7. Presence. Who's online, as soft state: heartbeats with an expiry, so a dead phone goes offline by itself. Chat and presence reuse the gateways.

Around them: templates rendered per channel and language, provider callbacks (receipts, bounces, complaints) by webhook, and an audit store, an append-only log in a columnar store like ClickHouse.

4.2 One Notification, End to End#

Follow Arjun's ₹2,400 with the platform in place. Priya's web app is open; her phone is in her bag.

%% title: Payment received: from the payment service to Priya's screen
sequenceDiagram
  autonumber
  participant PS as Payment service
  participant API as Send API
  participant Q as Outbox and lanes
  participant RT as Router
  participant PF as Preferences
  participant IA as In-app delivery
  participant GW as Gateway gw-17
  participant B as Priya's browser
  participant PW as Push worker
  PS->>API: send(priya, payment_received, 2400 from Arjun), key txn-9f3
  API->>Q: notification row and outbox row, one transaction
  API-->>PS: 202 Accepted, notification n-81
  Q->>RT: transactional lane
  RT->>PF: preferences and devices for priya
  PF-->>RT: in-app on, push on, web session live
  RT->>IA: in-app task
  IA->>IA: inbox append, seq 1184
  IA->>GW: hint for priya, seq 1184
  GW-->>B: seq 1184, 2400 rupees received from Arjun
  B->>GW: ack 1184
  Note over IA,PW: acked within 5 s, so no push for a routine payment
  Note over RT,PW: no live device or no ack, then push via APNs or FCM

In a typical design the live path takes a few hundred milliseconds: two queue hops, two cache reads, an inbox write and a socket write. Two details carry the week:

• The inbox write comes before the socket push. If gw-17 crashes between steps 9 and 10, Priya's browser reconnects elsewhere and asks for "everything after 1183". Nothing is lost.
• Push depends on the ack. No ack within a few seconds means the socket was probably dead, so the platform falls back to push (Day 3).

4.3 The Router's Policy, in Code#

The router turns Chapter 2's class table into behaviour. A sketch of its core decision (Day 2 builds the real one):

# pipeline/plan.py: which channels, in which order (illustrative)
from datetime import datetime

POLICY = {
    # class:          (lane,            send first,        then, in order, on failure or no ack)
    "critical":      ("critical",      ["push"],          ["sms", "email"]),   # alerts: unread after 2 min, SMS (Day 2)
    "transactional": ("transactional", ["in_app"],        ["push", "email"]),
    "social":        ("transactional", ["in_app"],        ["push"]),
    "reminder":      ("transactional", ["push"],          ["email"]),
    "marketing":     ("bulk",          ["push"],          ["email"]),
}

def plan(n, prefs, now: datetime) -> dict:
    lane, first, fallbacks = POLICY[n.cls]
    if n.category == "otp":
        first, fallbacks = ["sms"], []              # a code is useless late: SMS at once, no ladder
    if n.cls == "transactional" and prefs.sms_alerts_for(n.category):
        fallbacks = fallbacks + ["sms"]             # the user asked for SMS on payments

    def ok(channel):                                # critical alerts can't be opted out of
        return n.cls == "critical" or prefs.allows(n.category, channel)

    send_at = now
    if n.cls in ("reminder", "marketing") and prefs.in_quiet_hours(now):
        send_at = prefs.quiet_hours_end(now)        # defer, don't drop
    return {
        "lane": lane,
        "now": [c for c in first if ok(c)],
        "fallback": [c for c in fallbacks if ok(c)],   # in-app with no live socket counts as "no ack"
        "send_at": send_at,
    }

Four choices to notice: critical traffic ignores opt-outs and quiet hours (a 2 am fraud alert is the point); quiet hours defer rather than drop; fallbacks run only when the first channel fails or goes unacknowledged, which is what keeps SMS at 5%; and an OTP skips the ladder, going by SMS at once, because a code that arrives late is useless. A security or fraud alert starts with push and escalates to SMS if it's still unread after 2 minutes (Day 2's escalation saga).

05Chapter 5: The Data Model#

5.1 Five Records#

Most of the platform's correctness lives in how these records are separated:

%% title: The data model: what is stored, and how the records relate
flowchart TD
  U["user<br/>user_id · locale · timezone · phone · email"]:::core
  P@{ icon: "sd:database", label: "preferences<br/>user_id · category · channel · enabled<br/>quiet hours · consent log" }
  D@{ icon: "sd:phone", label: "device_tokens<br/>token · platform · status · last_seen" }
  N@{ icon: "sd:bell", label: "notifications<br/>notification_id · user_id · class<br/>template · variables · idempotency_key" }
  DL@{ icon: "sd:log", label: "deliveries<br/>notification_id · channel · provider_msg_id<br/>status · attempts · error" }
  I@{ icon: "sd:feed", label: "inbox_items<br/>user_id · seq · notification_id<br/>title · body · read_at" }
  U -->|"1 to many, one per category and channel"| P
  U -->|"1 to many"| D
  U -->|"1 to many"| N
  N -->|"1 to many, one per channel"| DL
  N -->|"1 to 0 or 1"| I
  class P,D,N,DL,I store

• notifications: the logical event, one per user per event ("Priya received ₹2,400", n-81), holding the idempotency key so a retry finds the existing row.
• deliveries: one per channel attempt. A fraud alert sent by push and then, still unread, by SMS is one notification with two deliveries, each with its provider message id and status, so "did the user get it?" and "did the SMS fail?" are separate questions.
• inbox_items: what the bell shows, keyed by (user_id, seq). The sequence number gives the order, makes "everything after 1183" a range read and makes gaps visible. Read state lives here.
• preferences: one row per (user, category, channel), plus quiet hours, timezone and a consent log. The switch says what to do; the log proves you were allowed to.
• device_tokens: one per app install, with a status and last-seen time, because tokens change on reinstall and providers report dead ones.

A condensed schema, trimmed to what the design needs:

CREATE TABLE notifications (
    notification_id  UUID        NOT NULL,
    user_id          UUID        NOT NULL,
    class            TEXT        NOT NULL,      -- critical | transactional | social | reminder | marketing
    category         TEXT        NOT NULL,      -- e.g. otp, payments, security, offers
    template         TEXT        NOT NULL,
    variables        JSONB,
    idempotency_key  TEXT        NOT NULL,      -- from the caller: same key, same notification
    send_at          TIMESTAMPTZ,               -- null = now
    created_at       TIMESTAMPTZ NOT NULL DEFAULT now(),
    PRIMARY KEY (notification_id, created_at)
) PARTITION BY RANGE (created_at);            -- one partition a day or a month; drop old ones whole
-- dedup is checked within the retention window by a unique index per partition or a key store

CREATE TABLE deliveries (
    notification_id  UUID        NOT NULL,
    channel          TEXT        NOT NULL,      -- push | sms | email | in_app
    target           TEXT        NOT NULL,      -- token id, phone, address; user id for in-app
    provider_msg_id  TEXT,                      -- what the provider calls it, for callbacks
    status           TEXT        NOT NULL,      -- queued | sent | delivered | failed | bounced | read
    attempts         INT         NOT NULL DEFAULT 0,
    last_error       TEXT,
    updated_at       TIMESTAMPTZ NOT NULL DEFAULT now(),
    PRIMARY KEY (notification_id, channel, target)
);

CREATE TABLE inbox_items (                    -- partitioned by user_id in production
    user_id          UUID        NOT NULL,
    seq              BIGINT      NOT NULL,      -- per-user, strictly increasing
    notification_id  UUID        NOT NULL,
    title            TEXT        NOT NULL,
    body             TEXT,
    deep_link        TEXT,
    created_at       TIMESTAMPTZ NOT NULL,
    read_at          TIMESTAMPTZ,
    PRIMARY KEY (user_id, seq)
);

CREATE TABLE preferences (
    user_id   UUID    NOT NULL,
    category  TEXT    NOT NULL,
    channel   TEXT    NOT NULL,
    enabled   BOOLEAN NOT NULL,
    version   INT     NOT NULL DEFAULT 1,      -- optimistic locking for concurrent edits
    PRIMARY KEY (user_id, category, channel)
);

CREATE TABLE device_tokens (
    token_id    UUID PRIMARY KEY,
    user_id     UUID NOT NULL,
    platform    TEXT NOT NULL,                 -- ios | android | web
    token       TEXT NOT NULL UNIQUE,
    status      TEXT NOT NULL DEFAULT 'active',-- active | invalid
    last_seen   TIMESTAMPTZ NOT NULL
);

5.2 Where Each Record Lives#

06Chapter 6: Channel Trade-Offs#

6.1 Cost, Latency, Reach and Reliability#

Each channel wins on something and loses on something else. Provider figures are as of October 2026.

The pattern behind the table:

• Push is free and fast, but no permission, no push. It's a doorbell, not a mailbox; the app reads the inbox when it opens.
• SMS reaches nearly everyone with no app, hence OTPs, and a template bug or retry loop costs real money.
• Email is cheap and rich but slow to be noticed and bound to sender reputation: receipts, statements, digests.
• In-app is fastest, but reaches only people looking at the app, and every connection costs us even when idle.

No channel is "best". The platform picks per class and per user the cheapest channel that will reach the person in time, and escalates only when it doesn't.

6.2 The Rules Belong to the Platform#

Compliance is a strong argument for one platform: each rule gets a single enforcement point.

• Consent per channel, with a record. Consent to marketing email isn't consent to marketing SMS; the consent log in 5.1 records when and how each was given.
• Unsubscribe that works at once. Gmail requires "one-click unsubscribe" for bulk senders' marketing (Google), and it must reach the router's cache in seconds.
• Registered SMS templates. In India a local-route SMS carries an Entity ID and a Template ID from DLT registration (AWS docs), so a new SMS template ships only once it's registered.
• An audit trail. "Every notification we sent this user in March, and what the provider said" must be a query, not an investigation.

07Chapter 7: Which Day Goes Deep on What#

Today drew every box. Each of the next four days takes some of them and makes them work under failure and at scale.

%% title: Week 6: which day builds which part of the platform
flowchart TD
  D1["Day 1 · The whole system<br/>requirements, estimates, architecture, data model"]:::hot
  D2["Day 2 · The delivery pipeline<br/>guarantees, priority lanes, preferences"]:::core
  D3["Day 3 · Real-time channels<br/>gateways, WebSockets and SSE, resume"]:::core
  D4["Day 4 · Presence and chat fan-out<br/>online dots, typing, groups, receipts"]:::core
  D5["Day 5 · Operations, scale, edge cases<br/>SLOs, campaigns, provider failover, cost"]:::core
  D1 --> D2
  D2 -->|"in-app tasks and the inbox"| D3
  D3 -->|"gateways and the registry"| D4
  D2 --> D5
  D3 --> D5
  D4 --> D5

The Preface maps the same way: the late OTP and Meera's ignored opt-out are Day 2, Priya's bell is Day 3, Kabir's green dot is Day 4, the SMS bill and the 20:00 burst are Day 5.

08Chapter 8: How Real Companies Do It#

8.1 LinkedIn: Air Traffic Controller#

LinkedIn built Air Traffic Controller (ATC) so teams stopped deciding notifications on their own. Its goal: "the right message to the right member through the right channel at the right time with the right frequency". ATC drops duplicates, rate-limits upstream applications, chooses the channel, aggregates related notifications and picks a good time to send. It runs as a stream processor on Apache Samza, with Kafka and local RocksDB state. It "currently processes over a billion requests per day", it let LinkedIn "cut member complaints in half", and parallelising it cut P90 latency for messaging push notifications "from about 12 seconds to about 1.5 seconds" (LinkedIn Engineering, March 2018).

What carries over: centralise the decision (whether, which channel, when), not only the sending. Complaints fell because of what ATC chose not to send.

8.2 Uber: RAMEN, a Real-Time Push Platform#

Uber's apps used to poll for state. "At some point, 80% of requests made to the backend API gateway were polling calls" (Uber Engineering, December 2020). Their replacement splits the problem in three: Fireball decides "when to push a message?", the API gateway decides what to push by calling domain services for the payload, and RAMEN servers hold the persistent connections and deliver.

RAMEN began on Server-Sent Events with sequence-number acknowledgements so clients could resume; a next-generation protocol on gRPC bidirectional streaming was "currently in beta release" when the post was written. Messages carry a priority (High, Medium, Low) and a time-to-live "ranging from a few seconds to up to 30 minutes"; servers "hold all the messages either in memory and backed in a database" and retry until the TTL expires. Uber reports "more than 1.5M concurrent connections" and "over 250,000 messages per second" (Uber Engineering, 2020).

What carries over: separate when, what and how; give each message a sequence number and a TTL; keep it durable until acknowledged. That's our router, templates, inbox and Day 3's gateways.

8.3 Slack: Writes In Over HTTP, Events Out Over Sockets#

"Every Slack client has a persistent websocket connection to Slack's servers to receive real-time events to maintain its state", but to send a message "the client hits our Webapp API", and the message is fanned out to subscribed clients from there. Slack reports "tens of millions of connected clients" and delivery "across the world in 500ms" (Slack Engineering, April 2023). What carries over: durable write through an ordinary API, delivery over the socket, so a dropped socket loses nothing.

09Chapter 9: Common Mistakes#

1. Designing only the send path. API to Twilio, and nothing for the user with the app open. Include the inbox and the real-time path; the inbox is what makes the real-time path safe.
2. One queue for every class. That's the Preface's 20:08 OTP. Separate lanes and workers from day one.
3. Treating a provider's 200 as delivery. FCM's "sent" means enqueued; an accepted email can bounce an hour later. Keep sent and delivered apart and measure the gap.
4. SMS as the safety net for everything. 5% of messages, ~90% of the bill. Use it where reaching the person is worth the price, after cheaper channels fail.
5. The socket as the record. Every crashed gateway, dropped Wi-Fi and deploy then loses messages. Inbox first, then the hint.

10Chapter 10: Interview Tips#

10.1 When to Bring It Up#

Either the prompt says "notification system", or it hides inside another one: "tell the user when the order ships", "riders get a trip offer", "show unread counts". Whenever a design sends anything to users, one sentence ("this goes through a notification platform with priority lanes and an inbox") shows you know it's a system of its own.

10.3 Questions to Ask the Interviewer#

• "Which notifications are critical, and what's their latency target?"
• "Do online users need to see things live, or is the next refresh fine?"
• "Is there an SMS budget, and which countries do we send to?"
• "How big are campaigns, and how often?"

10.4 Common Follow-Up Questions#

11Chapter 11: Practice Problems#

Summary#

Further Reading#

Engineering Posts#

• Blog

  LinkedIn — Air Traffic Controller: Member-First Notifications at LinkedIn (1 March 2018): https://www.linkedin.com/blog/engineering/messaging-notifications/air-traffic-controller-member-first-notifications-at-linkedin

• Blog

  Uber — Uber's Real-Time Push Platform (December 2020): https://www.uber.com/blog/real-time-push-platform/

• Blog

  Slack — Real-time Messaging (11 April 2023): https://slack.engineering/real-time-messaging/

Provider Documentation#

• Read

  Firebase — Pricing (FCM "No-cost"): https://firebase.google.com/pricing

• Docs

  Firebase — Throttling and quotas: https://firebase.google.com/docs/cloud-messaging/throttling-and-quotas

• Docs

  Firebase — Understanding message delivery: https://firebase.google.com/docs/cloud-messaging/understand-delivery

• Read

  Android — Notification runtime permission: https://developer.android.com/develop/ui/views/notifications/notification-permission

• Read

  Amazon SES — Pricing: https://aws.amazon.com/ses/pricing/

• Read

  Twilio — SMS pricing, United States and India: https://www.twilio.com/en-us/sms/pricing/us · https://www.twilio.com/en-us/sms/pricing/in

• Docs

  Twilio — SMS character limits and segments: https://www.twilio.com/docs/glossary/what-sms-character-limit

• Docs

  AWS End User Messaging — India sender ID registration and routes: https://docs.aws.amazon.com/sms-voice/latest/userguide/registrations-sms-senderid-india.html · https://docs.aws.amazon.com/sms-voice/latest/userguide/registrations-sms-senderid-india-routes.html

• Docs

  Google — Email sender guidelines: https://support.google.com/a/answer/81126