Technical Design: [Feature or system]

Author: [Name]
Reviewers: [Names]
Status: Draft
Related requirements: [PRD or issue links]

Context and goals

[Explain the existing system, the change needed, and the requirements this design satisfies.]

Non-goals: [Explicitly excluded capabilities.]

Proposed architecture

[Describe components, ownership boundaries, and how requests move through the system.]

Component	Responsibility	Inputs and outputs	Owner
[Client]	[User interaction]	[Requests and responses]	[Team]
[Service]	[Business rules]	[Validated operations]	[Team]
[Storage]	[Persistence]	[Data model and queries]	[Team]

Data model

Entity or field	Type	Constraints	Lifecycle
[Entity.id]	[Identifier]	[Unique, required]	[Creation and deletion]
[Entity.ownerId]	[Identifier]	[Ownership relation]	[Transfer and retention]

Consistency: [Transactions, concurrent writes, conflict resolution, and invariants.]

Interfaces and request flow

1. [Validate input and authenticate the caller.]
2. [Authorize access to the specific resource.]
3. [Execute the operation and persist state.]
4. [Publish events or return the response.]

Contracts: [API or event schema links, versioning, and compatibility expectations.]

Failure handling

Failure	Detection	User or system behavior	Recovery
[Dependency timeout]	[Signal]	[Error or fallback]	[Retry budget and backoff]
[Duplicate request]	[Idempotency key]	[Stable result]	[Retention and conflict policy]
[Partial write]	[Signal]	[Consistency behavior]	[Transaction or compensation]

Security and privacy

• Trust boundaries: [Untrusted inputs and validation.]
• Access control: [Roles, resource-level authorization, tenant isolation.]
• Sensitive data: [Classification, logging redaction, retention and deletion.]
• Abuse controls: [Rate limits and resource limits.]

Performance and observability

Concern	Target or expectation	Verification
Latency and throughput	[Percentile, load, target]	[Load test]
Capacity	[Volume and growth assumptions]	[Capacity estimate]
Reliability	[Availability or error budget]	[Metrics and alerts]

Diagnostics: [Logs, metrics, traces, dashboards, and on-call ownership.]

Alternatives and tradeoffs

Alternative	Advantages	Disadvantages	Reason not selected
[Alternative approach]	[Pros]	[Cons]	[Evidence or constraint]

Test and rollout plan

• Unit, integration, and end-to-end coverage mapped to requirements.
• Migration tested with representative data and recovery procedure.
• Backward compatibility verified during mixed-version deployment.
• Staged rollout and monitoring window assigned.
• Rollback triggers, data compatibility, and owner documented.

Open questions

Question	Owner	Resolution needed by
[Unresolved design choice]	[Name]	[Date]