Architecture Blueprint

Design Push Notification Service (APNs, FCM, SMS, Email)

High-volume multi-channel notification platform delivering billions of critical push alerts, transactional emails, and SMS with user preference filtering, rate limiting, and dead-letter retries.

1. System Requirements

Functional

Dispatch notifications across multiple delivery channels (Apple APNs, Google FCM, Twilio SMS, Resend/SES Email).
Enforce user opt-out preferences, channel preferences, and localized quiet hours (no marketing alerts at 3 AM).
Support high-priority real-time alerts (2FA codes, fraud alerts) and scheduled marketing broadcasts.

Non-Functional / SLA

Sub-2 second delivery latency for critical security alerts.
High reliability (at-least-once delivery) with deduplication to prevent spamming users.
Scalable fan-out capable of broadcasting breaking news alerts to 50M+ users in under 3 minutes.

2. Scale & Resource Estimates

Throughput: 100 Million daily active users. 1 Billion notifications/day = ~11,500/sec average, 100,000/sec peak during breaking events.

Storage & RAM: Audit logs: 1B notifications * 500 bytes = 500 GB/day. Retained for 30 days = 15 Terabytes in cold storage.

3. System API Endpoints

POST /api/v1/notifications/dispatch
Request:
{
  "user_id": "usr-8812",
  "priority": "HIGH", // HIGH (2FA, Order) or BULK (Marketing)
  "channels": ["PUSH", "EMAIL"],
  "template_id": "tpl-login-alert",
  "template_data": { "device": "MacBook Pro", "location": "New York, USA" },
  "idempotency_key": "notif-idem-9921"
}
Response (202 Accepted):
{
  "notification_id": "ntf-991204",
  "status": "QUEUED"
}

4. Database Schema Design

Table: user_notification_preferences (PostgreSQL)
- user_id (UUID - Primary Key)
- push_enabled (BOOLEAN)
- email_enabled (BOOLEAN)
- sms_enabled (BOOLEAN)
- quiet_hours_start (TIME)
- quiet_hours_end (TIME)
- timezone (VARCHAR(64))

Table: user_device_tokens (PostgreSQL)
- token_id (UUID - Primary Key)
- user_id (UUID - Foreign Key)
- platform (ENUM: IOS, ANDROID, WEB)
- device_token (TEXT)
- is_active (BOOLEAN)
- updated_at (TIMESTAMP)

Table: notification_audit_log (Cassandra / ClickHouse)
- notification_id (UUID)
- user_id (UUID)
- channel (VARCHAR)
- status (ENUM: DELIVERED, FAILED, THROTTLED)
- sent_at (TIMESTAMP)

5. Interactive High-Level Architecture

graph TD AppService["Business Microservices: Orders, Auth, Social"] --> Gateway["Notification API Gateway"] Gateway --> DedupRate[("Redis Deduplication & Rate Limiter")] DedupRate --> PriorityRouter{"Priority Classifier"} PriorityRouter -->|Critical: 2FA & Security| HighQueue[("Kafka High Priority Topic")] PriorityRouter -->|Bulk: Marketing & Digest| LowQueue[("Kafka Bulk Topic")] HighQueue --> DispatcherHigh["High Priority Dispatch Workers"] LowQueue --> DispatcherLow["Bulk Dispatch Workers"] DispatcherHigh --> UserPref[("User Preference & Channel Store")] DispatcherHigh --> APNs["Apple Push Notification Service (APNs)"] DispatcherHigh --> FCM["Firebase Cloud Messaging (FCM)"] DispatcherHigh --> SMS["Twilio SMS Gateway"] DispatcherHigh --> Email["Resend / SES Email Gateway"] DispatcherHigh -.->|Retry Exhausted| DLQ[("Dead Letter Queue (DLQ)")]

6. Scalability Deep Dive & Bottlenecks

A unified notification pipeline must avoid the head-of-line blocking problem. If a marketing campaign sends 10 Million promotional push notifications, critical 2FA authentication codes must not be stuck behind millions of marketing messages. The architecture strictly divides ingestion into separate Kafka topics: `priority.notifications` and `bulk.notifications`. High-priority workers maintain dedicated connection pools to APNs/FCM HTTP/2 endpoints, guaranteeing sub-second delivery even during massive marketing bursts.

7. Production Scaling Strategies

Multi-Tiered Queue Separation: Isolate topics by SLA. High-priority traffic (login alerts, payments) receives dedicated compute clusters, while bulk traffic is throttled to respect provider quotas.

HTTP/2 Persistent Multiplexing: Maintain persistent HTTP/2 connection pools to Apple (APNs) and Google (FCM). Reusing TLS sessions avoids SSL handshake latency and handles thousands of concurrent pushes per connection.

Distributed Deduplication: When multiple microservices trigger events for the same activity, Redis checks a short-lived `dedup:{user_id}:{event_type}` key with a 5-minute sliding window to suppress duplicate notifications.

User Quiet Hours Engine: Convert the user's local timezone into UTC. Non-urgent marketing notifications scheduled during quiet hours (e.g., 10 PM - 8 AM) are re-queued into a delayed delivery wheel for morning dispatch.

Rate Limiting & Anti-Spam: Enforce strict per-user limits (e.g., maximum 3 push notifications per hour) to prevent runaway notification loops caused by software bugs from harassing users.

Dead-Letter Queue (DLQ) & Retry Policy: Transient delivery failures (HTTP 500/503 from third-party APIs) retry with exponential jittered backoff. If 5 retries fail, payloads route to a DLQ for manual inspection and alerting.

8. Runnable Production Starter Code

Scaffold

System Design Architectures