SYSTEM DESIGN:Lesson 17: When Your App Needs to Ping Users

You: "Example flow — order delivered event, user gets push notification?"
     -> Interviewer: "Yes, like Swiggy or Zomato."

You: "Which channels? Push, SMS, email — all three?"
     -> Interviewer: "Push primary, SMS fallback if push fails."

You: "Do users control preferences — marketing off, order updates on?"
     -> Interviewer: "Yes."

You: "What latency for transactional — seconds or minutes?"
     -> Interviewer: "Under 10 seconds."

You: "I will cover event queue, worker, template engine,
     idempotency keys, and provider integration. Scale fan-out next."

Swiggy backend -> FCM -> your phone (even if app is killed)

def pick_channels(user, event_type) -> list[str]:
    prefs = get_preferences(user.id)
    if event_type == "order_delivered":
        channels = []
        if prefs.push_enabled:
            channels.append("push")
        if prefs.sms_enabled and "push" not in channels:
            channels.append("sms")  # fallback
        return channels
    if event_type == "marketing_offer" and not prefs.marketing_opt_in:
        return []
    return ["email"]

Event source -> Notification API -> Queue -> Worker -> Provider (FCM/SES/SMS) -> User device
                  |                              |
                  +-> Idempotency check          +-> Delivery status DB
                  +-> Template render
                  +-> Preference filter

# In order service — do NOT block on FCM
def mark_delivered(order_id: str, user_id: str):
    db.update_order_status(order_id, "delivered")
    event_bus.publish("order.delivered", {
        "order_id": order_id,
        "user_id": user_id,
        "idempotency_key": f"order-delivered-{order_id}",
    })
    return {"status": "delivered"}

{
  "event_type": "order.delivered",
  "user_id": "usr_abc123",
  "payload": {
    "order_id": "ord_xyz789",
    "restaurant": "Meghana Biryani",
    "total": 450
  },
  "idempotency_key": "order-delivered-ord_xyz789",
  "created_at": "2026-08-28T20:14:00Z"
}

def process_notification_event(event: dict):
    if already_sent(event["idempotency_key"]):
        return  # duplicate event — skip

    user = get_user(event["user_id"])
    channels = pick_channels(user, event["event_type"])
    if not channels:
        log_skipped(event, reason="preferences")
        return

    body = render_template(event["event_type"], event["payload"])
    for channel in channels:
        provider = get_provider(channel)
        result = provider.send(user, body, metadata=event["payload"])
        record_delivery(event["idempotency_key"], channel, result)

{
  "event_type": "order.delivered",
  "push": {
    "title": "Order delivered!",
    "body": "Enjoy your meal from {{restaurant}}. Tap to rate."
  },
  "sms": {
    "body": "Swiggy: Your order from {{restaurant}} (Rs {{total}}) was delivered."
  },
  "email": {
    "subject": "Your Swiggy order is here",
    "body_html": "<p>Order {{order_id}} delivered...</p>"
  }
}

def render_template(event_type: str, payload: dict) -> dict:
    tmpl = template_store.get(event_type)
    return {
        channel: render_string(tmpl[channel], payload)
        for channel in tmpl
    }

CREATE TABLE notification_preferences (
    user_id          TEXT PRIMARY KEY,
    push_enabled     BOOLEAN DEFAULT true,
    sms_enabled      BOOLEAN DEFAULT true,
    email_enabled    BOOLEAN DEFAULT true,
    marketing_opt_in BOOLEAN DEFAULT false,
    quiet_hours_start TIME,   -- no push between 11 PM and 7 AM
    quiet_hours_end   TIME,
    updated_at       TIMESTAMPTZ
);

CREATE TABLE device_tokens (
    user_id     TEXT,
    device_token TEXT,
    platform    TEXT,  -- ios | android
    PRIMARY KEY (user_id, device_token)
);

order-delivered-{order_id}
payment-failed-{payment_id}
otp-{request_id}

CREATE TABLE sent_notifications (
    idempotency_key TEXT PRIMARY KEY,
    user_id         TEXT,
    event_type      TEXT,
    channels_sent   TEXT[],
    sent_at         TIMESTAMPTZ DEFAULT now()
);

def already_sent(key: str) -> bool:
    return db.exists("sent_notifications", idempotency_key=key)

def mark_sent(key: str, user_id: str, channels: list):
    db.insert("sent_notifications", ...)  # unique constraint catches races

def send_push(user_id: str, title: str, body: str, data: dict):
    tokens = get_device_tokens(user_id)
    for token in tokens:
        response = fcm.send(
            message={
                "token": token,
                "notification": {"title": title, "body": body},
                "data": data,
            }
        )
        if response.error == "NotRegistered":
            delete_device_token(user_id, token)

POST /api/v1/notifications
Authorization: Bearer <service_token>
Idempotency-Key: order-delivered-ord_xyz789

{
  "user_id": "usr_abc123",
  "event_type": "order.delivered",
  "payload": {
    "order_id": "ord_xyz789",
    "restaurant": "Meghana Biryani",
    "total": 450
  }
}

202 Accepted
{ "notification_id": "ntf_001", "status": "queued" }

GET /api/v1/notifications/ntf_001

200 OK
{
  "notification_id": "ntf_001",
  "status": "delivered",
  "channels": [
    { "channel": "push", "status": "delivered", "delivered_at": "..." }
  ]
}

PUT /api/v1/users/me/notification-preferences
{ "marketing_opt_in": false, "push_enabled": true }

POST /api/v1/users/me/device-tokens
{ "token": "fcm_token_...", "platform": "android" }

queued -> processing -> sent -> delivered
                      \-> failed -> retry (max 3) -> dead_letter

10,000 notifications/day
10,000 / 86,400 ~ 0.12/sec average
Peak dinner rush (10x): ~1.2/sec
One worker + one SQS queue handles this easily

10,000 SMS/day x Rs 0.20 = Rs 2,000/day if every notification is SMS
Push-first saves real money