System Design: [Notification service name]

Reference design for a multi-channel notification service that sends push, email, SMS and in-app messages on behalf of product teams. It covers templates and localisation, user preferences and opt-out, priority queues, per-user rate limits, provider failover, retries with backoff, deduplication and delivery tracking. It follows the structure of the System Design Document template and is pre-filled with a worked design to adapt. Values marked Example are assumptions. Consent and marketing rules vary by jurisdiction; this is an engineering format, not legal advice.

Document control

Approvals

Revision history

Contents

1. Overview
2. Requirements
3. Capacity estimation
4. API design
5. Data model
6. High-level design
7. Detailed design
8. Scalability and performance
9. Reliability, security and operations
10. Trade-offs and alternatives
11. Delivery plan and risks
12. Appendices

1. Overview

1.1 Problem statement

[Example: Nine product teams call email, SMS and push providers directly. Users get the same alert three times, unsubscribe links work for only some emails, a marketing campaign once delayed password-reset emails by 40 minutes, and nobody can answer "did this user receive the message?".]

1.2 Proposed solution

[Example: Product teams publish a notification request (recipient, template, data, category, priority) to one API. The service deduplicates the request, checks the user's preferences, quiet hours and frequency caps, renders the template per channel and locale, and places one job per channel on priority queues. Channel workers send through the primary provider with retries and fail over to a secondary provider. Provider callbacks and webhooks update a delivery log that support and product teams can query.]

1.3 Decisions requested from reviewers

2. Requirements

2.1 Functional requirements

2.2 Non-functional requirements

2.3 Out of scope

• [Example: campaign authoring UI and audience segmentation]
• [Example: two-way SMS conversations]
• [Example: voice calls]
• [Item deferred, with the release that will take it]

3. Capacity estimation

3.1 Assumptions

3.2 Throughput

Per channel at burst:

Bursts come from campaigns, which are low priority, so they can be smoothed over minutes without breaking any requirement.

3.3 Storage

3.4 SMS cost

This is the dominant cost and justifies push-first fallback ordering and strict SMS eligibility rules (7.2).

3.5 Summary

4. API design

4.1 Endpoints

4.2 Request and response examples

A product team asks for a transactional notification; the service decides channels from the category and user preferences:

POST /v1/notifications HTTP/1.1
Content-Type: application/json
Idempotency-Key: order-shipped:ord_88123

{"userId": "u_4410", "category": "order_updates", "priority": "transactional", "template": "order_shipped", "templateVersion": 3, "data": {"orderId": "ord_88123", "carrier": "DHL", "eta": "2026-03-16"}, "channels": ["push", "email"]}

HTTP/1.1 202 Accepted
Content-Type: application/json

{"id": "ntf_01JA9", "state": "accepted", "dedupOf": null}

4.3 Errors and limits

Suppression by preference is not an error: the request is accepted and its final state becomes suppressed with a reason.

5. Data model

5.1 Entities

A notification request produces one delivery per channel; each delivery records attempts and provider events.

5.2 Storage choices

6. High-level design

The accept path is short and synchronous; everything after the queue is asynchronous and retryable.

7. Detailed design

7.1 Templates

Templates are stored per channel and locale in a registry, written in a logic-less language (variables, conditionals, loops only), validated against a JSON Schema for their data, and require review before activation. Email templates are rendered to HTML and plain text; push templates are checked against platform payload limits; SMS templates are checked for segment count, since a message above 160 GSM-7 characters (70 in UCS-2) is billed as several segments.

7.2 Priorities and channel policy

Workers consume P0 first, then P1, then P2, with P2 limited to a configurable share of provider capacity so campaigns can never starve transactional mail.

7.3 Preferences, consent and opt-out

• Preferences are stored per category and channel, defaulting by category (marketing off unless consent is recorded where the market requires it).
• Every email carries a one-click unsubscribe (the List-Unsubscribe and List-Unsubscribe-Post headers per RFC 8058) and SMS honours STOP keywords through the provider's opt-out handling.
• Opt-out writes are synchronous to the preference store, and the orchestrator reads preferences at send time, not at request time, so a scheduled campaign respects an unsubscribe made after scheduling.
• Hard bounces and invalid push tokens mark the contact point invalid.

7.4 Send path with retries and failover (critical path)

The sequence below shows a transactional push with an email fallback.

Retry delay for attempt $n$ uses capped exponential backoff with full jitter:

With base 1 s and cap 5 min, attempt 6 waits up to 64 s and attempt 9 up to 5 minutes. P0 jobs use base 200 ms and give up after 30 s, because a late one-time code is useless; the user can request another.

Provider failover uses a circuit breaker per provider and region: when the error rate exceeds 20% over 1 minute, new sends route to the secondary until probes succeed. Only errors that are safe to retry (timeouts, 5xx, throttling) trigger a retry; permanent errors (invalid number, unsubscribed address) end the delivery as failed.

7.5 Deduplication

A residual duplicate is possible when a provider accepts a send but the response is lost and the provider offers no idempotency. This is accepted and measured (NFR-05).

7.6 Delivery tracking and consistency model

Each delivery moves through states driven by workers and provider callbacks; callbacks can arrive late or out of order, so transitions only move forward.

The delivery log is eventually consistent with providers: "delivered" may appear minutes after "sent", and some channels (SMS in some countries, push on some platforms) never report delivery. Preferences are strongly consistent (read from the primary on opt-out paths). Open tracking in email is approximate because many clients pre-fetch or block images.

8. Scalability and performance

Latency budget for a P0 one-time code (target 2 s to provider):

9. Reliability, security and operations

9.1 Failure modes

9.2 Security, privacy and abuse

9.3 Observability

9.4 Cost estimate

10. Trade-offs and alternatives

11. Delivery plan and risks

11.1 Milestones

11.2 Rollout and rollback

[Example: Migrate one category at a time behind a flag in the calling service. During migration, the old path stays available; rollback flips the flag. Provider credentials for direct use are revoked only after M4.]

11.3 Risks

12. Appendices

12.1 Open questions

12.2 Glossary

12.3 References

Standard and licence note

Based on common industry practice for notification platforms and on the specifications cited in 12.3. This is a reference design to adapt, with illustrative numbers and prices; it is a format, not legal advice on consent or marketing rules. Original text written for this collection. Template licence: MIT.