design-documentation

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:**
```markdown
## 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:**
```typescript
interface ComponentName {
  method(input: InputType): Promise<OutputType>;
}


### Step 5: Define Data Models

Document all data structures:

```markdown
## 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:**
```json
{
  "id": "abc123",
  "name": "Example",
  "createdAt": "2024-01-15T10:30:00Z"
}


### Step 6: Plan Error Handling

Document error scenarios:

```markdown
## 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 support

Data 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 preferences

Authentication

### 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 architecture

Quality 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:**
```typescript
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:
1. Get design review and approval
2. Move to Task Planning phase
3. Break design into implementation tasks
4. Begin systematic implementation

About this skill

When to Use This Skill

Design Document Structure

Standard Template

Overview

Architecture

Components and Interfaces

Data Models

Error Handling

Testing Strategy

Step 3: Define System Architecture

Step 4: Design Components and Interfaces

Step 7: Define Testing Strategy

Decision Documentation

Common Design Decisions

API Design

Data Storage

Authentication

Quality Checklist

Common Pitfalls

Example: User Profile Design

Data Models

UserProfile

Error Handling

Testing Strategy