--- name: design-documentation description: Transform approved requirements into comprehensive technical designs. Define system architecture, component interactions, data models, and interfaces to create a blueprint for implementation. license: MIT compatibility: Claude Code, Cursor, VS Code, Windsurf metadata: category: methodology complexity: intermediate author: Kiro Team version: "1.0.0" --- # 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 ```markdown # 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: ```markdown ## 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):** ```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: ```markdown ## 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; } ``` ``` ### 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 ```markdown ## 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: ```markdown ### 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 ```markdown ### 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 ```markdown ### 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 ```markdown ### 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 1. **Over-Engineering:** Design for current requirements, not hypothetical futures 2. **Under-Specified Interfaces:** Define clear component boundaries 3. **Ignoring Non-Functional Requirements:** Address performance, security, scalability 4. **Technology-First Design:** Let requirements drive technology choices 5. **Insufficient Error Handling:** Plan for failures, not just happy paths ## Example: User Profile Design ```markdown # 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; updateProfile(userId: string, data: ProfileUpdate): Promise; uploadAvatar(userId: string, image: File): Promise; deleteAvatar(userId: string): Promise; } ``` ## 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