gh-onezerocompany-claude-project-basics/skills/spec-author/templates/design-document.md

### Design Document

# <!-- Title and ID, e.g., #[DESIGN-001] Microservices Architecture for User Service -->

Type: <!-- Architecture | System Design | RFC | Technology Choice -->
Status: <!-- Draft | Under Review | Accepted | Rejected -->
Version: <!-- e.g., 1.0.0 -->

## Executive Summary

<!-- 3-4 sentences: What problem does this solve? What's the proposed solution? What are the key tradeoffs? -->

## Problem Statement

<!-- Describe the current state, limitations, and impact. Why are existing solutions insufficient? -->

## Goals & Success Criteria

### Primary Goals
- **Goal 1**: <!-- Specific, measurable objective -->
- **Goal 2**: <!-- Specific, measurable objective -->
- **Goal 3**: <!-- Specific, measurable objective -->

### Success Criteria
1. <!-- Measurable criterion with target metrics -->
2. <!-- Measurable criterion with target metrics -->
3. <!-- Measurable criterion with target metrics -->

## Context & Background

<!-- Why now? What triggered this decision? What constraints exist? Historical context if relevant. -->

## Proposed Solution

### High-Level Overview

<!-- Architecture diagram or ASCII art showing major components and data flow -->

```
┌─────────────┐
│   Client    │
└──────┬──────┘
       │
       ├─→ [API Gateway]
       │         │
       ├─→ [Service Layer]
       │    ├─ Service A
       │    └─ Service B
       │
       └─→ [Data Layer]
            ├─ Database
            └─ Cache
```

<!-- Brief narrative: How do components work together? What's the overall approach? -->

### Architecture Components

#### <!-- Component Name -->
- **Purpose**: <!-- What this component does -->
- **Technology**: <!-- Stack choice and version -->
- **Key Responsibilities**: <!-- Primary functions -->
- **Interactions**: <!-- How it connects with other components -->

#### <!-- Component Name -->
- **Purpose**: <!-- What this component does -->
- **Technology**: <!-- Stack choice and version -->
- **Key Responsibilities**: <!-- Primary functions -->
- **Interactions**: <!-- How it connects with other components -->

### Design Decisions

#### Decision 1: <!-- Decision Title -->
- **Decision**: <!-- What was chosen -->
- **Rationale**: <!-- Why this choice over alternatives -->
- **Alternatives Considered**: <!-- Briefly list other options and why they weren't chosen -->
- **Impact**: <!-- Key consequences of this decision -->

#### Decision 2: <!-- Decision Title -->
- **Decision**: <!-- What was chosen -->
- **Rationale**: <!-- Why this choice over alternatives -->
- **Alternatives Considered**: <!-- Briefly list other options and why they weren't chosen -->
- **Impact**: <!-- Key consequences of this decision -->

### Technology Stack

**Language & Runtime**
- <!-- Technology, version, and rationale -->

**Data Layer**
- <!-- Primary database/storage, version, and rationale -->
- <!-- Cache layer, version, and rationale -->

**Infrastructure**
- <!-- Hosting/cloud platform and rationale -->
- <!-- Container/orchestration technology if applicable -->

**Key Libraries/Frameworks**
- <!-- Critical dependencies with versions -->

### Data Model & Storage

<!-- Reference data specification or provide high-level overview -->

**Storage Strategy**
- **Primary Database**: <!-- Choice and structure -->
- **Caching**: <!-- Strategy and technology -->
- **Data Retention**: <!-- Archival and cleanup policies -->

<!-- Optionally include simplified schema or entity relationships -->

### API & Integration Points

<!-- Reference API specification or list key endpoints and integrations -->

**External Dependencies**
- Integrates with <!-- Service/API name --> for <!-- purpose -->
- Consumes events from <!-- Service/API name -->
- Publishes events to <!-- Service/API name -->

**Key Endpoints** (or reference API spec)
- <!-- HTTP method and path -->: <!-- Purpose -->
- <!-- HTTP method and path -->: <!-- Purpose -->

## Trade-offs

### Accepting
- <!-- Cost, complexity, or limitation we're accepting -->
- <!-- Technical debt or constraint we're taking on -->
- <!-- Performance or feature tradeoff -->

### Gaining
- <!-- Primary benefit we're achieving -->
- <!-- Problem we're solving -->
- <!-- Capability we're enabling -->

## Implementation

<!-- Reference implementation plan or outline high-level phases -->

**Approach**: <!-- Sequential rollout, phased migration, parallel development, etc. -->

**Phases**:
1. **Phase 1**: <!-- Description, key deliverables -->
2. **Phase 2**: <!-- Description, key deliverables -->
3. **Phase 3**: <!-- Description, key deliverables -->

**Migration Strategy** (if applicable):
- <!-- How existing systems/data will be transitioned -->

See [Plan Specification](#) for detailed implementation roadmap.

## Performance & Scalability

### Performance Targets
- **Latency**: <!-- e.g., < 100ms p95, < 200ms p99 -->
- **Throughput**: <!-- e.g., 1000 requests/second -->
- **Availability**: <!-- e.g., 99.9% uptime -->

### Scalability Strategy
- **Scaling Approach**: <!-- Horizontal/vertical, stateless design, etc. -->
- **Bottlenecks**: <!-- Known limitations and mitigation strategies -->
- **Auto-scaling**: <!-- Triggers, thresholds, and scaling policies -->

### Monitoring & Observability
- **Metrics**: <!-- Key metrics to track -->
- **Alerting**: <!-- Critical alerts and thresholds -->
- **Logging**: <!-- Logging strategy and aggregation -->

## Security

**Authentication**
- <!-- Method: JWT, OAuth, API keys, etc. -->

**Authorization**
- <!-- Access control approach: RBAC, ABAC, etc. -->

**Data Protection**
- **Encryption at Rest**: <!-- Method and key management -->
- **Encryption in Transit**: <!-- TLS/SSL configuration -->
- **PII Handling**: <!-- Sensitive data protection approach -->

**Secrets Management**
- <!-- How secrets, credentials, and keys are managed -->

**Compliance**
- <!-- Relevant standards: GDPR, SOC2, HIPAA, etc. -->

## Dependencies & Assumptions

### Dependencies
- <!-- External service or system dependency and impact if unavailable -->
- <!-- Team or resource dependency -->
- <!-- Third-party library or platform dependency -->

### Assumptions
- <!-- Key assumption that must hold true for this design to work -->
- <!-- Assumption about scale, usage patterns, or constraints -->
- <!-- Assumption about external systems or future capabilities -->

## Open Questions

<!-- Questions that need resolution before or during implementation -->

- [ ] <!-- Question or decision to be made --> - **Status**: <!-- Under investigation, blocked, etc. -->
- [ ] <!-- Question or decision to be made --> - **Status**: <!-- Under investigation, blocked, etc. -->
- [ ] <!-- Deferred decision with rationale for deferral -->

## Approvals

**Technical Review**
- <!-- Name, Role -->

**Architecture Review**
- <!-- Name, Role -->

**Security Review**
- <!-- Name, Role -->

**Approved By**
- <!-- Name, Role -->