# Technical design document: [System or change]

**Author:** [Name]  
**Reviewers:** [Names]  
**Status:** Draft  
**Version:** 0.1  
**Last updated:** YYYY-MM-DD

## Summary

[Describe the proposed technical change and why it is needed.]

## Context and problem

[Current architecture, user or system problem, evidence, and constraints.]

## Goals

- [Technical or product outcome]

## Non-goals

- [Explicit exclusion]

## Requirements

### Functional

- [Required behavior]

### Non-functional

| Requirement | Target |
|---|---|
| Availability | [Target] |
| Latency | [Target] |
| Security | [Control] |
| Data retention | [Period] |

## Proposed design

### Architecture

[Describe components and data flow. Link a diagram if used.]

### Interfaces and data contracts

```json
{
  "example": "Replace with a representative request or event"
}
```

### Data model and migration

[Schema changes, backfill, compatibility, and rollback.]

### Security and privacy

[Authentication, authorization, secrets, logging, personal data, and threat controls.]

## Alternatives considered

| Option | Advantages | Disadvantages | Decision |
|---|---|---|---|
| [Option] | [Benefits] | [Costs] | Selected/Rejected |

## Failure modes and recovery

| Failure | Detection | Response | Owner |
|---|---|---|---|
| [Failure] | [Signal] | [Recovery] | [Team] |

## Testing and validation

- [Unit, integration, end-to-end, performance, security, and migration checks]

## Rollout plan

1. [Preparation]
2. [Limited release]
3. [Monitoring]
4. [Full release]

**Rollback trigger:** [Condition]  
**Rollback procedure:** [Steps]

## Observability

- **Metrics:** [List]
- **Logs:** [List]
- **Alerts:** [Threshold and owner]

## Open questions

- [ ] [Question] · **Owner:** [Name]