Sistema de Notificações

"Projete um sistema de notificações que envia push, e-mails e SMS para muitos times de produto: confirmações de pedido, lembretes e campanhas de marketing. Os usuários precisam poder escolher o que recebem."

O sistema de notificações é o problema clássico de fan-out assíncrono para terceiros não confiáveis. Nada aqui é computacionalmente difícil; o que o torna interessante é que todas as partes interessantes ficam fora do seu controle: os gateways de push da Apple e do Google, provedores de e-mail e SMS com seus próprios rate limits, celulares que desinstalam o app, caixas de entrada que devolvem mensagens. A entrevista verifica se você consegue construir um pipeline que absorve rajadas, nunca envia a mesma mensagem duas vezes (ou explica quando pode enviar), mantém as mensagens urgentes rápidas enquanto um disparo de marketing está escoando, e respeita o que o usuário pediu.

O BoxOffice envia três tipos bem diferentes de notificação, e eles tornam os requisitos concretos:

• Transacional — "seus ingressos para sábado" segundos depois do webhook de pagamento (caso de ingressos). Pouco volume, precisa chegar rápido, não pode se perder.
• Agendada — "os portões abrem em 2 horas" para os 60 000 portadores de ingresso do show de hoje. Conhecida com antecedência, todas no mesmo momento.
• Campanha — "a pré-venda da turnê de estádios começa sexta às 10:00" para os 5 milhões de seguidores de um artista. Enorme, nada urgente e perigosa: se todo mundo tocar ao mesmo tempo, a notificação faz um DDoS no seu próprio app.

1. Esclarecer os requisitos

(roteiro de entrevista)

Requisitos funcionais

1. Serviços internos disparam notificações por uma única API (order, inventory, auth…), por usuário e tipo, com os dados para o template.
2. Canais: push (iOS via APNs, Android via FCM), e-mail e SMS.
3. Notificações agendadas (enviar num horário) e campanhas (enviar para um público, ex.: todos os seguidores de um artista).
4. Templates por tipo, canal e idioma.
5. Preferências do usuário: opt-out por categoria e canal, horário de silêncio, link de descadastro em todo e-mail de marketing.
6. Rastreamento: enviada, entregue, aberta, devolvida, por notificação e por campanha.

Requisitos não funcionais

Fora do escopo (diga explicitamente)

Construir nossa própria infraestrutura de push ou e-mail (usamos provedores), o editor de conteúdo do marketing, testes A/B de texto, a interface da caixa de entrada no app (citada como follow-up).

2. Estimativas de guardanapo (back-of-the-envelope)

# Notification system: assumptions (illustrative)
transactional_day = 2_000_000   # order confirmations, receipts, password resets
scheduled_day     = 3_000_000   # reminders ("doors open in 2 h")
campaign_users    = 5_000_000   # followers of one big artist: presale alert
channels_per_user = 1.5         # push for everyone, e-mail for half of them
email_share       = 0.5         # share of campaign users who also get an e-mail
window_min        = 30          # how long we spread the campaign over
tap_share         = 0.1         # users who open the app right after the notification
email_limit_s     = 1_000       # e-mail provider sending limit per second (illustrative)
record_b          = 500         # one notification log record
dedup_days        = 7           # how long we remember notification ids
dedup_b           = 60          # one dedup key in the cache

campaign_msgs   = campaign_users * channels_per_user
daily_msgs      = transactional_day + scheduled_day + campaign_msgs
avg_rate        = daily_msgs / 86_400
blast_rate_1m   = campaign_msgs / 60                        # if sent within one minute
spread_rate     = campaign_msgs / (window_min * 60)
taps_blast      = campaign_users * tap_share / 60           # app requests caused by the blast
taps_spread     = campaign_users * tap_share / (window_min * 60)
email_drain_min = campaign_users * email_share / email_limit_s / 60
log_gb_day      = daily_msgs * record_b / 1e9
dedup_gb        = daily_msgs * dedup_days * dedup_b / 1e9

rows = [
    ("campaign_msgs", campaign_msgs, "msgs"), ("daily_msgs", daily_msgs, "msgs/day"),
    ("avg_rate", avg_rate, "msgs/s"), ("blast_rate_1m", blast_rate_1m, "msgs/s"),
    ("spread_rate", spread_rate, "msgs/s"), ("taps_blast", taps_blast, "req/s"),
    ("taps_spread", taps_spread, "req/s"), ("email_drain_min", email_drain_min, "min"),
    ("log_gb_day", log_gb_day, "GB/day"), ("dedup_gb", dedup_gb, "GB"),
]
print("| quantity | value | unit |\n|---|---:|---|")
for name, value, unit in rows:
    v = f"{value:,.0f}" if abs(value) >= 100 else f"{value:,.2f}"
    print(f"| `{name}` | {v} | {unit} |")

O que os números dizem:

• A média é minúscula (~145 mensagens/s) e o pico é enorme: uma campanha de pré-venda são 7,5 M de mensagens, 125 mil/s se disparada em um minuto. ⇒ uma fila entre o disparo e os remetentes, e workers que escoam a uma taxa controlada. É um problema de absorver rajadas, não de vazão.
• Disparar em um minuto também gera ~8 mil requisições/s no app de fãs que tocam na notificação — no mesmo backend que está preparando a pré-venda. Espalhar por 30 minutos reduz isso a ~280 req/s. ⇒ espalhe as campanhas numa janela: o sistema de notificações precisa proteger o resto do BoxOffice, não só a si mesmo.
• Com um provedor de e-mail que aceita 1 000 mensagens/s, os 2,5 M de e-mails levam ~42 minutos, não importa quantos workers rodemos. ⇒ o limite do provedor decide a duração; precisamos de rate limit por provedor, e e-mails transacionais precisam de capacidade reservada (uma prioridade separada), senão esperam 40 minutos atrás da campanha.
• O log de notificações tem ~6 GB/dia e as chaves de deduplicação de uma semana ~5 GB — pouco. Armazenamento não é o problema; ordenar o trabalho é.

3. API

POST /v1/notifications                                   → 202 {notificationId, status: ACCEPTED}
     Idempotency-Key: order-81f3-confirmed
     {"userId": 42, "type": "order.confirmed", "priority": "transactional",
      "data": {"orderId": "81f3", "event": "Rock in Rio — Day 2", "seats": ["A-12-07", "A-12-08"]}}

POST /v1/campaigns                                       → 202 {campaignId, status: SCHEDULED}
     {"audience": {"followersOf": "artist:77"}, "type": "presale.alert",
      "sendAt": "2027-03-10T15:00:00Z", "spreadOver": "30m", "channels": ["push", "email"]}
POST /v1/campaigns/{campaignId}/cancel                   → 200 {sent, cancelled}

PUT  /v1/users/{userId}/preferences                      → 204
     {"marketing": {"push": true, "email": false}, "quietHours": {"from": "22:00", "to": "08:00"},
      "timezone": "America/Sao_Paulo", "locale": "pt-BR"}
POST   /v1/devices  {"userId": 42, "platform": "ios", "token": "…"}    → 201
DELETE /v1/devices/{token}                                              → 204

POST /v1/webhooks/{provider}                             ← delivered / bounced / complaint / opened (signed)
GET  /v1/notifications/{notificationId}                  → 200 {channel statuses, attempts}

• O disparo é assíncrono: 202 Accepted significa "enfileirada de forma durável", não "entregue". Os produtores nunca esperam pela Apple ou pelo provedor de e-mail.
• A Idempotency-Key vem do evento de negócio (order-81f3-confirmed), então um produtor que repete — ou um evento consumido duas vezes do Kafka — cria uma notificação.
• A priority é definida pelo tipo (configurada centralmente), e não escolhida livremente por cada time — senão tudo vira "transacional".

4. Modelo de dados

-- Preferences, templates, campaigns: small, relational, read-mostly (SQL)
CREATE TABLE preference (
    user_id     BIGINT, category TEXT, channel TEXT,       -- 'marketing' | 'reminders' | 'transactional'
    enabled     BOOLEAN NOT NULL,
    PRIMARY KEY (user_id, category, channel)
);
CREATE TABLE user_settings (
    user_id BIGINT PRIMARY KEY, timezone TEXT, locale TEXT,
    quiet_from TIME, quiet_to TIME, email TEXT, phone TEXT, email_suppressed BOOLEAN DEFAULT false
);
CREATE TABLE device (
    token TEXT PRIMARY KEY, user_id BIGINT NOT NULL, platform TEXT NOT NULL,   -- ios | android | web
    active BOOLEAN NOT NULL DEFAULT true, last_seen TIMESTAMPTZ
);
CREATE TABLE template (
    type TEXT, channel TEXT, locale TEXT, version INT,
    subject TEXT, body TEXT,                                -- e.g. Mustache/Handlebars source
    PRIMARY KEY (type, channel, locale, version)
);
CREATE TABLE campaign (
    campaign_id UUID PRIMARY KEY, audience JSONB, type TEXT, send_at TIMESTAMPTZ,
    spread_over INTERVAL, status TEXT, cursor TEXT          -- where the audience expansion stopped
);

# Notification log (NoSQL, partition = user_id, clustering = created_at DESC): write-heavy, append-only
notification {notification_id, user_id, type, channel, status: ACCEPTED|SENT|DELIVERED|FAILED|SKIPPED,
              provider, provider_msg_id, attempts, created_at, sent_at, reason}

# Dedup keys (cache) — one per notification and channel
SET notif:order-81f3-confirmed:push 1 NX EX 604800     → OK (first time) | nil (already sent)

# Per-user frequency cap (cache)
INCR cap:42:marketing:2027-03-10  → 2      EXPIRE … 86400

5. Design de alto nível

flowchart LR
    ord["serviços order / inventory /<br/>auth"] --> api["API de notificações<br/>valida, idempotência"]
    camp["Serviço de campanhas"] --> sch["Scheduler<br/>sendAt, espalhamento, silêncio"]
    sch --> api
    api --> route["Roteador<br/>preferências, templates,<br/>dispositivos, limites"]
    route --> qt[["Filas: transacional<br/>push · email · sms"]]
    route --> qm[["Filas: em massa<br/>push · email · sms"]]
    qt --> wp["Workers de push"]
    qm --> wp
    qt --> we["Workers de e-mail"]
    qm --> we
    qt --> ws["Workers de SMS"]
    wp --> apns[["APNs / FCM"]]
    we --> esp[["Provedor de e-mail A / B"]]
    ws --> sms[["Provedor de SMS"]]
    wp -. falhou após retentativas .-> dlq[["DLQ"]]
    esp -. webhooks .-> trk["Rastreamento"]
    trk --> an[("Analytics")]
    route --> log[("Log de notificações")]

Uma confirmação de pedido, de ponta a ponta:

sequenceDiagram
    autonumber
    participant O as order (consumidor Kafka)
    participant A as API de notificações
    participant R as Roteador
    participant Q as Fila (e-mail transacional)
    participant W as Worker de e-mail
    participant P as Provedor de e-mail
    participant T as Rastreamento
    O->>A: POST /notifications (Idempotency-Key order-81f3-confirmed)
    A->>A: primeira vez? grava ACCEPTED
    A-->>O: 202
    A->>R: route(usuário 42, order.confirmed)
    R->>R: preferências ok, renderiza o template pt-BR
    R->>Q: enfileira job de e-mail
    Q->>W: job (tentativa 1)
    W->>P: envia (timeout 3 s)
    P--xW: 503 Service Unavailable
    W->>Q: reenfileira com backoff 2 s ± jitter
    Q->>W: job (tentativa 2)
    W->>P: envia
    P-->>W: 202 aceito, id do provedor
    W->>W: status SENT
    P-->>T: webhook entregue

6. Aprofundamentos (deep dives)

6.1 Canais, filas e prioridades

Cada canal tem seu próprio provedor, modos de falha e limites, então cada um ganha sua própria fila e pool de workers — um provedor de SMS lento não pode parar as notificações push (um bulkhead). Cada canal também tem (pelo menos) duas prioridades: transacional e em massa.

Prioridades. Duas filas separadas por canal (ou um sistema de filas com prioridade estrita) e pools de workers separados ou capacidade reservada para o transacional. Uma campanha de 2,5 M de e-mails escoa então no limite do provedor menos a fatia reservada ao transacional, e a confirmação do pedido continua saindo em segundos.

6.2 Entregar uma vez: idempotência, retentativas, DLQ e failover

O pipeline é pelo menos uma vez de ponta a ponta — filas reentregam quando um worker cai, workers repetem quando um provedor dá timeout (semântica de entrega). Para o efeito ser "uma vez" para o usuário:

1. ID da notificação vindo do evento de negócio. A API guarda Idempotency-Key → notificationId; um segundo disparo para order-81f3-confirmed devolve a notificação existente.
2. Workers idempotentes. Antes de chamar o provedor, o worker reivindica notif:{id}:{channel} com SET NX; um job reentregue encontra a chave e só verifica o status.
3. Guardas do lado do provedor, quando existem. O apns-collapse-id do APNs faz o aparelho mostrar só a notificação mais recente com aquele ID; várias APIs de e-mail e SMS aceitam uma chave de idempotência ou uma referência do cliente.

def handle(job):
    key = f"notif:{job.notification_id}:{job.channel}"
    if not cache.set(key, "sending", nx=True, ex=7 * 86_400):
        return ack(job)                                   # already handled: duplicate delivery
    try:
        provider_id = provider.send(job.payload, timeout=3, idempotency_key=job.notification_id)
        log.update(job.notification_id, job.channel, status="SENT", provider_id=provider_id)
        return ack(job)
    except (Timeout, ProviderUnavailable, RateLimited) as err:
        cache.delete(key)                                 # allow the retry to claim it again
        if job.attempt >= MAX_ATTEMPTS:
            return dead_letter(job, reason=str(err))      # alert + manual or automatic replay
        delay = min(300, 2 ** job.attempt) * random.uniform(0.5, 1.5)   # backoff + jitter
        return retry_later(job, delay)
    except InvalidRecipient:
        devices.deactivate(job.token)                     # permanent: do not retry
        log.update(job.notification_id, job.channel, status="FAILED", reason="invalid recipient")
        return ack(job)

Falhas por tipo. Distinga erros transitórios (timeouts, 429, 5xx: repita com backoff exponencial e jitter), erros permanentes (token inválido, devolução permanente: não repita, corrija os dados) e mensagens venenosas (um template que falha ao renderizar: direto para a DLQ). A fila de mensagens mortas é monitorada; uma DLQ não vazia alerta alguém e tem uma ferramenta de reprocessamento.

Queda de provedor. Um circuit breaker por provedor abre quando os erros se acumulam (integrações). Para e-mail e SMS, mantenha um segundo provedor e faça failover do tráfego transacional para ele (o em massa pode simplesmente esperar). Para push não há alternativa ao APNs/FCM: enfileire e espere, e descarte pushes de marketing que ficaram velhos (um alerta de pré-venda depois que a pré-venda começou é ruído).

/** @return true if an e-mail was sent, false if the event was a duplicate */
@Transactional
public boolean handle(OrderEvent e) {
    if (props.idempotent()) {
        int fresh = jdbc.sql("INSERT INTO processed_events (event_id) VALUES (?) ON CONFLICT DO NOTHING")
                .param(e.eventId())
                .update();
        if (fresh == 0) {
            log.info("duplicate event {} for order {} ignored", e.eventId(), e.orderId());
            return false;
        }
    }
    email.orderReceived(e); // throws -> the whole transaction rolls back, the dedupe row too
    jdbc.sql("""
            INSERT INTO notifications (event_id, order_id, email, kind, occurred_at)
            VALUES (?, ?, ?, ?, ?)
            """)
            .params(e.eventId(), e.orderId(), e.customerEmail(), e.eventType(),
                    OffsetDateTime.ofInstant(e.occurredAt(), ZoneOffset.UTC))
            .update();
    return true;
}

DefaultErrorHandler errorHandler(KafkaTemplate<String, String> template) {
    // after the retries, publish to <topic>-dlt, same partition, with the exception in headers
    DeadLetterPublishingRecoverer recoverer = new DeadLetterPublishingRecoverer(template);

    ExponentialBackOffWithMaxRetries backOff = new ExponentialBackOffWithMaxRetries(3);
    backOff.setInitialInterval(500L);  // 0.5 s, 1 s, 2 s
    backOff.setMultiplier(2.0);
    backOff.setMaxInterval(5_000L);

    DefaultErrorHandler handler = new DefaultErrorHandler(recoverer, backOff);
    // permanent failures: retrying is pointless, go straight to the DLT
    handler.addNotRetryableExceptions(JacksonException.class, IllegalArgumentException.class);
    return handler;

6.3 Preferências, templates e limites

O roteador aplica uma sequência fixa de verificações antes de enfileirar qualquer coisa — filtros baratos primeiro:

flowchart LR
    t["Disparo<br/>usuário 42, presale.alert"] --> p{"Aceitou push<br/>de marketing?"}
    p -->|não| skip1["SKIPPED (log)"]
    p -->|sim| c{"Limite de frequência<br/>≤ 3 de marketing/dia?"}
    c -->|excedido| skip2["SKIPPED (log)"]
    c -->|ok| qh{"Horário de silêncio<br/>no fuso do usuário?"}
    qh -->|sim| def["Adia para o scheduler<br/>(08:00 local)"]
    qh -->|não| r["Renderiza o template<br/>(locale pt-BR)"]
    r --> d["Busca os dispositivos"]
    d --> q[["Fila push (em massa)"]]

• As preferências ficam em cache no roteador (são lidas a cada envio e mudam raramente); mesmo assim um opt-out precisa valer em segundos, então invalide na mudança.
• O transacional ignora limites de frequência e horário de silêncio (uma confirmação de ingresso às 23:00 é esperada); o marketing nunca ignora. A categoria é fixa por tipo, de forma central.
• Templates são versionados por tipo, canal e idioma; renderize no roteador (ou no worker) com os dados do disparo, e caia para um idioma padrão. Um erro de renderização é uma mensagem venenosa.
• Limites de frequência (INCR com TTL diário por usuário e categoria) protegem os usuários de cinco times enviando cada um "só um" push por dia.
• Rate limits dos provedores são aplicados pelos workers com um token bucket compartilhado por provedor e conta (caso do rate limiter), então desaceleramos antes de o provedor começar a responder 429.

6.4 Envios agendados e campanhas

Notificações agendadas ("os portões abrem em 2 h") são guardadas com um send_at; o scheduler consulta um índice por faixa de tempo (WHERE send_at <= now() AND status = 'PENDING', reivindicado com FOR UPDATE SKIP LOCKED para que várias instâncias do scheduler não enviem em dobro) ou usa uma fila com atraso. 60 000 lembretes exatamente às 18:00 já são uma mini-campanha: espalhe-os por alguns minutos.

Campanhas são expandidas em lotes, nunca como um único job gigante:

sequenceDiagram
    autonumber
    participant C as Serviço de campanhas
    participant G as Seguidores (grafo social)
    participant S as Scheduler
    participant R as Roteador
    C->>G: página de seguidores de artist:77 (cursor, 10 000)
    G-->>C: ids de usuários + próximo cursor
    C->>C: salva o cursor (retomável)
    C->>S: lote com horários de envio espalhados por 30 min (com jitter)
    S->>R: lotes vencidos, a uma taxa controlada
    R->>R: preferências, limites, silêncio, renderização
    Note over C,R: repete até o cursor acabar (ou a campanha ser cancelada)

• Retomável: o cursor é salvo depois de cada página; se o serviço de campanhas reiniciar, ele continua em vez de recomeçar (e as duplicatas são barradas pelas chaves de dedupe de qualquer forma).
• Espalhe com jitter: cada lote recebe horários de envio distribuídos pela janela, então os provedores veem uma taxa plana e o BoxOffice vê ~280 toques/s em vez de 8 000 (seção 2). O mesmo raciocínio da sala de espera: transformar um pico num fluxo.
• Botão de emergência: cancel para a expansão e faz os workers descartarem os jobs daquela campanha — essencial quando o texto tem uma data errada.
• Fusos horários: "às 10:00 no horário local" significa um agendamento de lotes por fuso horário.

Rastreamento. Os provedores informam delivered, bounced, complaint (e no e-mail, aberturas por um pixel de rastreamento e cliques por links redirecionados) por webhooks assinados. O serviço de rastreamento atualiza o log de notificações e envia os eventos para o armazenamento de analytics para os relatórios de campanha. Aberturas são aproximadas: alguns clientes de e-mail pré-carregam as imagens (o Apple Mail Privacy Protection, por exemplo), inflando as taxas de abertura.

7. Gargalos, modos de falha e trade-offs

Os trade-offs para dizer em voz alta: duplicatas vs. perdas (no transacional, repita e aceite duplicatas raras), velocidade vs. proteção (uma campanha espalhada por 30 minutos é mais lenta, mas segura para os provedores e para o BoxOffice), e isolamento vs. utilização (pools separados por canal e prioridade desperdiçam alguma capacidade, mas tornam as falhas locais).

8. Experimente no playground

O cenário notification-system tem um scheduler e produtores alimentando uma fila, workers por canal e provedores externos de e-mail/push.

Abrir o playground completo

9. Perguntas de follow-up que o entrevistador faz

10. Rubrica de autoavaliação

Relacionados: Filas e pub/sub, Semântica de entrega, Trabalho assíncrono e schedulers, Integrações externas, Hands-on 7 (consumidor notification idempotente e DLQ), Caso de ingressos.

Como se conecta

Quais aulas este caso testa? Cada ramo é uma aula cujas ideias o design usa (azul), com os componentes da paleta em que elas aparecem (verde):

flowchart LR
    CASE(["Notification system"]) --> EST["Estimation<br/>a provider limit sets campaign time"]:::tech
    CASE --> CMP["Compute<br/>scheduler, workers, provider adapters"]:::tech
    CASE --> MSG["Messaging<br/>queue per channel and priority, DLQ"]:::tech
    CASE --> DIS["Distributed<br/>dedup, at-most-once effect"]:::tech
    CASE --> REL["Reliability<br/>retries + jitter, bulkheads, failover"]:::tech
    CMP -.-> k1["scheduler · worker<br/>notifications"]:::comp
    MSG -.-> k2["queue"]:::comp
    REL -.-> k3["email · thirdparty"]:::comp
    DIS -.-> k4["nosql<br/>(notification log)"]:::comp
    classDef comp fill:#1e9e5a22,stroke:#1e9e5a
    classDef tech fill:#2f6fed22,stroke:#2f6fed

Aulas que ele testa: Compute — trabalho assíncrono · Compute — integrações · Mensageria — filas e pub/sub · Mensageria — semântica · Confiabilidade — padrões · Hands-on 7. Componentes da paleta: scheduler · queue · worker · notifications · email · thirdparty · nosql · analytics. Cenários: notification-system, async-queue.

Referências

• XU, A. System Design Interview — An Insider's Guide, vol. 1, cap. 10 "Design a Notification System"¹.
• Documentação do Apple Push Notification service (tokens, apns-collapse-id, respostas de erro)².
• Documentação do Firebase Cloud Messaging (tipos de mensagem, códigos de erro)³.
• KLEPPMANN, M.; RICCOMINI, C. Designing Data-Intensive Applications, 2ª ed., capítulos sobre processamento de streams e semântica de exatamente uma vez⁴.
• Descadastro em um clique para e-mails de marketing⁵.