Design Documentation
Create technical blueprints that bridge requirements and implementation. This skill teaches how to document architecture decisions, component design, and system interactions.
When to Use This Skill
Use design documentation when:
- Requirements phase is complete and approved
- You need to plan technical implementation
- Multiple developers will work on the feature
- Architecture decisions need documentation
- The feature involves complex integrations
Design Document Structure
Standard Template
# Design Document: [Feature Name]
## Overview
[High-level summary of the feature and approach]
## Architecture
[System architecture and component overview]
## Components and Interfaces
[Detailed component descriptions and interactions]
## Data Models
[Data structures and relationships]
## Error Handling
[Error scenarios and response strategies]
## Testing Strategy
[Testing approach and quality assurance]Step-by-Step Process
Step 1: Requirements Analysis
Before designing, ensure you understand:
- All functional requirements
- Non-functional requirements (performance, security, scalability)
- Constraints (technology stack, timeline, resources)
- Integration points with existing systems
Analysis Questions:
- What does the system need to do?
- What are the performance expectations?
- What existing code/systems does this touch?
- What are the security requirements?
- What could go wrong?
Step 2: Research and Context Building
Identify areas needing research:
- Technology choices and alternatives
- Third-party integrations and APIs
- Best practices for similar systems
- Security and compliance considerations
Research Documentation:
## Research Findings
### [Topic]
**Sources:** [Links/references]
**Key Insights:**
- [Finding 1]
- [Finding 2]
**Impact on Design:** [How this affects our approach]Step 3: Define System Architecture
Document the high-level structure:
## Architecture
### System Overview
[How the overall system works]
### Component Architecture
[Major components and their responsibilities]
### Data Flow
[How information moves through the system]
### Technology Decisions
[Key technology choices and rationale]Architecture Diagram (Mermaid):
graph TD
A[Client] --> B[API Gateway]
B --> C[Auth Service]
B --> D[Feature Service]
D --> E[Database]
D --> F[Cache]Step 4: Design Components and Interfaces
For each major component:
## Components and Interfaces
### [Component Name]
**Purpose:** [What this component does]
**Responsibilities:**
- [Responsibility 1]
- [Responsibility 2]
**Interfaces:**
- Input: [What it receives]
- Output: [What it produces]
- Dependencies: [What it requires]
**API Definition:**interface ComponentName { method(input: InputType): Promise<OutputType>; }
Step 5: Define Data Models
Document all data structures:
## Data Models
### [Entity Name]
**Purpose:** [What this entity represents]
**Properties:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| id | string | Yes | Unique identifier |
| name | string | Yes | Display name |
| createdAt | Date | Yes | Creation timestamp |
**Validation Rules:**
- [Rule 1]
- [Rule 2]
**Relationships:**
- [Relationship to other entities]
**Example:**{ "id": "abc123", "name": "Example", "createdAt": "2024-01-15T10:30:00Z" }
Step 6: Plan Error Handling
Document error scenarios:
## Error Handling
### Error Categories
1. **Validation Errors:** Invalid user input
2. **Authentication Errors:** Unauthorized access
3. **External Service Errors:** Third-party failures
4. **System Errors:** Internal failures
### Error Response Strategy
| Error Type | HTTP Code | User Message | System Action |
|------------|-----------|--------------|---------------|
| Validation | 400 | Specific field error | Log, return details |
| Auth | 401 | "Please log in" | Redirect to login |
| Not Found | 404 | "Resource not found" | Log, return error |
| Server | 500 | "Something went wrong" | Log, alert, retry |
### Recovery Mechanisms
- [Retry strategies]
- [Fallback behaviors]
- [Circuit breaker patterns]Step 7: Define Testing Strategy
## Testing Strategy
### Unit Testing
- **Coverage Target:** 80%+
- **Focus Areas:** [Critical business logic]
- **Mocking Strategy:** [What to mock]
### Integration Testing
- **Scope:** [Component interactions to test]
- **Environment:** [Test environment setup]
- **Data Strategy:** [Test data approach]
### End-to-End Testing
- **Critical Paths:** [User journeys to test]
- **Tools:** [Testing tools]
### Performance Testing
- **Load Targets:** [Expected load]
- **Benchmarks:** [Performance requirements]Decision Documentation
Document key decisions using this template:
### Decision: [Brief Title]
**Context:** [Situation requiring a decision]
**Options Considered:**
**Option 1: [Name]**
- Pros: [Benefits]
- Cons: [Drawbacks]
- Effort: [Low/Medium/High]
**Option 2: [Name]**
- Pros: [Benefits]
- Cons: [Drawbacks]
- Effort: [Low/Medium/High]
**Decision:** [Chosen option]
**Rationale:** [Why this option was selected]
**Implications:** [What this means for implementation]Common Design Decisions
API Design
### Decision: API Architecture
**Options:**
1. **REST API** - Standard HTTP methods, well-understood
2. **GraphQL** - Flexible queries, single endpoint
3. **RPC-style** - Direct operation mapping
**Decision:** REST API
**Rationale:** Standard CRUD operations, team familiarity, good tooling supportData Storage
### Decision: Database Choice
**Options:**
1. **PostgreSQL** - ACID compliance, complex queries
2. **MongoDB** - Schema flexibility, horizontal scaling
3. **Redis** - High performance, limited queries
**Decision:** PostgreSQL with JSON columns
**Rationale:** Data consistency needs + flexibility for user preferencesAuthentication
### Decision: Authentication Strategy
**Options:**
1. **Session-based** - Server-controlled, simple
2. **JWT tokens** - Stateless, scalable
3. **OAuth 2.0** - External provider, no password management
**Decision:** JWT with refresh token rotation
**Rationale:** Scalability requirements, API-first architectureQuality Checklist
Before finalizing design:
Completeness:
- All requirements addressed in design
- Major system components defined
- Data models cover all entities
- Error handling covers expected failures
- Testing strategy addresses all layers
Clarity:
- Design decisions clearly explained
- Component responsibilities well-defined
- Interfaces between components specified
- Technical choices include rationale
Feasibility:
- Design is technically achievable
- Performance requirements can be met
- Security requirements addressed
- Implementation complexity reasonable
Traceability:
- Design elements map to requirements
- All requirements covered by design
- Testing validates requirement fulfillment
Common Pitfalls
- Over-Engineering: Design for current requirements, not hypothetical futures
- Under-Specified Interfaces: Define clear component boundaries
- Ignoring Non-Functional Requirements: Address performance, security, scalability
- Technology-First Design: Let requirements drive technology choices
- Insufficient Error Handling: Plan for failures, not just happy paths
Example: User Profile Design
# Design Document: User Profile Management
## Overview
Enable users to view and edit their profile information, including personal details, preferences, and profile picture.
## Architecture
### Component Architecture┌─────────────┐ ┌──────────────┐ ┌─────────────┐ │ Client │────▶│ Profile API │────▶│ Database │ └─────────────┘ └──────────────┘ └─────────────┘ │ ▼ ┌──────────────┐ │ Image Store │ └──────────────┘
### Technology Stack
- API: Node.js with Express
- Database: PostgreSQL
- Image Storage: S3-compatible object storage
- Cache: Redis for session data
## Components
### ProfileService
**Purpose:** Manage user profile CRUD operations
**Interface:**interface ProfileService { getProfile(userId: string): Promise<UserProfile>; updateProfile(userId: string, data: ProfileUpdate): Promise<UserProfile>; uploadAvatar(userId: string, image: File): Promise<string>; deleteAvatar(userId: string): Promise<void>; }
## Data Models
### UserProfile
| Field | Type | Required | Validation |
| --- | --- | --- | --- |
| id | UUID | Yes | Auto-generated |
| email | string | Yes | Valid email format |
| displayName | string | Yes | 2-50 characters |
| bio | string | No | Max 500 characters |
| avatarUrl | string | No | Valid URL |
| preferences | JSON | No | Valid JSON object |
| updatedAt | timestamp | Yes | Auto-updated |
## Error Handling
| Scenario | Response | Action |
| --- | --- | --- |
| Profile not found | 404 | Return error message |
| Invalid update data | 400 | Return validation errors |
| Image too large | 413 | Return size limit error |
| Unauthorized | 401 | Redirect to login |
## Testing Strategy
- Unit tests for validation logic
- Integration tests for API endpoints
- E2E test for profile edit flow
Next Steps
After completing design:
- Get design review and approval
- Move to Task Planning phase
- Break design into implementation tasks
- Begin systematic implementation