Technical Design Document: [Unified Notification Service]
Author(s) | [Name, Senior Engineer; Name, Tech Lead] |
Team | [Customer Platform] |
Reviewers | [Principal Engineer; Security; Data Platform; Mobile lead] |
Status | [In review] |
Created / updated | [10 November 2026 / 24 November 2026] |
Related documents | [PRD: Order communications revamp; SRS section 3.4] |
1. Summary
[We propose a single Notification Service that receives events from other services and sends customer messages by email, SMS and push, applying templates, customer preferences and rate limits in one place. It replaces notification code currently duplicated across five services, and targets 99.95% successful delivery hand-off within 60 seconds of an event.]
2. Background
[Order, payment, delivery and marketing services each send messages directly to email and SMS providers with their own templates and logic. This causes inconsistent branding, duplicate messages (2.1% of orders receive two dispatch emails), no single view of what a customer was sent, and preferences that are honoured in some services and not others.]
3. Goals and non-goals
Goals
[One service and API for all transactional customer notifications (email, SMS, push).]
[Respect customer channel preferences and quiet hours consistently.]
[At-least-once processing with de-duplication so customers do not get duplicates.]
[Searchable history of every message sent per customer for 13 months.]
Non-goals
[Marketing campaign tools (audience building, A/B testing): remain in the marketing platform.]
[In-app message inbox: a later phase.]
[Replacing the email and SMS providers.]
4. Current architecture
[Each producer service calls provider APIs synchronously during request handling. Failures are retried inconsistently; two services drop messages on provider timeout. Templates live in each service’s repository.]
5. Proposed design
5.1 Architecture overview
Diagram: producers publish events to the message bus; the Notification Service consumes them, enriches with customer data, renders templates and sends through channel adapters; delivery status flows back from providers via webhooks.
Component | Responsibility | Technology |
|---|---|---|
[Event intake] | [Consume notification events from the message bus topic "notifications.v1"; validate schema] | [Consumer group, 6 partitions] |
[Orchestrator] | [Look up preferences, apply rules (quiet hours, de-duplication, rate limits), choose channels] | [Stateless service, autoscaled] |
[Template renderer] | [Render localised templates with event data] | [Template engine; templates versioned in repository] |
[Channel adapters] | [Send via email, SMS and push providers; handle provider-specific errors] | [One adapter per channel] |
[Status receiver] | [Receive provider delivery webhooks; update message status] | [HTTPS endpoint with signature verification] |
[Message store] | [Store message records and status history] | [Relational database] |
[Dead-letter queue] | [Hold events that fail after retries for inspection and replay] | [Message bus DLQ topic] |
5.2 Data flow
[Producer publishes an event, e.g. "order.dispatched", with an idempotency key, customer ID and payload.]
[Event intake validates the schema and writes a message record with status "received".]
[Orchestrator checks the idempotency key (de-duplicates within 24 hours), loads preferences and decides channels.]
[Template renderer produces the content for each channel in the customer’s language.]
[Channel adapters send to providers; status set to "sent" or "failed (retrying)".]
[Provider webhooks update status to "delivered", "bounced" or "failed".]
[After 5 failed attempts with exponential back-off over 30 minutes, the event moves to the dead-letter queue and an alert fires.]
5.3 Data model
Table | Key fields | Notes |
|---|---|---|
[message] | [id, idempotency_key (unique), customer_id, event_type, channel, template_version, status, created_at] | [Partitioned by month; 13-month retention] |
[message_status_event] | [message_id, status, provider_reference, detail, occurred_at] | [Append-only history] |
[preference] | [customer_id, channel, opted_in, quiet_hours_start, quiet_hours_end, updated_at] | [Source of truth moves here from the account service] |
5.4 Interfaces
Event contract: [Producers publish to "notifications.v1" with fields: event_type, idempotency_key, customer_id, locale (optional), payload. Schema registered in the schema registry with backward-compatible evolution.]
Query API: [GET /customers/{id}/messages returns message history for customer service tools (paginated, staff authentication only).]
Preferences API: [GET and PUT /customers/{id}/preferences for the account pages and mobile app.]
6. Alternatives considered
Option | Pros | Cons | Decision |
|---|---|---|---|
[A. Shared library used by each producer] | [Little new infrastructure] | [Still duplicated deployment; no central history or preferences; upgrades across 5 services] | [Rejected] |
[B. Buy a notification platform (SaaS)] | [Fast to start; built-in dashboards] | [$90k+ a year at our volume; customer data leaves our platform; limited custom rules] | [Rejected for now; revisit at 3× volume] |
[C. Central service consuming events (proposed)] | [Single place for rules, templates and history; decoupled from producers] | [New service to run; migration effort] | [Chosen] |
7. Capacity and performance
Measure | Estimate |
|---|---|
[Messages per day today] | [About 1.2 million (orders 450k, delivery updates 600k, account and payment 150k)] |
[Peak rate] | [Black Friday peak 4× average: about 55 messages per second, bursts to 150/s] |
[Design target] | [300 messages per second sustained (5× peak) with horizontal scaling] |
[Storage] | [About 1 KB per message plus status history: about 1.5 GB per month, 20 GB at 13 months] |
[Latency target] | [95% of messages handed to provider within 60 seconds of the event] |
8. Reliability and failure handling
[At-least-once consumption with idempotency keys gives effectively-once sending.]
[Provider outage: retries with back-off; SMS can fail over to the secondary provider by configuration.]
[Quiet hours: non-urgent messages are delayed, not dropped; urgent types (security, payment failure) bypass quiet hours.]
[Poison messages go to the dead-letter queue with a replay tool.]
9. Security and privacy
[Service-to-service authentication with mutual TLS; query API requires staff SSO and role "customer-service".]
[Message bodies containing personal data are encrypted at rest; only metadata is logged.]
[Data retention: message records deleted after 13 months; erasure requests delete records by customer ID.]
[Provider webhook signatures verified; replayed webhooks rejected after 5 minutes.]
[Security review booked: [date].]
10. Observability
Signal | Metric or log | Alert |
|---|---|---|
[Throughput] | [Events consumed and messages sent per channel per minute] | [Drop of 50% vs same time last week for 10 min] |
[Latency] | [Event-to-send time, p50/p95/p99] | [p95 above 60 s for 10 min] |
[Errors] | [Provider errors by code; DLQ depth] | [DLQ depth above 100 or error rate above 2%] |
[Delivery] | [Delivered, bounced and failed rates per channel] | [Bounce rate above 5% in an hour] |
11. Testing strategy
[Unit tests for rules, templates and adapters; contract tests for every producer event schema.]
[Integration tests against provider sandboxes.]
[Load test at 300 messages per second for 1 hour before launch.]
[Shadow mode: consume real events and render messages without sending, comparing with current output for 2 weeks.]
12. Rollout and migration
Phase | Scope | Exit criteria | Target |
|---|---|---|---|
[1. Shadow] | [Consume all events, send nothing] | [Rendered output matches for 99% of messages] | [Jan 2027] |
[2. Account emails] | [Password reset, email change] | [No incidents for 1 week; latency within target] | [Feb 2027] |
[3. Order and delivery] | [Behind a feature flag per event type, 10% then 100%] | [Duplicate rate below 0.1%] | [Mar 2027] |
[4. Decommission] | [Remove provider code from producers] | [All producers migrated] | [Apr 2027] |
Rollback: [Each event type can be switched back to the producer’s existing sending path by feature flag within 5 minutes until phase 4.]
13. Risks and open questions
# | Risk or question | Owner | Status |
|---|---|---|---|
[1] | [Do we move preference ownership from the account service in phase 1 or later?] | [Tech lead, Accounts team] | [Open] |
[2] | [Push notification tokens are stored in the mobile backend; agree an interface] | [Mobile lead] | [Open] |
[3] | [Risk: migration during peak season] | [Engineering manager] | [Mitigated: phases 3–4 after January] |
14. Milestones
Milestone | Date |
|---|---|
[Design approved] | [4 Dec 2026] |
[Service skeleton and event intake in production (shadow)] | [15 Jan 2027] |
[Account emails live] | [12 Feb 2027] |
[All transactional notifications live] | [31 Mar 2027] |
15. Approval
Reviewer | Role | Decision | Date |
|---|---|---|---|
[Name] | [Principal Engineer] | [Approved / Changes requested] | [Date] |
[Name] | [Security] | [Date] | |
[Name] | [Engineering Manager] | [Date] |