Design Doc: Feature or system name

Field	Value
Author	@name
Reviewers	@a, @b
Status	Draft / In review / Approved / Implemented
Created	YYYY-MM-DD
Last updated	YYYY-MM-DD

Overview

One paragraph: what this design does and the outcome it produces. A reader should understand the proposal in 60 seconds.

Background

Context a newcomer needs: current system, prior decisions, links to related docs.

Goals

• Goal one – measurable
• Goal two

Non-goals

• Explicitly out of scope

Detailed design

The core of the document. Sub-sections as needed:

Architecture

flowchart TD
    A[Component A] --> B[Component B]
    B --> C[(Store)]

APIs / interfaces

interface Contract {
  method(input: Input): Promise<Output>;
}

Data model

Schema, migrations, backward compatibility.

Failure modes

What can fail, how it degrades, how it recovers.

Alternatives considered

Option	Why not chosen
Alternative A	Reason

Security & privacy

Attack surface, data flows, auth implications.

Cost / performance

Resource impact, scaling characteristics, budgets.

Rollout

Phases, feature flags, migration path, rollback.

Open questions

• Unresolved item – owner