Design: a notification system

The prompt

Every product grows notifications team by team: one sends emails directly, another calls a push provider, a third has its own SMS account. Then users get the same alert three times, at 3 a.m., with no way to turn it off. "Design a notification system" asks for the shared platform that fixes that.

1. Requirements

Functional

• One API: send a notification of a given type to a user, a list of users or a segment, now or at a set time.
• Templates per type and channel, filled with data from the caller.
• Users control which types they get on which channels; quiet hours in their own time zone.
• Delivery status per notification and channel.

Non-functional

• Login codes and security alerts delivered within seconds, even during a campaign.
• No user gets the same notification twice on one channel.
• Bulk sends spread out within the providers' limits.

2. Estimates

• Rate: 50 million a day is about 600 a second on average; a campaign to 5 million users, spread over 10 minutes, is about 8,000 a second on top.
• Delivery log: 50 million rows a day at about 300 bytes is 15 GB a day; kept 90 days, about 1.4 TB.
• Device tokens: 40 million users × 1.5 devices = 60 million tokens: a table, not a big-data problem.

3. Entities and API

POST /notifications
  { idempotency_key, type: "link.trending", to: { user_id } | { segment },
    data: { code, clicks }, channels?: [...], send_at? }                  →  202 { notification_id }

Preferences { user_id, type, channel → on/off, quiet_hours: 22–07, time_zone }
Device      { user_id, platform, token, last_seen }
Delivery    { notification_id, channel, status, provider_id, sent_at }   primary key (notification_id, channel)

Callers say what happened and to whom; the platform decides whether, how and when to tell them.

4. High-level design

5. Deep dives

export async function deliverOnce(db: pg.Pool, notificationId: string, channel: string, send: () => Promise<void>) {
  const claimed = await db.query(
    `INSERT INTO deliveries (notification_id, channel, status) VALUES ($1, $2, 'sending')
     ON CONFLICT DO NOTHING RETURNING notification_id`,
    [notificationId, channel],
  );
  if (claimed.rowCount === 0) return "duplicate"; // a redelivered event: someone already has it
  await send();
  await db.query(`UPDATE deliveries SET status = 'sent', sent_at = now() WHERE notification_id = $1 AND channel = $2`, [
    notificationId,
    channel,
  ]);
  return "sent";
}

/** Quiet hours in the user's own time zone, which may wrap past midnight (22 → 7). */
export function inQuietHours(now: Date, timeZone: string, startHour: number, endHour: number) {
  const hour = Number(new Intl.DateTimeFormat("en-GB", { hour: "2-digit", hourCycle: "h23", timeZone }).format(now));
  return startHour <= endHour ? hour >= startHour && hour < endHour : hour >= startHour || hour < endHour;
}

Tested on Postgres 16: the same event delivered to five workers at once produced one send and four duplicates; the same notification on the email channel was sent separately, as it should be. At 17:30 UTC, quiet hours of 22:00 to 07:00 were in force for a user in Kolkata (23:00 there) and not for one in London; in Kolkata, 06:59 was still quiet and 07:00 wasn't.

Providers are best-effort. Apple's and Google's push services may reorder notifications, keep only a limited number for an offline device, and drop some; they report tokens that are no longer valid, and senders must delete those tokens or keep paying to send to dead devices. For SMS and email, a second provider behind a circuit breaker (08.09 Circuit breakers and bulkheads) keeps login codes working when one provider has an outage. Anything that must be seen, like a security alert, also goes to an in-app inbox stored by Snip itself.

6. Wrap-up

What breaks first: campaign spikes that hit provider limits, so bulk senders pace themselves with token buckets per provider (14.03 Rate limiting algorithms); then the delivery log, which grows fastest and is partitioned by day and expired after 90 days (14.11 Data retention, deletion and privacy).

Recap

Interview questions