Notification router - one event, the right channel, once

Why this design

Every product with users ends up with a notification system, usually by accident: each team calls the email provider directly, then the push provider, then somebody adds SMS for one feature. Within a year users are getting the same alert on three channels at 2am and support cannot say why. A notification router is the one place that decides channel, timing and deduplication for every notification in the company. Interviewers like it because it mixes product rules (preferences, quiet hours, digests) with a real distributed systems guarantee (once per channel over an at-least-once bus).

What you will learn

• Separating "what happened" (an event) from "who should hear about it, how, and when" (routing), and why producers must never pick channels.
• Preferences and consent as data: per notification type, per channel, with legal opt-in for SMS and marketing.
• Quiet hours in the user's timezone, deferral until morning, digests, and the morning thundering herd they create.
• Exactly once per channel via a unique claim, and the crash window that remains.
• Fallback across channels, and why it is a deliberate duplicate.

How to read this board

1. Press Play and follow the walkthrough: SOURCES on the left, then the ROUTE column hanging down from the router.
2. Then ONCE in the middle - the claim between deciding and sending.
3. Then CHANNELS and providers on the right, and the user.
4. 1 · Requirements to 6 · Deployment in the written band, then the DATA MODEL.
5. Then argue with the tension: once except for a crash window, a fallback that duplicates on purpose, and a timezone that travels.

Ask these before drawing anything

• Which notifications are transactional (password reset, payment failed, security alert) and which are engagement or marketing? The two have different legal rules, different quiet-hours rules, and must never share a send queue.
• Who decides the channel - the producing team or the user? The answer must be the user, through preferences, with the notification type providing defaults.
• What does "once" mean - once per event, or once per channel per event? A shipped order on push AND email is usually intended. The same push twice never is.
• Is SMS in scope, and who pays for it? At a cent or more per message, SMS is reserved for opt-in, critical notifications.
• How fresh must a preference change be? If a user turns off a type and gets one more five seconds later, is that a bug report?

Functional

• Consume domain events (order.shipped, comment.created, login.new_device) from the event bus.
• For each recipient, select channels from type defaults, user preferences and consent.
• Apply quiet hours in the user's timezone; defer non-urgent notifications to 08:00 local.
• Collapse bursts of low-priority notifications into a digest within a 15 minute window.
• Send each notification at most once per (event, user, channel), even when the event is delivered more than once.
• Fall back from push to email when a push is not opened within ten minutes, for types that opt in.
• Record delivery receipts, bounces, opens and unsubscribes.

Non-functional

• Transactional notifications: event to provider handoff in under 5 seconds at p99.
• Engagement notifications: under 15 minutes, or the next 08:00 local.
• Preference changes take effect within 30 seconds.
• Duplicates per channel below 1 in 100,000 sends.
• Unsubscribe honoured immediately and auditable for regulators (CAN-SPAM, GDPR, TCPA for SMS).