Functional
- Accept notification intents and templates.
- Apply user consent, locale, quiet hours, and channel preferences.
- Deliver email, SMS, push, and inbox with status history.
End-to-end walkthrough
Notification Platform
Deliver user notifications across channels with preferences, retries, and auditability.
Frame before solving
Requirements & boundaries
Quality attributes
- Transactional messages start within seconds.
- No intent is silently lost; duplicate external sends are minimized.
- Providers and tenants are isolated from one another.
Explicitly out of scope
- Campaign audience segmentation.
- Provider billing reconciliation.
Size the important constraints
Back-of-the-envelope estimates
Plan for campaign peaks far above average.
Queue references templates/data instead of copying large assets.
Cache versioned preference snapshots.
Separate operational and compliance stores.
These are reference assumptions, not universal facts. In an interview or architecture review, change them when the product context changes.
Define the contract
API & data model
Core operations
/v1/notificationsSubmit intent with recipient, template, data, priority, and idempotency key./v1/notifications/{id}Return per-channel delivery state./v1/preferences/{user}Update versioned consent and channel rules.Authoritative records
notification_id, tenant, recipient, template_version, priority, expires_atImmutable intent is the deduplication anchor.notification_id+channel+attempt, provider_id, status, error, occurred_atAppend attempts for diagnosis and audit.Trace the critical path
Architecture & request flow
- 1Accept intent→
- 2Resolve preferences→
- 3Render channel payload→
- 4Queue delivery→
- 5Record outcome
Notification API
Validate and deduplicate intents
Preference service
Apply consent and channel rules
Delivery queues
Buffer each channel independently
Providers
Send email, SMS, push, or inbox messages
Reason about the hard parts
Critical design deep dives
Orchestration
Persist the intent before publishing channel tasks. A transactional outbox or log-derived publisher closes the database/queue dual-write gap. Each channel evaluates expiry before sending.
Idempotency
Deduplicate client submissions by tenant and idempotency key. Consumers use notification/channel as their processing key. Where providers support idempotency, forward the same stable token.
Provider control
Track latency, error codes, and quotas by provider. Circuit-break failing routes, shift only eligible traffic, and prevent retries from consuming the entire provider recovery budget.
Make trade-offs explicit
Architecture decisions
ChoiceWhyCost
Per-channel queuesIsolates provider behaviorCross-channel orchestration is asynchronous
At-least-once deliveryAvoids silent lossConsumers and providers need idempotency
Failure-first review
What happens if…?
SMS provider is down
Open its circuit, retain bounded backlog, and apply channel-specific expiry.
Duplicate event arrives
Deduplicate on notification intent, recipient, and policy version.
Avoid premature complexity
How the design evolves
One channel
Intent table + worker + one provider
Move here when: Initial transactional notifications.
Multi-channel
Preference service and isolated channel queues
Move here when: Different consent and retry semantics emerge.
Global platform
Regional intake, provider routing, priority admission control
Move here when: Campaign peaks and regional provider failures.
Test the reasoning
Interview follow-ups
How do you avoid losing work between database and queue?
Strong answer signal: Transactional outbox, CDC, or log-first intent storage.
When should a notification expire?
Strong answer signal: Tie TTL to business meaning; do not deliver stale OTPs or alerts.
How do you prove consent was honored?
Strong answer signal: Versioned preference snapshot and immutable decision audit.
Build from primitives