Push Notification Platform at Scale

Push looks like one API call until you need priority, retries, per-user limits and delivery you can measure.

Part 1 of 5

Basics

The whole idea first, then the terms the rest of this page uses.

1.1Whole idea

Teams want to reach users without each building their own pipeline. A platform takes a request, applies preferences and limits, chooses devices, and hands messages to FCM and APNs through separate queues, so a marketing blast never delays a password reset.

Why it matters

Push looks like one API call until you need priority, retries, per-user limits and delivery you can measure.

1.2Key concepts

One idea per card, in plain words.

01FCM and APNs

Google's and Apple's delivery services. You hand over the message; they decide when the device gets it.

02Device token

Address of one app install. It changes, and it dies when the app is removed.

03Collapse key

Replaces older undelivered messages of the same kind, so an offline phone wakes to one update.

04Priority lanes

Separate queues per class, so bulk traffic cannot starve urgent traffic.

Part 2 of 5

Question

What exactly you must answer, and what to settle before you start.

2.1Question

Interviewer

Design a push platform for 50 million users, used by 30 product teams. One-time passcodes must arrive in seconds, even during a 20-million-user marketing send.

2.2Clarify first

Each answer removes a guess.

You askAnswer
Is push guaranteed?No. FCM and APNs are best effort, so critical flows need a fallback such as SMS.
Who stops over-sending?The platform: per-user limits and quiet hours apply to every team.
Part 3 of 5

Detailed answer

How it works, and how to build or explain it.

3.1Architecture

The components and how they connect.

Notify APIidempotency key · templatePolicypreferences · limits · quiethoursUrgent queuepasscodes, chatBulk queuecampaigns, throttledSendersper-provider workersFCM / APNsexternal deliveryToken storeuser → devicescheckurgentbulkpacedsendlookup
ServiceData storeQueue / streamExternal
Boxes are components; arrows show calls and data flow.

3.2Step by step

The mechanism, in the order you would explain it.

  1. Accept idempotently

    Callers send an idempotency key, so a retry never notifies twice. It is the same rule as the outbox and payments.

  2. Apply policy

    Check preferences, per-user limits and quiet hours before queueing.

  3. Split the lanes

    Urgent and bulk use separate queues and workers. Bulk runs at a paced rate.

  4. Fan out to devices

    Look up each user's tokens. Delete any token that a provider reports as dead.

  5. Handle provider limits

    Back off with jitter on 429 and 503. Retry only while the message still matters, then drop it.

  6. Measure delivery

    The app acknowledges receipt and opens. Provider acceptance alone does not prove delivery.

3.3Code

A working implementation, then what each part does and why.

One set of rules for every team

Thirty teams send through this. Urgent messages skip the limits, and bulk ones never delay them.

NotifyRouter.ktKotlinCopy
1enum class Lane { URGENT, BULK }2 3data class Notification(val key: String, val userId: String, val lane: Lane, val hourLocal: Int)4 5sealed interface Routed {6  data class Queue(val lane: Lane) : Routed7  data class Dropped(val why: String) : Routed8}9 10/** Every team's sends pass through one set of rules. */11class NotifyRouter(private val maxBulkPerDay: Int = 3, private val quiet: IntRange = 22..23) {12  private val seenKeys = HashSet<String>()13  private val bulkToday = HashMap<String, Int>()14 15  fun route(n: Notification): Routed {16    if (!seenKeys.add(n.key)) return Routed.Dropped("duplicate")     // the caller retried17    if (n.lane == Lane.URGENT) return Routed.Queue(Lane.URGENT)      // passcodes skip the limits18    if (n.hourLocal in quiet || n.hourLocal < 7) return Routed.Dropped("quiet hours")19    val sent = bulkToday.getOrDefault(n.userId, 0)20    if (sent >= maxBulkPerDay) return Routed.Dropped("daily limit")21    bulkToday[n.userId] = sent + 122    return Routed.Queue(Lane.BULK)23  }24}
24 linesUTF-8Kotlin
seenKeys.add(n.key)
A caller's retry sends nothing twice.
Lane.URGENT
Returns before any limit applies, because a passcode can't wait for quiet hours to end.
bulkToday
Per-user limits protect people from the sum of every team's campaigns.

Compiled and tested by npm run test:mobile.

Telling other devices to look

A push doesn't carry the change. It just says something changed, so Dev's tablet pulls by cursor like any other device.

SyncServer.ktKotlinCopy
1/** Push says "come and look". It carries no data, and one push covers many changes. */2class ChangeNotifier(private val sendPush: (device: String) -> Unit) {3  fun onCommitted(changes: List<Change>, devicesFor: (jobId: String) -> Set<String>, author: String) {4    changes.flatMap { devicesFor(it.jobId) }5      .toSet()6      .minus(author)7      .forEach(sendPush)8  }9}
9 linesUTF-8Kotlin
flatMap { devicesFor(it.jobId) }
Finds who cares about each change.
.toSet()
Five changes for one tablet still mean one push, which saves battery and provider quota.
.minus(author)
The phone that made the change doesn't need telling.

Compiled and tested by npm run test:mobile.

Part 4 of 5

Q&A

What interviewers ask next. Answer out loud, then open.

4.1Interview questions

How do you send silent pushes reliably?
You cannot. Silent push is throttled by the OS, so treat it as a hint, and let the app catch up by cursor on next open.
How do you avoid a stampede?
A send to 20 million users makes phones call your API at once. Pace the send and add client-side jitter before fetching.
How do you handle time zones?
Store each user's zone, and schedule bulk sends per zone.
Part 5 of 5

Extra depth

Edge cases, counterpoints and what to read next.

5.1Edge cases and counterpoints

Includes the strongest argument against this approach.

Show detailsHide details
Content privacy
Send a reference and fetch on the device when the content is sensitive. Providers and lock screens can see the payload.
Android channels
Users can mute a channel, so pick channels carefully. Mixing marketing into one channel mutes the important ones too.
Counterpoint
A small product can call FCM directly. Build a platform only once several teams need one set of rules.