Skip to content
GraviPointThe Centre of Productivity
  • AI AgentNew
  • Pricing
  • Community
Log inGet started free
TemplatesProject & Task ManagementAgile & ScrumTechnical Design Document

DocumentAgile & ScrumFree

Technical Design Document

Explain how a system will be built: architecture, data model, interfaces, alternatives, scaling, security and rollout.

Shown with sample data

Colour

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

  1. [One service and API for all transactional customer notifications (email, SMS, push).]

  2. [Respect customer channel preferences and quiet hours consistently.]

  3. [At-least-once processing with de-duplication so customers do not get duplicates.]

  4. [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

  1. [Producer publishes an event, e.g. "order.dispatched", with an idempotency key, customer ID and payload.]

  2. [Event intake validates the schema and writes a message record with status "received".]

  3. [Orchestrator checks the idempotency key (de-duplicates within 24 hours), loads preferences and decides channels.]

  4. [Template renderer produces the content for each channel in the customer’s language.]

  5. [Channel adapters send to providers; status set to "sent" or "failed (retrying)".]

  6. [Provider webhooks update status to "delivered", "bounced" or "failed".]

  7. [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]

Text in [brackets] is yours to replace.

  • About
  • What’s included
  • How to use
  • Questions
  • Related resources

About this template

A technical design document (design doc) lets engineers agree how something will be built before writing the code, when changing direction is cheap. This template covers context and goals, explicit non-goals, the proposed architecture and data flow, data model, APIs, alternatives considered with trade-offs, capacity estimates, reliability, security and privacy, observability, testing, rollout and open questions, worked through for a fictional e-commerce notification service.

Who it’s for

  • New services, major features and architectural changes
  • Design reviews with senior engineers and other teams
  • Recording why decisions were made for future maintainers
  • Onboarding engineers to an existing system

What’s included

  • 1. Summary
  • 2. Background
  • 3. Goals and non-goals
  • 4. Current architecture
  • 5. Proposed design
  • 6. Alternatives considered
  • 7. Capacity and performance
  • 8. Reliability and failure handling
  • 9. Security and privacy
  • 10. Observability

How to use it

  1. 1Start with the problem, goals and non-goals; reviewers should agree on these before the solution.
  2. 2Describe the proposed design at the level a peer engineer needs to critique it: components, data flow, data model and interfaces.
  3. 3Always include alternatives you considered and why you rejected them.
  4. 4Cover the cross-cutting concerns: scale, failure modes, security, privacy, observability and migration.
  5. 5Circulate for review, record decisions and open questions, and update the document if the design changes during build.

Tips

  • Write for reviewers who have 20 minutes. Put a summary and a diagram description at the top.
  • Non-goals prevent scope creep and endless review debates. Be explicit about what this design does not solve.
  • Estimate load with real numbers (requests per second, data volume, growth) and show the arithmetic; it is where design flaws usually show up.

Questions

What is the difference between an SRS and a technical design document?

The SRS defines what the system must do and how well. The technical design document explains how it will be built to meet those requirements: architecture, components, data and technology choices.

How long should a design doc be?

Usually 5 to 15 pages. Small changes may need only a one-page design; large platform changes may need more, with detail in appendices.

Who should review a technical design?

The engineers who will build and run it, a senior or principal engineer, and representatives of teams it depends on or affects, such as security, data and platform teams.

Related searchestechnical design document templatesoftware design documentdesign doc templatesystem design documentengineering design docarchitecture design document

Details

Format
Document
Category
Agile & Scrum
Setup
150 min
Level
Advanced
Price
Free

Download a copy

Downloads need a free account.

DocumentAgile & ScrumFree

Technical Design Document

Explain how a system will be built: architecture, data model, interfaces, alternatives, scaling, security and rollout.

A free account keeps your copy safe so you can come back to it. Have one? Log in

Download a copy

Downloads need a free account.

Details

Format
Document
Category
Agile & Scrum
Setup
150 min
Level
Advanced
Price
Free

Your copy is private to you.

More agile & scrum templates

View all
Sprint Backlog4 sheets

Committed

44

Done

15

Sprint progress

34%

ABCD
1StoryTypeEpicAssignee
2As a user I can reset my password by emailStoryAccountsAna
3Show order history with filtersStoryOrdersBen
4Checkout fails on expired cardBugPaymentsChen
5Upgrade logging libraryTech debtPlatformDee
Backlog
SpreadsheetAgile & Scrum

Sprint Backlog

User stories with points and status, a live burndown against the ideal line, and velocity from past sprints.

10 min setupPreview
Bug Tracker2 sheets

Open bugs

5

Open critical

1

SLA breached

4

ABCD
1TitleSeverityEnvironmentSteps to reproduce
2Checkout fails when card has expiredCriticalProductionAdd item, pay with expired test card
3Order history filter ignores date rangeMajorProductionFilter orders by last 30 days
4Typo on pricing pageTrivialProductionOpen /pricing
5Search is slow on large cataloguesMajorProductionSearch with 10,000+ products
Bugs
SpreadsheetAgile & Scrum

Bug Tracker

Bugs with severity, environment, owner and status, plus age, SLA breaches and time to resolve.

10 min setupPreview

Sprint Retrospective: Sprint 14

Date: Date · Facilitator: Name · Team: Team name

Sprint facts

Committed pointsCompleted pointsBugs found
31243

Last retro's actions

  • •Action: Done / Not done

What went well

  • •Item
  • •Item
DocumentAgile & Scrum

Sprint Retrospective

Run a focused retro: what went well, what to improve and owned actions.

15 min setupPreview

Practical guides and new resources, monthly.

One short email with new templates, calculators and how-tos. Unsubscribe any time.

GraviPointThe Centre of Productivity

Find the right resource. Make it work for you. Get things done with spreadsheets, documents, forms and calculators you can use right in your browser.

support@gravipoint.com
  • @gravipoint
  • @GraviPoint
  • GraviPoint
  • 𝕏@gravipoint

Templates

  • All templates
  • Budgets & expenses
  • Invoices & billing
  • Project management
  • HR & people
  • Inventory & stock
  • Sales & CRM
  • Financial calculators

Popular

  • Monthly budget
  • Invoice
  • Employee shift schedule
  • Weekly timesheet
  • Project plan & Gantt chart
  • Inventory tracker
  • Expense report
  • Mortgage calculator

Solutions

  • Individuals & households
  • Freelancers & consultants
  • Founders & startups
  • Small business owners
  • Teams & operations
  • Students & educators

Company

  • About
  • Features
  • Pricing
  • Community
  • Journal
  • Contact
© 2026 GraviPoint. All rights reserved.
  • Privacy
  • Terms
  • Help centre
  • FAQ