Notification Service

Clarify Requirements

Imagine Sarah just placed an order on a food-delivery app. Within seconds, she expects a push notification on her phone, an email receipt in her inbox, and an SMS when her food is out for delivery. The Notification Service is the single backend system that fans every "something happened" event out to the right channel, in the right format, in the right language, while respecting Sarah's preferences and never spamming her if a downstream provider melts down. Let's pin down what it must do — and what we're explicitly leaving out.

Actors & Use Cases

Four kinds of clients touch this system. Upstream microservices (Order, Payment, Auth) are the ones generating events — they're 99% of the traffic. End users never call the service directly; they only see the notifications and update their preferences via a settings UI. Admins manage templates and watch dashboards. External providers (Twilio, SendGrid) call back into us with delivery receipts.

Architecture — From Naive to Production

Before any class diagram, let's build up the architecture in three passes: the simplest thing that could work, why it falls over, and the production shape that earns every box.

Pass 1 — The naive design (and why it breaks)

Your first instinct: a single REST endpoint POST /send. The Order Service calls it, you connect to SendGrid synchronously, return 200, done. Three lines of code.

Now fast-forward to Black Friday. Three concrete failures:

Pass 2 — The mental model: API plane vs Worker plane

The single most important split in this system is between accepting a notification request (must be fast, synchronous, returns an ID) and delivering it (slow, async, talks to flaky third parties). They have wildly different SLAs and scale independently. Once you internalize that split, every other component falls out naturally.

Pass 3 — The production shape

Now we draw the whole thing. Every box has a number — find its matching card below to see what it does, and crucially, what would break without it.

Component-by-component — what each numbered box does

Use the numbers in the diagram above to find the matching card below. Each one answers: what is this?, why is it here?, and what breaks without it?

Concrete walkthrough — Sarah's order confirmation

Sarah hits "Place Order" at 14:02:06. Here's exactly what happens, mapped to the numbered components above:

1. Order Service ① POSTs {user_id: 42, template: "ORDER_CONFIRMED_v3", channel: "EMAIL", vars: {...}, idempotency_key: "order-9876-confirm"} to the Load Balancer ②.
2. The LB routes it to one of three Notification API ③ pods. The API checks Redis ④ — the key doesn't exist, so it claims it.
3. API calls Preference Service ⑤ → "Sarah accepts transactional email" ✓. Calls Template Service ⑥ with vars → renders subject & body.
4. API writes a row to Postgres ⑦ with status PENDING, then publishes the message to the notifications.email topic in Kafka ⑧, partitioned by user_id=42. Returns 202 {notification_id: "n_abc123"} to the Order Service. Elapsed: 38ms.
5. An Email Worker ⑪ pulls the message. The Rate Limiter ⑨ checks: Sarah's email rate ✓, SendGrid's quota ✓.
6. The Channel Dispatcher ⑩ routes to the EmailSender strategy. EmailSender calls SendGrid ⑫. Returns 202 Accepted in 740ms.
7. Worker updates Postgres row to SENT, emits a notification.sent event to Audit ⑮.
8. Six seconds later, SendGrid POSTs to our Callback API ⑭ → delivered. We update the row to DELIVERED.
9. Two minutes later, Sarah clicks the tracking link in the email. SendGrid POSTs again → clicked. Row updates to CLICKED. Marketing now knows the email worked.

Core Entities & Enums

Now we map the architecture to objects. The trick is to find the nouns ("notification", "template", "channel", "user preference") and the things that vary ("which channel?", "which retry policy?"). Variations become enums or strategy classes; nouns become entities.

ER / Schema Diagram

Before classes, lock down the data model. Notice how delivery_attempt is a separate table — every retry gets a new row, so we have a complete forensic trail when things go wrong. The idempotency_key is unique per client, preventing duplicate sends.

Class Diagram

The NotificationService is the façade. It composes a Preference checker, a Template renderer, and a SenderFactory that resolves the right strategy per channel. ChannelSender is the strategy interface — each concrete sender is a swappable implementation.

Design Patterns Used

This problem is a pattern playground because the variation points are loud and clear. Each pattern below is paired with the exact question it answers.

Notification Lifecycle — State Machine

A notification's life is more nuanced than "sent / not sent". Modeling every state explicitly lets us answer support questions like "did Sarah open the email?" and lets the worker safely resume after a crash by inspecting the state.

Send Flow — Sequence Diagram

The happy-path send, end-to-end. Notice how the API returns to the caller before the provider is even called — that's the API/Worker split paying off.

Java Implementation

Pure Java 17, no frameworks. Order: enums → records → strategy interface → concrete senders → factory → service → worker → demo.

public enum Channel { EMAIL, SMS, PUSH, IN_APP, WHATSAPP, SLACK }

public enum Priority { CRITICAL, HIGH, NORMAL, LOW }

public enum Status {
    PENDING, SUPPRESSED, SENT, RETRY,
    DEAD, DELIVERED, BOUNCED, OPENED, CLICKED
}

import java.time.Instant;
import java.util.*;

public record NotificationRequest(
    long userId,
    String templateId,
    Channel channel,
    Map<String, Object> vars,
    String idempotencyKey,
    Priority priority,
    Instant scheduledAt
) {
    public static Builder builder() { return new Builder(); }

    public static class Builder {
        private long userId;
        private String templateId;
        private Channel channel;
        private Map<String, Object> vars = new HashMap<>();
        private String idempotencyKey = UUID.randomUUID().toString();
        private Priority priority = Priority.NORMAL;
        private Instant scheduledAt = Instant.now();

        public Builder to(long u)            { this.userId = u;        return this; }
        public Builder template(String t)     { this.templateId = t;    return this; }
        public Builder channel(Channel c)     { this.channel = c;       return this; }
        public Builder var(String k, Object v) { vars.put(k, v);          return this; }
        public Builder priority(Priority p)   { this.priority = p;      return this; }
        public Builder idempotencyKey(String k){ this.idempotencyKey = k; return this; }
        public Builder scheduleAt(Instant at){ this.scheduledAt = at;   return this; }

        public NotificationRequest build() {
            if (templateId == null || channel == null)
                throw new IllegalStateException("template & channel required");
            return new NotificationRequest(userId, templateId, channel,
                    Map.copyOf(vars), idempotencyKey, priority, scheduledAt);
        }
    }
}

public class Notification {
    private final String id;
    private final long userId;
    private final Channel channel;
    private final Priority priority;
    private final String renderedPayload;
    private volatile Status status;
    private final AtomicInteger attempts = new AtomicInteger(0);

    public Notification(String id, long u, Channel c, Priority p, String body) {
        this.id = id; this.userId = u; this.channel = c;
        this.priority = p; this.renderedPayload = body;
        this.status = Status.PENDING;
    }
    public int    incrementAttempts() { return attempts.incrementAndGet(); }
    public void   markSent()      { this.status = Status.SENT; }
    public void   markRetry()     { this.status = Status.RETRY; }
    public void   markDead()      { this.status = Status.DEAD; }
    public void   markSuppressed(){ this.status = Status.SUPPRESSED; }
    // getters omitted for brevity
    public String  getId()       { return id; }
    public long    getUserId()   { return userId; }
    public Channel getChannel()  { return channel; }
    public Priority getPriority(){ return priority; }
    public String  getPayload()  { return renderedPayload; }
    public Status  getStatus()   { return status; }
    public int     getAttempts() { return attempts.get(); }
}

public interface ChannelSender {
    DeliveryResult send(Notification n) throws SendException;
    Channel getChannel();
}

public record DeliveryResult(boolean success, String providerMsgId, long latencyMs) {}

public class SendException extends Exception {
    private final boolean retryable;
    public SendException(String msg, boolean retryable) {
        super(msg); this.retryable = retryable;
    }
    public boolean isRetryable() { return retryable; }
}

public class EmailSender implements ChannelSender {
    private final SendGridClient client;
    public EmailSender(SendGridClient c) { this.client = c; }

    @Override
    public DeliveryResult send(Notification n) throws SendException {
        long t0 = System.currentTimeMillis();
        try {
            String msgId = client.sendEmail(n.getUserId(), n.getPayload());
            return new DeliveryResult(true, msgId, System.currentTimeMillis() - t0);
        } catch (RateLimitedException | TimeoutException e) {
            throw new SendException(e.getMessage(), true);   // retryable
        } catch (InvalidAddressException e) {
            throw new SendException(e.getMessage(), false);  // permanent
        }
    }
    @Override public Channel getChannel() { return Channel.EMAIL; }
}

public class SenderFactory {
    private final Map<Channel, ChannelSender> registry = new EnumMap<>(Channel.class);

    public void register(ChannelSender s) { registry.put(s.getChannel(), s); }

    public ChannelSender get(Channel c) {
        ChannelSender s = registry.get(c);
        if (s == null) throw new IllegalArgumentException("No sender for " + c);
        return s;
    }
}

public interface RetryPolicy {
    boolean shouldRetry(int attemptNo, Throwable cause);
    Duration nextDelay(int attemptNo);
}

public class ExponentialBackoffPolicy implements RetryPolicy {
    private final int maxAttempts;
    private final Duration baseDelay;

    public ExponentialBackoffPolicy(int max, Duration base) {
        this.maxAttempts = max; this.baseDelay = base;
    }

    @Override
    public boolean shouldRetry(int attemptNo, Throwable cause) {
        if (attemptNo >= maxAttempts) return false;
        if (cause instanceof SendException se) return se.isRetryable();
        return true;
    }

    @Override
    public Duration nextDelay(int attemptNo) {
        long ms = baseDelay.toMillis() * (1L << attemptNo);          // 1s, 2s, 4s, 8s...
        long jitter = ThreadLocalRandom.current().nextLong(ms / 4);   // avoid thundering herd
        return Duration.ofMillis(ms + jitter);
    }
}

public class TokenBucketLimiter implements RateLimiter {
    private final Map<String, Bucket> buckets = new ConcurrentHashMap<>();
    private final long capacity;
    private final long refillPerSec;

    public TokenBucketLimiter(long capacity, long refillPerSec) {
        this.capacity = capacity; this.refillPerSec = refillPerSec;
    }

    @Override
    public boolean tryAcquire(String key) {
        return buckets
            .computeIfAbsent(key, k -> new Bucket(capacity, refillPerSec))
            .tryConsume();
    }

    private static class Bucket {
        private final long capacity, refillPerSec;
        private double tokens;
        private long lastRefillNs;

        Bucket(long cap, long rps) {
            this.capacity = cap; this.refillPerSec = rps;
            this.tokens = cap; this.lastRefillNs = System.nanoTime();
        }

        synchronized boolean tryConsume() {
            long now = System.nanoTime();
            double elapsedSec = (now - lastRefillNs) / 1_000_000_000.0;
            tokens = Math.min(capacity, tokens + elapsedSec * refillPerSec);
            lastRefillNs = now;
            if (tokens >= 1) { tokens -= 1; return true; }
            return false;
        }
    }
}

public class NotificationService {
    private final PreferenceService prefs;
    private final TemplateService   templates;
    private final NotificationRepository repo;
    private final QueuePublisher    publisher;
    private final IdempotencyStore  idempotency;

    public NotificationService(PreferenceService p, TemplateService t,
                               NotificationRepository r, QueuePublisher q,
                               IdempotencyStore i) {
        this.prefs = p; this.templates = t; this.repo = r;
        this.publisher = q; this.idempotency = i;
    }

    public String send(NotificationRequest req) {
        // 1. Idempotency — return existing if duplicate
        Optional<String> existing = idempotency.claim(req.idempotencyKey());
        if (existing.isPresent()) return existing.get();

        // 2. Preference + quiet-hours check (CRITICAL bypasses)
        Decision d = prefs.isAllowed(req.userId(), req.channel(), req.priority());
        if (d == Decision.SUPPRESS) {
            String id = repo.save(Notification.suppressed(req));
            return id;
        }

        // 3. Render template
        RenderedMessage body = templates.render(req.templateId(),
                                                  req.vars(),
                                                  prefs.getLocale(req.userId()));

        // 4. Persist + enqueue (in same transaction would be ideal — outbox pattern)
        Notification n = new Notification(UUID.randomUUID().toString(),
                                              req.userId(), req.channel(),
                                              req.priority(), body.payload());
        repo.save(n);
        publisher.publish(n);
        return n.getId();
    }
}

public class NotificationWorker {
    private final SenderFactory factory;
    private final RetryPolicy   retry;
    private final RateLimiter   limiter;
    private final NotificationRepository repo;
    private final QueuePublisher  publisher;
    private final DeadLetterQueue dlq;
    private final EventBus        events;

    public void consume(Notification n) {
        String userKey     = "user:" + n.getUserId();
        String providerKey = "provider:" + n.getChannel();

        if (!limiter.tryAcquire(userKey) || !limiter.tryAcquire(providerKey)) {
            publisher.publishDelayed(n, Duration.ofSeconds(1));   // shed back to queue
            return;
        }

        int attemptNo = n.incrementAttempts();
        try {
            DeliveryResult r = factory.get(n.getChannel()).send(n);
            n.markSent();
            repo.update(n);
            events.publish(new SentEvent(n.getId(), r.latencyMs()));
        } catch (SendException e) {
            if (retry.shouldRetry(attemptNo, e)) {
                n.markRetry();
                repo.update(n);
                publisher.publishDelayed(n, retry.nextDelay(attemptNo));
            } else {
                n.markDead();
                repo.update(n);
                dlq.add(n, e);
                events.publish(new DeadEvent(n.getId(), e.getMessage()));
            }
        }
    }
}

public class Demo {
    public static void main(String[] args) {
        // Wire dependencies
        SenderFactory factory = new SenderFactory();
        factory.register(new EmailSender(new SendGridClient()));
        factory.register(new SMSSender(new TwilioClient()));
        factory.register(new PushSender(new FCMClient()));

        NotificationService svc = new NotificationService(
            new PreferenceService(),
            new TemplateService(),
            new NotificationRepository(),
            new QueuePublisher(),
            new IdempotencyStore()
        );

        // Order Service sends a confirmation
        String notifId = svc.send(
            NotificationRequest.builder()
                .to(42L)
                .template("ORDER_CONFIRMED_v3")
                .channel(Channel.EMAIL)
                .var("name", "Sarah")
                .var("orderId", "9876")
                .priority(Priority.HIGH)
                .idempotencyKey("order-9876-confirm")
                .build()
        );

        System.out.println("Tracking ID: " + notifId);

        // Duplicate request — returns same ID, no second send
        String dupe = svc.send(
            NotificationRequest.builder()
                .to(42L).template("ORDER_CONFIRMED_v3").channel(Channel.EMAIL)
                .idempotencyKey("order-9876-confirm")
                .build()
        );
        assert notifId.equals(dupe);   // idempotent ✓
    }
}

Concurrency & Reliability

Three things will bite you in production. Address them in the design conversation, not after the interview ends.

Extension Points (Open/Closed)

The shape of the design is justified by how easily it absorbs new requirements without editing existing code.

Interview Q&A & Trade-offs

Real follow-ups you'll get after presenting this design. Each answer states the trade-off, not just the solution.