Push Notifications

The Problem

Push notifications are the primary re-engagement channel for mobile and web apps. When an event occurs (new message, order update, price alert), the system must determine who should be notified, respect user preferences, render the notification payload, and deliver it through platform-specific gateways (Apple Push Notification service, Firebase Cloud Messaging, Web Push). At scale, this involves millions of deliveries per minute with strict latency targets, complex preference filtering, and graceful handling of token invalidation and rate limits imposed by platform providers.

Architectural Approaches

Architecture

Loading diagram...

Key Components

Data Model

Loading diagram...

APNs vs FCM Protocol Differences

Apple Push Notification service (APNs):

• Uses HTTP/2 with JWT or certificate-based authentication
• Supports multiplexing hundreds of requests on a single connection
• Returns device token feedback (inactive tokens) in the response
• Payload limit: 4KB (increased from original 256 bytes)
• Supports critical alerts, time-sensitive notifications, and notification groups
• Token-based auth (JWT) is preferred — certificates expire annually

Firebase Cloud Messaging (FCM):

• HTTP v1 API with OAuth 2.0 authentication
• Supports topic-based and condition-based targeting
• Data messages (handled by app) vs notification messages (handled by OS)
• Payload limit: 4KB for notification, 4KB for data
• Batch send API for up to 500 messages per request
• Handles both Android and iOS (via APNs proxy)

Web Push:

• Uses the VAPID protocol with application server keys
• Payload encrypted with the push subscription’s public key
• Max payload: ~4KB (varies by browser)
• Requires a service worker to handle incoming messages

Deduplication and Suppression

Users hate duplicate or excessive notifications. Implement multiple layers of deduplication:

Event-level deduplication: Use idempotency keys (event ID + user ID) to prevent the same event from generating multiple notifications. Store processed keys in Redis with a 24-hour TTL.

Collapsing: Multiple events of the same type within a window should collapse into one notification. “You have 5 new messages from Alice” instead of 5 separate notifications. Use collapse keys (APNs apns-collapse-id, FCM collapse_key).

Frequency capping: Limit notifications per user per time window (e.g., max 10 push notifications per hour). Track counts in Redis with sliding window counters.

Quiet hours: Respect user-defined quiet hours. Queue notifications during quiet periods and deliver when the window opens — or discard if they’re time-sensitive and expired.

Channel suppression: If the user is actively viewing the conversation in the app (detected via WebSocket presence), suppress the push notification for that conversation.

Handling Token Lifecycle

Push tokens are ephemeral and must be managed carefully:

Token registration: Clients register their push token on every app launch (tokens can change). The backend upserts the token, deactivating any previous token for the same device.

Token invalidation: APNs and FCM return specific error codes when a token is invalid:

• APNs: 410 Gone (unregistered), 400 BadDeviceToken
• FCM: messaging/registration-token-not-registered

On these errors, mark the token as inactive immediately. Do NOT retry — it will never succeed.

Token rotation: iOS may rotate tokens during OS updates or app reinstalls. Always accept the latest token from the client and deactivate old ones.

Cleanup: Run a weekly job to remove tokens that haven’t been seen (re-registered) in 60+ days. These likely belong to uninstalled apps.

Multi-device: A user may have 2-5 active tokens (phone, tablet, watch, web). Send to ALL active tokens. The platform OS handles deduplication across devices in the same ecosystem.

Real-World Examples

Architectural Tradeoffs

# Learn the System Design of: Push Notifications

You are an expert software architect and teacher. I want to understand push notifications as a practical system design capability. (Fan-out delivery to APNs and FCM with guarantees, batching, and user preferences).

Use the following architectural guide as a learning reference. Avoid one-size-fits-all recommendations. Keep assumptions, costs, and tradeoffs explicit.

---

import { Mermaid, ComponentList, ComponentCard, ApproachList, Approach, Example, Tradeoff } from '@/components/mdx';

## The Problem

Push notifications are the primary re-engagement channel for mobile and web apps. When an event occurs (new message, order update, price alert), the system must determine who should be notified, respect user preferences, render the notification payload, and deliver it through platform-specific gateways (Apple Push Notification service, Firebase Cloud Messaging, Web Push). At scale, this involves millions of deliveries per minute with strict latency targets, complex preference filtering, and graceful handling of token invalidation and rate limits imposed by platform providers.

## Architectural Approaches

<ApproachList>
<Approach
  name="Direct Push via Platform SDKs"
  pros={[
    'Zero infrastructure overhead — no queues or workers',
    'Lowest latency for small volumes',
    'Easy to understand and debug',
  ]}
  cons={[
    'Tight coupling between business logic and notification delivery',
    'No retry, batching, or deduplication',
    'Each service must handle token management and preference checks',
    'Fails under load — APNs/FCM rate limits are easy to hit',
  ]}
>
Each backend service directly calls APNs/FCM APIs when an event occurs. The simplest approach — import the SDK, construct the payload, and send. Works for small-scale apps with few notification types.
</Approach>
<Approach
  name="Queue-Based Notification Pipeline"
  pros={[
    'Decoupled — any service can trigger notifications via events',
    ...

[Full prompt copied to clipboard]