Design Doc Template (Technical Design Document) in Markdown

# Design doc: Quiet hours scheduler (EXAMPLE, fictional product "Relay")

| | |
|---|---|
| **Status** | In review |
| **Author(s)** | Mateo Silva |
| **Reviewers** | Priya Raman, Lee Chen |
| **Approver** | Engineering manager, Notifications |
| **Related** | PRD: Quiet hours · Ticket: RELAY-1842 |
| **Created** | 2026-11-09 |
| **Decision needed by** | 2026-11-23 |
| **Last updated** | 2026-11-09 |

## TL;DR

We will decide at send time whether to hold a notification, using a per-user schedule stored in the existing settings table and evaluated by the notification service. Held messages go to a digest queue that a worker flushes when quiet hours end. We chose evaluation at send time over a scheduled job because it needs no clock-driven sweeps. Reviewers: please check the digest queue sizing and the urgent-message path.

## Context and problem

Today the notification service sends every push as soon as a message arrives. The PRD asks for quiet hours (R1 to R5). The service has no concept of the recipient's local time, and the only way to stop pushes is to mute a channel.

## Goals and non-goals

**Goals**

- Hold non-urgent pushes during a user's quiet hours (R2) and let urgent ones through (R3).
- Add no more than 50 ms at P95 to delivery (non-functional requirement).

**Non-goals**

- Admin-set team schedules.
- Email notifications.

## Requirements this design must meet

| Requirement | Source | Where it is addressed |
|---|---|---|
| R1 Schedule per weekday | PRD | Data model |
| R2 Hold non-urgent | PRD | Key flows, step 2 |
| R3 Urgent breaks through | PRD | Key flows, step 1 |
| R4 Digest after quiet hours | PRD | Components: digest worker |
| Add at most 50 ms at P95 | PRD | Cross-cutting: performance |

## Proposed design

### Overview

The notification service reads the recipient's schedule from a cache, decides hold or send, and writes held messages to a digest queue. A worker flushes the queue when the schedule says quiet hours have ended.

```mermaid
flowchart LR
    A[Message service] --> B[Notification service]
    B -->|send| C[Push gateway]
    B -->|hold| D[(Digest queue)]
    E[Digest worker] --> D
    E --> C
    B --> F[(Schedule cache)]
```

### Components and responsibilities

| Component | Responsibility | Owner |
|---|---|---|
| Notification service | Decide hold or send for each message | Notifications |
| Schedule cache | Hold each user's schedule and time zone, 5 minute TTL | Notifications |
| Digest queue | Store held messages with channel and timestamp | Notifications |
| Digest worker | At the end of quiet hours, send one digest per user | Notifications |

### Data model

```text
quiet_hours(user_id, weekday 0-6, start_minute 0-1439, end_minute 0-1439, time_zone)
digest_item(user_id, channel_id, message_id, held_at)   -- deleted after the digest is sent
```

### Interfaces and APIs

```text
PUT /v1/me/quiet-hours
{"time_zone": "Europe/Lisbon", "days": [{"weekday": 1, "start": "19:00", "end": "08:00"}]}
-> 200 {"saved": true}
```

### Key flows

1. An urgent message skips the schedule check and is sent at once.
2. A normal message: read the schedule from the cache; if now falls inside quiet hours, write a digest item and stop; otherwise send.
3. If the cache is down, send the message (fail open): a late-night push is better than a lost message.

## Alternatives considered

| Option | How it works | Pros | Cons | Verdict |
|---|---|---|---|---|
| **Proposed:** decide at send time | Check the schedule when the message arrives | No clock-driven jobs; simple | Adds a cache read to every send | Chosen because the cost is small and measurable |
| Scheduled sweep | A job marks users as quiet or active every minute | Cheap per message | A minute of lag; load spikes on the hour | Rejected because of lag at the start and end |
| Client-side hold | The app suppresses pushes locally | No server work | Does not work if the app is closed | Rejected because it fails the main case |
| Do nothing | Keep muting channels | No work | Problem stays | Rejected, see the PRD |

## Cross-cutting concerns

- **Security and privacy:** other users can read only the end time of quiet hours, never the schedule.
- **Performance and scale:** one cache read per message; target 50 ms at P95, measured in the rollout.
- **Reliability:** the service fails open if the cache or the schedule store is unavailable.
- **Observability:** metrics message_held, digest_sent, schedule_cache_miss; alert if the digest queue grows for 10 minutes.
- **Cost:** a small cache and one more queue; no new paid service.

## Migration and rollout

- **Migration:** a new table, no change to existing data. Users without a schedule are never held.
- **Rollout:** behind a flag, internal for a week, then 10%, then everyone.
- **Rollback:** switch the flag off; held items are sent as a digest at the next flush.

## Testing plan

- **Unit and integration:** the hold decision across time zones and daylight saving changes.
- **Load or failure tests:** cache down, digest queue at 10x expected size.
- **Acceptance:** each PRD acceptance criterion is a test case.

## Risks and open questions

| Item | Type | Owner | Resolve by |
|---|---|---|---|
| Daylight saving changes during quiet hours | Risk | Mateo | 2026-11-16 |
| Digest limit per user | Question | Priya | 2026-11-16 |

## Decision log

| Date | Decision | Reason | Decided by |
|---|---|---|---|
| 2026-11-09 | Fail open when the cache is down | Missing a message is worse than a late push | Mateo, engineering manager |