# Technical design document template

Six linked documents that take a system from requirements to rollout: the context, the architecture, the data and interfaces, how it runs and fails, and the options you turned down. Download them as Markdown files: they open in any editor, sit next to the code in a repository, draw their diagrams on GitHub and in Obsidian, and import into Nodary as a map.

Free, no account, no email. Use it, change it, share it.

[Download the template (.zip)](https://nodary.ai/downloads/technical-design-document-template.zip)

## Read every page before you download

The overview fits on one screen and links to five parts, so a reviewer reads the summary, then goes straight to the part they own. Italic lines say what to write; the examples follow one sample feature, share links that expire.

- Technical design document: The page everyone reads first: the summary, goals and non-goals, and a link to every part.
- Context and requirements: What exists today, the requirements the design must meet, and the constraints around it.
- Architecture: The components, how they talk to each other, how a request flows through them, and the key decisions.
- Data and interfaces: The data model, the APIs and events, and how existing data moves to the new shape.
- Operations: How it is deployed and watched, how it stays secure, and what happens when something fails.
- Alternatives and risks: The options you turned down and why, the risks, the rollout plan and the open questions.

### Technical design document

_How to use this template: italic lines are guidance. Replace them with your own words, then delete them. Values in square brackets are yours to fill in. Keep this page to one screen: a reviewer should know from it what they are approving._

#### At a glance

| Field | This design |
| --- | --- |
| System or feature | [Name] |
| Author | [name] |
| Reviewers | [names] |
| Status | [draft, in review, approved, built] |
| Requirements | [link to the PRD] |
| Target release | [date or version] |

#### Summary

_Three sentences: what you will build, why, and the one decision a reviewer should look at first._

_Example (a sample feature): Share links get an optional end date. Every request checks the date, so a link stops working the moment it ends. A scheduled job revokes expired links every minute; it only cleans up, so a late run changes nothing for the person opening the link._

[Your summary]

#### Goals and non-goals

- Goal: [...]
- Goal: [...]
- Non-goal: [...]
- Non-goal: [...]

#### The rest of the design

_Each part is its own document. Link to it rather than copy from it, so every fact lives in one place._

- [Context and requirements](https://nodary.ai/templates/technical-design-document#doc-context): what exists today, the requirements and the constraints
- [Architecture](https://nodary.ai/templates/technical-design-document#doc-architecture): the components, the request flow and the key decisions
- [Data and interfaces](https://nodary.ai/templates/technical-design-document#doc-data): the data model, the APIs, the events and the migration
- [Operations](https://nodary.ai/templates/technical-design-document#doc-operations): deployment, monitoring, security and failure modes
- [Alternatives and risks](https://nodary.ai/templates/technical-design-document#doc-alternatives): the options turned down, the risks, the rollout and open questions

_This template is free to use, change and share. It comes from_ [Nodary](https://nodary.ai)_, where these files import as a map of linked documents._

### Context and requirements

**Owner:** [name] · **Status:** draft · **Last reviewed:** [date]

#### Current state

_What exists today and what is wrong with it, in a few sentences. Link the code, the dashboards and the earlier designs._

[Current state]

#### Requirements

_The requirements that shape the design, each linked to where it comes from. Leave out the ones the design does not affect._

| ID | Requirement | Source |
| --- | --- | --- |
| [R1] | [...] | [PRD, incident, regulation] |
| [R2] | [...] | [...] |

_Example (a sample feature): R1: a link stops opening within one minute of its end date. Source: the PRD’s acceptance criteria._

#### Constraints

- Performance: [...]
- Security and privacy: [...]
- Compatibility: [...]
- Team and time: [...]

#### Assumptions

- [Assumption], checked by [name]
- [...]

Related: [Technical design document](https://nodary.ai/templates/technical-design-document#doc-overview) · [Architecture](https://nodary.ai/templates/technical-design-document#doc-architecture)

### Architecture

**Owner:** [name] · **Status:** draft · **Last reviewed:** [date]

#### Components

_Replace these boxes with yours. Mark what is new, what changes and what stays as it is._

```mermaid
flowchart TD
  n0["Client"]
  n1["API"]
  n2["Service"]
  n3["Database"]
  n4["Job queue"]
  n5["File storage"]
  n0 --> n1
  n1 --> n2
  n2 --> n3
  n2 --> n4
  n4 --> n3
  n2 --> n5
```
_Main components and the calls between them_

| Component | Responsibility | Owner | New or changed |
| --- | --- | --- | --- |
| [API] | [...] | [team] | [new, changed, unchanged] |
| [...] | [...] | [...] | [...] |

#### Request flow

_Follow one request from the user’s action to the response. Number the steps: reviewers comment on them by number._

1. [The user does ...]
2. [The API checks ...]
3. [The service writes ...]
4. [The response says ...]

#### Key decisions

_The choices a reviewer must agree with. Give each significant one a record in the team’s decision log, and link it here._

| Decision | Why | Record |
| --- | --- | --- |
| [...] | [...] | [link] |

Related: [Context and requirements](https://nodary.ai/templates/technical-design-document#doc-context) · [Data and interfaces](https://nodary.ai/templates/technical-design-document#doc-data) · [Operations](https://nodary.ai/templates/technical-design-document#doc-operations)

### Data and interfaces

**Owner:** [name] · **Status:** draft · **Last reviewed:** [date]

#### Data model

| Entity | Field | Type | Notes |
| --- | --- | --- | --- |
| [...] | [...] | [...] | [nullable, indexed, personal data] |
| [...] | [...] | [...] | [...] |

_Example (a sample feature): share__link.expires__at: a timestamp with time zone, empty when the link has no end date, indexed for the job that revokes expired links._

#### APIs

| Method | Path | Purpose | Who can call it |
| --- | --- | --- | --- |
| [POST] | [/...] | [...] | [...] |
| [...] | [...] | [...] | [...] |

#### Events

| Event | Emitted when | Read by |
| --- | --- | --- |
| [...] | [...] | [...] |

#### Migration

_How existing data reaches the new shape without downtime, and how you would undo it._

1. [Add the new fields, empty]
2. [Write to old and new]
3. [Backfill]
4. [Read from new]
5. [Remove the old]

Related: [Architecture](https://nodary.ai/templates/technical-design-document#doc-architecture) · [Operations](https://nodary.ai/templates/technical-design-document#doc-operations)

### Operations

**Owner:** [name] · **Status:** draft · **Last reviewed:** [date]

#### Deployment

- Where it runs: [...]
- How it ships: [pipeline, flags]
- Configuration and secrets: [...]

#### Monitoring and alerts

| Signal | Normal | Alert when | Alert goes to |
| --- | --- | --- | --- |
| [error rate] | [...] | [...] | [team] |
| [...] | [...] | [...] | [...] |

#### Security and privacy

- [ ] Every request checks who is asking and what they may do
- [ ] Personal data listed, with where it is kept and for how long
- [ ] Secrets kept out of the code and the logs
- [ ] Input checked where it enters the system
- [ ] Abuse and rate limits considered

#### Failure modes

| Failure | What users see | How we notice | How we recover |
| --- | --- | --- | --- |
| [...] | [...] | [...] | [...] |
| [...] | [...] | [...] | [...] |

_Example (a sample feature): The revoking job stops: expired links are still refused, since every request checks the date; only the cleanup lags. An alert fires when the job has not run for five minutes._

Related: [Architecture](https://nodary.ai/templates/technical-design-document#doc-architecture) · [Alternatives and risks](https://nodary.ai/templates/technical-design-document#doc-alternatives)

### Alternatives and risks

**Owner:** [name] · **Status:** draft · **Last reviewed:** [date]

#### Alternatives considered

| Option | For | Against | Why not |
| --- | --- | --- | --- |
| [...] | [...] | [...] | [...] |
| [...] | [...] | [...] | [...] |

#### Risks

| Risk | Impact | What we do about it | Owner |
| --- | --- | --- | --- |
| [...] | [low, medium, high] | [...] | [name] |

#### Rollout

1. Behind a flag, for [the team]
2. [A small share] of [users]
3. Everyone
4. Flag removed

#### Open questions

- [ ] [Question], [who answers it], [by when]

Related: [Technical design document](https://nodary.ai/templates/technical-design-document#doc-overview) · [Context and requirements](https://nodary.ai/templates/technical-design-document#doc-context) · [Operations](https://nodary.ai/templates/technical-design-document#doc-operations)

## How to use it

### Start from the requirements

Link the product requirements in the context page and list the ones that shape the design. A design that answers no requirement is a refactoring in disguise.

### Draw, then write

Draw the components and the calls between them before the prose. Reviewers spot a missing box faster than a missing paragraph.

### Write down what you rejected

Fill in the alternatives with the options you seriously considered. It saves the review from reopening them one by one.

### Update it after the build

When the code ships, mark what changed from the plan. The next person reads the design to learn how the system works, not how it was imagined.

## Import it into Nodary as a map

Nodary is an AI-native workspace where a team’s documents link instead of piling up. Import the .zip and the design arrives with its five parts filed under it, its links kept and its diagram drawn as a Mermaid diagram you can edit. Reviewers comment on a passage or on an element of a diagram, the author asks for an approval, and coding agents such as Cursor, Claude Code or VS Code, connected over MCP, read the design before they write the code.

1. Open a project’s map and choose Import.
2. Choose the Folder or ZIP tab, then Choose a ZIP.
3. Pick the downloaded file, check the tree, and import.

The Free plan holds ten documents per workspace, the project’s own page included: the template’s six leave room for three more. Nodary also has a one-page Technical Design template built in.

## Writing a design document reviewers can approve

A technical design document fails when reviewers cannot tell what they are approving, or when the system it describes is not the one that shipped. These habits prevent both.

### Lead with the decision

Say in the summary what you will build and the one choice a reviewer should look at first. Nobody should reach page three to find it.

### Draw before you write

A diagram of six boxes and their calls beats six pages of prose, and shows the missing piece at once.

### Name what you will not do

Non-goals keep the review on the design at hand instead of the one someone wishes you were writing.

### Show the options you turned down

For each significant choice, say what else you considered and why not. Reviewers then argue with your reasons, not with your conclusion.

### Plan for failure

Say what happens when each part fails, how you will notice, and how you recover. Operations is part of the design, not an appendix.

### Keep it true after the build

Mark what changed during the build and link the decisions behind it. A design that matches the code is documentation; one that does not is a trap.

## Questions about technical design documents

### What is a technical design document?

A technical design document, or TDD, describes how a system or a feature will be built before the code is written: its context and requirements, its architecture, its data and interfaces, how it is deployed and monitored, the risks and the alternatives considered. Engineers write it so that others can review the approach while it is still cheap to change.

### What should a technical design document include?

A summary with goals and non-goals, the current state and the requirements, the components and how they talk to each other, the data model and the APIs, deployment, monitoring, security and failure modes, the alternatives considered, the risks, the rollout plan and the open questions. This template has a document for each group.

### What is the difference between a technical design document and a PRD?

The product requirements document says what the feature must do and why. The technical design document says how the system will do it. Write the PRD first, then link it from the design so each requirement can be traced.

### When does a change need a design document?

When it touches several components or teams, changes data that already exists, is hard to undo, or carries a risk worth a second pair of eyes. A small change inside one component usually needs a good pull request, not a design document.

### Who should review a technical design document?

The engineers who will build and run it, an engineer from each system it touches, and someone responsible for security when it handles personal data or access. Ask for the review early, before most of the code exists.

### Do game teams write technical design documents too?

Yes. The game design document template has a technical design part for the engine, targets and pipeline; a large system such as networking, saves or tools deserves a full technical design document of its own, linked from it.

The page: https://nodary.ai/templates/technical-design-document