# [Feature name]: technical design

**Owner:** [name] · **Status:** Draft · **Last updated:** [date]
**Reviewers:** [engineering] · [security] · [owners of the systems it touches]

> Free technical design doc template from SprintProof: https://sprintproof.com/templates/technical-design-doc-template
> Replace everything in [brackets]. Delete the guidance lines (starting with ">") when you are done.

## 1. Context and goals

> Why this is being built and what the design has to achieve. Goals a reviewer can check the design against.

- **Builds on:** [link to the PRD or brief]
- **Goals:**
  - [The design must ...]
- **Constraints:** [deadline, existing systems, team size]

## 2. Non-goals

> What the design deliberately does not try to solve.

- [Not solved here]: [reason or where it is handled]

## 3. Proposed design

> The approach at a level where another engineer could build it. Describe the riskiest flow step by step and name every system it touches.

**Components:** [new or changed components and how they talk to each other]

1. [Step one of the main flow]
2. [Step two]
3. [Step three]

## 4. Data model

> Tables, columns, indexes and constraints. Say what is stored hashed, encrypted or not at all.

| Column | Type | Notes |
| --- | --- | --- |
| [name] | [type] | [constraint, index, hashed or not] |

**Queries that need an index:** [query] uses [index]

## 5. API

> Each call, who may make it and what comes back. List the stable error codes.

| Method and path | Who may call | Result and errors |
| --- | --- | --- |
| [METHOD /path] | [role] | [result, error codes] |

## 6. Alternatives considered

> The other ways you could have done it, including the one a reviewer is most likely to suggest, and why this one won.

| Option | For | Against | Decision |
| --- | --- | --- | --- |
| [option] | [benefit] | [cost or risk] | Chosen / Rejected |

## 7. Security and privacy

> How the design can be abused and what stops it. Include personal data it stores or sends.

- **Abuse case:** [how it could be misused] · **Control:** [limit, check or expiry]
- **Secrets and personal data:** [what is stored, in what form, for how long]

## 8. Rollout and migration

> The order in which the change ships, how it is switched on and how you undo it.

1. [Migration, additive and shipped alone]
2. [API behind a flag: name]
3. [Interface, then switch on for whom]

- **Rollback:** [how, and what happens to data written meanwhile]

## 9. Observability

> How you will know it works and how you will find out when it does not.

- **Events and metrics:** [what is recorded]
- **Alerts:** [failure], sent to [who]
- **First place to look when support reports a problem:** [log or dashboard]

## 10. Open questions and reviewers

> What is not decided, who decides it and by when. Then who has to approve the design.

| Question | Owner | Decide by | Answer |
| --- | --- | --- | --- |
| [question] | [name] | [date] | |

| Reviewer | Area | Decision | Conditions |
| --- | --- | --- | --- |
| [name] | [engineering, security, area owner] | Approved / Changes requested / Pending | |
