Design: Notification System

#Introduction

Almost every product needs to notify users: order confirmations, OTPs, payment alerts, delivery updates, marketing campaigns. A notification system is a common interview question because it combines asynchronous processing, third-party integrations, reliability, rate limiting and user preferences.

#Step 1 — Requirements

Functional

• Send notifications over push (iOS APNs / Android FCM), SMS, email and in-app.
• Triggered by other services (events or API calls) — e.g. "order shipped".
• Templates with personalisation and multiple languages.
• Respect user preferences — opt-outs per channel and category, quiet hours.
• Scheduled notifications and bulk campaigns.
• Track delivery status (sent, delivered, opened, failed).

Non-Functional

• High throughput — millions of notifications per day, bursts during campaigns.
• Reliability — critical notifications (OTP, payment alerts) must not be lost.
• Low latency for critical types — an OTP within seconds; marketing can wait.
• No duplicates — users shouldn't receive the same message twice.
• Extensible — adding a channel (WhatsApp) shouldn't require a redesign.

#Step 2 — Estimates

The key insight: traffic is bursty, third-party providers have their own rate limits, and some types are urgent — so queues and priorities are essential.

#Step 3 — API

POST /api/v1/notifications
{
  "idempotencyKey": "order-1001-shipped",
  "userId": "U-42",
  "type": "ORDER_SHIPPED",              // maps to a template and a category
  "channels": ["PUSH", "EMAIL"],         // optional — otherwise from preferences
  "priority": "HIGH",                    // HIGH (OTP, alerts) | NORMAL | LOW (marketing)
  "data": { "orderId": "1001", "eta": "Oct 18" },
  "sendAt": null                         // or a future time
}
→ 202 Accepted { "notificationId": "N-9f1c" }

GET /api/v1/notifications/{id}           → status per channel
PUT /api/v1/users/{id}/preferences       → opt-outs, quiet hours, language

Services can also simply publish domain events (OrderShipped) to Kafka, which the notification system consumes.

#Step 4 — Data Model

templates(id, type, channel, language, subject, body, version)
user_preferences(user_id, channel, category, enabled, quiet_hours, language)
device_tokens(user_id, platform, token, last_seen)
notifications(id, user_id, type, priority, status, created_at)
delivery_log(notification_id, channel, provider, status, attempts, updated_at)   -- high volume, TTL

#Step 5 — High-Level Design

#Step 6 — Deep Dives

Priorities

Separate queues (or topics) per priority make sure a 10-million-user campaign never delays someone's OTP.

Reliability and Retries

• At-least-once processing from the queue — so sends must be idempotent: keep a record per (notificationId, channel) and skip if already sent.
• Provider failover — integrate two SMS or email providers; switch on errors or circuit-breaker trips.
• Channel fallback — if push fails because the token is invalid, fall back to SMS for critical messages.
• Remove invalid device tokens reported by FCM/APNs.

Deduplication

Duplicates arise from retried API calls, event redelivery and worker retries:

• Idempotency key on intake (order-1001-shipped), stored with a TTL — repeats return the original notification.
• Per-channel send record checked before calling the provider.
• Content-based dedupe windows for noisy event sources ("don't send the same type to the same user within 5 minutes").

Rate Limiting

User Preferences and Compliance

• Check preferences before enqueueing (and again before sending scheduled messages).
• Honour unsubscribe links in email and opt-out keywords (STOP) for SMS.
• Quiet hours in the user's time zone — delay non-urgent notifications.
• Follow regulations, such as India's TRAI rules for commercial SMS (registered templates and sender IDs, DND preferences), plus anti-spam and data-protection laws.

Templates and Localisation

template ORDER_SHIPPED / PUSH / en:
  title: "Your order is on its way!"
  body:  "Order #{{orderId}} will arrive by {{eta}}."

Templates are versioned, rendered with the user's language, and validated (length limits for SMS, payload size limits for push).

Scheduling and Campaigns

• Scheduled notifications are stored with sendAt; a scheduler polls due items (indexed by time, sharded) or uses delayed queues.
• Campaigns are broken into batches by a fan-out job that pages through the target audience and enqueues messages at a controlled rate.

Tracking and Analytics

• Providers report delivery via webhooks; opens and clicks come from tracking pixels / links or app events.
• Status updates flow through a queue into the delivery log (wide-column or time-series store with TTL) and an analytics pipeline.

#Step 7 — Bottlenecks and Trade-offs

#Key Takeaways

• Accept requests quickly (202) and process asynchronously through queues per channel and priority.
• Keep urgent and bulk traffic separate.
• Retries + idempotency + provider failover give reliability without duplicates.
• Rate-limit per provider, per user and per campaign.
• Respect preferences, quiet hours and regulations; track delivery status from provider callbacks.