Software Design Document Template

Create comprehensive technical design documents following the Atlassian 8-section structure.

Document Structure Overview

| Section | Purpose | |---------|---------| | 1. Introduction | Purpose, scope, definitions | | 2. System Overview | High-level architecture | | 3. Design Considerations | Assumptions, constraints, risks | | 4. Architectural Strategies | Key decisions and alternatives | | 5. System Architecture | Components, data flow, APIs, models | | 6. Policies and Tactics | Security, error handling, logging | | 7. Detailed Design | Component-level specifications | | 8. Appendix | Diagrams, glossary |

Section Templates

Section 1: Introduction

## 1. Introduction

### 1.1 Purpose
[What this document covers and its intended audience]

### 1.2 Scope
[System boundaries - what's included and excluded]

### 1.3 Definitions and Acronyms
| Term | Definition |
|------|------------|
| [Term] | [Definition] |

### 1.4 References
- PRD: [link to PRD document]
- [Other relevant documents]

Section 2: System Overview

## 2. System Overview

### 2.1 System Context
[How this system fits into the broader architecture]

### 2.2 High-Level Architecture
[Architecture diagram description or ASCII diagram]

### 2.3 Key Components
- **Component A**: [Purpose and responsibility]
- **Component B**: [Purpose and responsibility]

Section 3: Design Considerations

## 3. Design Considerations

### 3.1 Assumptions
- [Assumption 1]
- [Assumption 2]

### 3.2 Constraints
- [Technical constraint]
- [Business constraint]

### 3.3 Dependencies
- [External system X]
- [Library Y version Z]

### 3.4 Risks
| Risk | Impact | Mitigation |
|------|--------|------------|
| [Risk] | High/Med/Low | [Strategy] |

Section 4: Architectural Strategies

## 4. Architectural Strategies

### 4.1 Strategy Selection
[Why this architecture was chosen over alternatives]

### 4.2 Alternatives Considered
| Option | Pros | Cons | Decision |
|--------|------|------|----------|
| [Option A] | [Pros] | [Cons] | Selected |
| [Option B] | [Pros] | [Cons] | Rejected |

### 4.3 Key Architectural Decisions
- **Decision 1**: [Decision and rationale]
- **Decision 2**: [Decision and rationale]

Section 5: System Architecture

## 5. System Architecture

### 5.1 Component Diagram
[Description or ASCII representation]

### 5.2 Data Flow
[How data moves through the system]

### 5.3 API Design

#### 5.3.1 Endpoints
| Method | Path | Description |
|--------|------|-------------|
| POST | /api/resource | Create resource |
| GET | /api/resource/:id | Get resource |

#### 5.3.2 Request/Response Schemas
[TypeScript interfaces or JSON schemas]

### 5.4 Data Models
[Database schema with types and constraints]

Section 6: Policies and Tactics

## 6. Policies and Tactics

### 6.1 Security
- Authentication: [Strategy]
- Authorization: [Strategy]
- Data encryption: [At rest / in transit]

### 6.2 Error Handling
- [Error handling strategy]
- [Retry policies]

### 6.3 Logging and Monitoring
- [What to log]
- [Alerting thresholds]

### 6.4 Performance
- [Caching strategy]
- [Connection pooling]

Section 7: Detailed Design

## 7. Detailed Design

### 7.1 [Component A] Design

#### 7.1.1 Responsibilities
- [Responsibility 1]
- [Responsibility 2]

#### 7.1.2 Interface
[TypeScript interface or function signatures]

#### 7.1.3 Implementation Notes
[Specific implementation details, algorithms, or patterns]

Section 8: Appendix

## 8. Appendix

### 8.1 Sequence Diagrams
[For complex flows]

### 8.2 State Diagrams
[For stateful components]

### 8.3 Glossary
[Extended definitions]

Requirement Traceability

Each design decision should trace to requirements:

### REQ-001 Implementation
**Requirement:** [Quote requirement]
**Design:** [How this design satisfies it]
**Verification:** [How to test it]

Quality Checklist

Before finalizing an SDD:

• [ ] Every PRD requirement (REQ-XXX) is addressed
• [ ] Data models are complete with types and constraints
• [ ] API contracts are fully specified
• [ ] Error scenarios are documented
• [ ] Security considerations are addressed
• [ ] Performance requirements have corresponding strategies
• [ ] Dependencies are versioned
• [ ] Diagrams are included where helpful

Additional Resources

For detailed section guidance and examples, see references/sections.md.