Title: [Clear, descriptive title]
Author(s): [Name(s)]
Date Created: [YYYY-MM-DD]
Status: Draft / In Review / Final
Reviewers: [Names of reviewers/stakeholders]
Overview
A high-level summary of what youโre designing and why.
Include just enough context to help new readers quickly understand the proposal.
Problem Statement
What problem are you solving?
Why is it important? Include any user pain points, system limitations, or business motivations.
Goals & Non-Goals
Goals:
- What this design aims to accomplish
Non-Goals:
- Whatโs explicitly out of scope (to reduce confusion)
Detailed Design
Describe the proposed solution in detail. Use diagrams, pseudocode, or data flows if helpful.
Include:
- Architecture overview
- Key components/modules
- Data models and APIs
- Security, performance, and scalability considerations
- UX/UI (if applicable)
Alternatives Considered
List any other approaches that were evaluated.
Include reasons why they were not chosen.
Trade-offs
Discuss known trade-offs, such as:
- Simplicity vs. flexibility
- Short-term vs. long-term
- Cost vs. performance
Testing & Validation
How will the solution be tested?
Unit tests, integration tests, performance testing, etc.
Milestones / Timeline
| Milestone | Target Date |
| Design review | YYYY-MM-DD |
| Implementation start | YYYY-MM-DD |
| Feature complete | YYYY-MM-DD |
| Launch / rollout | YYYY-MM-DD |
Risks & Mitigations
What might go wrong, and how will you reduce those risks?
Examples:
- Risk: Data loss โ Mitigation: Shadow write during migration
- Risk: Feature misuse โ Mitigation: Add usage constraints
Open Questions
Any unresolved decisions or questions that need team input.
Stakeholders
| Role | Name | Involvement |
| Engineering Lead | [Name] | Reviewer |
| Product Manager | [Name] | Requirements |
| QA | [Name] | Test planning |
Appendix / References
Include links to related tickets, RFCs, diagrams, spreadsheets, Slack threads, etc.
Approval
| Approver | Role | Decision | Date |
| [Name] | [e.g., Tech Lead] | โ / โ | [Date] |