musubi-sdd 0.1.0

package/src/templates/shared/documents/design.md

@@ -0,0 +1,737 @@
+# Technical Design: {{FEATURE_NAME}}
+
+**Project**: {{PROJECT_NAME}}
+**Version**: 1.0
+**Status**: Draft
+**Date**: {{DATE}}
+**Author**: {{AUTHOR}}
+
+---
+
+## Document Control
+
+| Version | Date | Author | Changes |
+|---------|------|--------|---------|
+| 1.0 | {{DATE}} | {{AUTHOR}} | Initial draft |
+
+---
+
+## Overview
+
+### Purpose
+
+[Describe the technical design for implementing the requirements]
+
+### Scope
+
+This design covers:
+- Architecture and component design
+- API contracts
+- Database schema
+- Integration points
+- Deployment architecture
+
+### Requirements Reference
+
+This design implements requirements from: [requirements.md](requirements.md)
+
+---
+
+## Steering Context
+
+**IMPORTANT**: This design aligns with project steering context:
+
+- **Architecture Patterns**: [steering/structure.md](../../steering/structure.md)
+- **Technology Stack**: [steering/tech.md](../../steering/tech.md)
+- **Product Context**: [steering/product.md](../../steering/product.md)
+
+**Key Alignments**:
+- Architecture pattern: [e.g., microservices, monolith, library-first]
+- Primary language: [e.g., TypeScript, Python, Go]
+- Framework: [e.g., Next.js, FastAPI, Express]
+- Database: [e.g., PostgreSQL, MongoDB, MySQL]
+
+---
+
+## Architecture Design
+
+### C4 Model: Context Diagram
+
+```
+[Diagram showing system in context with external systems and users]
+
++------------------+
+|                  |
+|  External User   |
+|                  |
++--------+---------+
+         |
+         | HTTPS
+         v
++------------------+     +------------------+
+|                  |     |                  |
+|  {{SYSTEM}}      +---->+ External API     |
+|                  |     |                  |
++--------+---------+     +------------------+
+         |
+         | SQL
+         v
++------------------+
+|                  |
+|    Database      |
+|                  |
++------------------+
+```
+
+**External Dependencies**:
+- [External System 1]: [Purpose]
+- [External System 2]: [Purpose]
+
+---
+
+### C4 Model: Container Diagram
+
+```
+[Diagram showing major containers/deployable units]
+
++--------------------------------------+
+|          {{SYSTEM}}                  |
+|                                      |
+|  +-------------+   +-------------+   |
+|  |             |   |             |   |
+|  |  Web App    +-->+  API Server |   |
+|  |  (Next.js)  |   |  (Node.js)  |   |
+|  |             |   |             |   |
+|  +-------------+   +------+------+   |
+|                           |          |
++---------------------------+----------+
+                            |
+                            | SQL
+                            v
+                   +--------+--------+
+                   |                 |
+                   |   PostgreSQL    |
+                   |                 |
+                   +-----------------+
+```
+
+**Containers**:
+1. **Web Application**: [Technology, purpose]
+2. **API Server**: [Technology, purpose]
+3. **Database**: [Technology, purpose]
+
+---
+
+### C4 Model: Component Diagram
+
+```
+[Diagram showing internal components of a container]
+
++-------------------------------------------+
+|          API Server Container             |
+|                                           |
+|  +---------------+   +----------------+   |
+|  |               |   |                |   |
+|  | Auth          |   | {{COMPONENT}}  |   |
+|  | Controller    +-->+ Service        |   |
+|  |               |   |                |   |
+|  +-------+-------+   +-------+--------+   |
+|          |                   |            |
+|          v                   v            |
+|  +-------+-------------------+--------+   |
+|  |                                    |   |
+|  |     Database Repository Layer     |   |
+|  |                                    |   |
+|  +------------------------------------+   |
+|                                           |
++-------------------------------------------+
+```
+
+**Components**:
+1. **{{COMPONENT}} Controller**: REST API endpoints
+2. **{{COMPONENT}} Service**: Business logic
+3. **{{COMPONENT}} Repository**: Data access
+
+---
+
+## Requirements Mapping
+
+### Architecture → Requirements Matrix
+
+| Component | Requirements Implemented | Design Rationale |
+|-----------|-------------------------|------------------|
+| {{COMPONENT}} Service | REQ-{{COMPONENT}}-001, REQ-{{COMPONENT}}-002 | Business logic encapsulation |
+| {{COMPONENT}} Controller | REQ-{{COMPONENT}}-003 | API exposure |
+| Database Schema | REQ-{{COMPONENT}}-004 | Data persistence |
+| Authentication Middleware | REQ-SEC-001 | Security enforcement |
+| Caching Layer | REQ-PERF-001 | Performance optimization |
+
+**Coverage**:
+- ✅ All functional requirements mapped
+- ✅ All non-functional requirements addressed
+- ✅ 100% requirements coverage
+
+---
+
+## API Design
+
+### RESTful API Endpoints
+
+#### POST /api/{{resource}}
+
+**Purpose**: [Create new resource]
+
+**Maps to Requirements**: REQ-{{COMPONENT}}-001
+
+**Request**:
+```http
+POST /api/{{resource}}
+Content-Type: application/json
+Authorization: Bearer {token}
+
+{
+  "field1": "value1",
+  "field2": "value2"
+}
+```
+
+**Request Schema**:
+```typescript
+interface CreateResourceRequest {
+  field1: string;  // Required, max 255 chars
+  field2: number;  // Required, positive integer
+}
+```
+
+**Response (Success)**:
+```http
+HTTP/1.1 201 Created
+Content-Type: application/json
+
+{
+  "id": "uuid",
+  "field1": "value1",
+  "field2": "value2",
+  "createdAt": "2025-11-16T10:00:00Z"
+}
+```
+
+**Response (Error)**:
+```http
+HTTP/1.1 400 Bad Request
+Content-Type: application/json
+
+{
+  "error": "Validation failed",
+  "details": [
+    {
+      "field": "field1",
+      "message": "Field1 is required"
+    }
+  ]
+}
+```
+
+**Status Codes**:
+- 201: Resource created successfully
+- 400: Invalid request (validation failed)
+- 401: Unauthorized (missing/invalid token)
+- 409: Conflict (resource already exists)
+- 500: Internal server error
+
+**Acceptance Criteria** (from REQ-{{COMPONENT}}-001):
+- ✅ Validates request schema
+- ✅ Returns 201 on success
+- ✅ Returns resource ID
+- ✅ Persists to database
+
+---
+
+#### GET /api/{{resource}}/:id
+
+**Purpose**: [Retrieve resource by ID]
+
+**Maps to Requirements**: REQ-{{COMPONENT}}-002
+
+**Request**:
+```http
+GET /api/{{resource}}/550e8400-e29b-41d4-a716-446655440000
+Authorization: Bearer {token}
+```
+
+**Response (Success)**:
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "field1": "value1",
+  "field2": "value2",
+  "createdAt": "2025-11-16T10:00:00Z",
+  "updatedAt": "2025-11-16T10:00:00Z"
+}
+```
+
+**Response (Not Found)**:
+```http
+HTTP/1.1 404 Not Found
+Content-Type: application/json
+
+{
+  "error": "Resource not found",
+  "id": "550e8400-e29b-41d4-a716-446655440000"
+}
+```
+
+**Status Codes**:
+- 200: Resource found
+- 401: Unauthorized
+- 404: Resource not found
+- 500: Internal server error
+
+---
+
+### OpenAPI Specification
+
+See [openapi.yaml](./openapi.yaml) for complete API specification.
+
+**Generation Command**:
+```bash
+# Generate OpenAPI spec
+@api-designer generate openapi for {{FEATURE_NAME}}
+```
+
+---
+
+## Database Design
+
+### Entity-Relationship Diagram
+
+```
++-------------------+          +-------------------+
+|      users        |          |   {{resource}}    |
++-------------------+          +-------------------+
+| id (PK)           |          | id (PK)           |
+| email             |          | user_id (FK)      |
+| password_hash     |          | field1            |
+| created_at        |          | field2            |
+| updated_at        |          | created_at        |
++-------------------+          | updated_at        |
+         |                     +-------------------+
+         |                              |
+         +------------------------------+
+                    1:N
+```
+
+---
+
+### Schema Definition
+
+#### Table: {{resource}}
+
+**Maps to Requirements**: REQ-{{COMPONENT}}-004
+
+**Columns**:
+
+| Column | Type | Constraints | Description |
+|--------|------|-------------|-------------|
+| id | UUID | PRIMARY KEY | Unique identifier |
+| user_id | UUID | FOREIGN KEY (users.id), NOT NULL | Owner reference |
+| field1 | VARCHAR(255) | NOT NULL | [Description] |
+| field2 | INTEGER | NOT NULL, CHECK (field2 > 0) | [Description] |
+| created_at | TIMESTAMP | NOT NULL, DEFAULT NOW() | Creation timestamp |
+| updated_at | TIMESTAMP | NOT NULL, DEFAULT NOW() | Update timestamp |
+
+**Indexes**:
+- PRIMARY KEY: `id`
+- INDEX: `user_id` (for lookups by user)
+- INDEX: `created_at` (for sorting)
+- UNIQUE: `user_id, field1` (business constraint)
+
+**DDL**:
+```sql
+CREATE TABLE {{resource}} (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  field1 VARCHAR(255) NOT NULL,
+  field2 INTEGER NOT NULL CHECK (field2 > 0),
+  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMP NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX idx_{{resource}}_user_id ON {{resource}}(user_id);
+CREATE INDEX idx_{{resource}}_created_at ON {{resource}}(created_at);
+CREATE UNIQUE INDEX idx_{{resource}}_user_field1 ON {{resource}}(user_id, field1);
+```
+
+---
+
+### Migration Strategy
+
+**Maps to Requirements**: REQ-MAINT-001
+
+**Initial Migration** (Greenfield):
+```sql
+-- migrations/001_create_{{resource}}_table.sql
+[DDL from above]
+```
+
+**Migration Tools**:
+- [e.g., Prisma Migrate, TypeORM migrations, Alembic]
+
+**Rollback Strategy**:
+```sql
+-- migrations/001_create_{{resource}}_table.down.sql
+DROP TABLE {{resource}};
+```
+
+---
+
+## Component Design
+
+### {{COMPONENT}} Service
+
+**Maps to Requirements**: REQ-{{COMPONENT}}-001, REQ-{{COMPONENT}}-002
+
+**Responsibilities**:
+- Business logic for {{resource}} operations
+- Validation
+- Error handling
+
+**Interface**:
+```typescript
+interface {{COMPONENT}}Service {
+  create(data: CreateResourceDTO): Promise<Resource>;
+  findById(id: string): Promise<Resource | null>;
+  update(id: string, data: UpdateResourceDTO): Promise<Resource>;
+  delete(id: string): Promise<void>;
+}
+```
+
+**Implementation**:
+```typescript
+// src/services/{{component}}.service.ts
+
+export class {{COMPONENT}}Service implements {{COMPONENT}}Service {
+  constructor(private repository: {{COMPONENT}}Repository) {}
+
+  async create(data: CreateResourceDTO): Promise<Resource> {
+    // REQ-{{COMPONENT}}-001: Validate input
+    this.validateCreateInput(data);
+
+    // REQ-{{COMPONENT}}-001: Check for duplicates
+    const existing = await this.repository.findByUserAndField1(
+      data.userId,
+      data.field1
+    );
+    if (existing) {
+      throw new ConflictError('Resource already exists');
+    }
+
+    // REQ-{{COMPONENT}}-001: Create resource
+    return this.repository.create(data);
+  }
+
+  // Additional methods...
+}
+```
+
+---
+
+### {{COMPONENT}} Repository
+
+**Maps to Requirements**: REQ-{{COMPONENT}}-004
+
+**Responsibilities**:
+- Data access layer
+- Database queries
+- Transaction management
+
+**Interface**:
+```typescript
+interface {{COMPONENT}}Repository {
+  create(data: CreateResourceDTO): Promise<Resource>;
+  findById(id: string): Promise<Resource | null>;
+  findByUserAndField1(userId: string, field1: string): Promise<Resource | null>;
+  update(id: string, data: UpdateResourceDTO): Promise<Resource>;
+  delete(id: string): Promise<void>;
+}
+```
+
+---
+
+## Integration Points
+
+### External API Integration
+
+**Service**: [External API Name]
+**Purpose**: [Integration purpose]
+**Maps to Requirements**: REQ-{{COMPONENT}}-005
+
+**Endpoint**: `https://api.external.com/v1/endpoint`
+**Authentication**: API Key in header
+**Rate Limit**: 1000 requests/hour
+
+**Request**:
+```http
+GET /v1/endpoint
+X-API-Key: {api_key}
+```
+
+**Error Handling**:
+- Retry with exponential backoff (3 attempts)
+- Circuit breaker after 5 consecutive failures
+- Fallback to cached data if available
+
+---
+
+## Security Design
+
+**Maps to Requirements**: REQ-SEC-001
+
+### Authentication
+
+- **Method**: JWT (JSON Web Tokens)
+- **Token Expiry**: 24 hours
+- **Refresh Token**: 7 days
+- **Storage**: HTTP-only cookies
+
+### Authorization
+
+- **Method**: Role-Based Access Control (RBAC)
+- **Roles**: admin, user, guest
+- **Permissions**: read, write, delete
+
+### Data Protection
+
+- **Encryption at Rest**: AES-256
+- **Encryption in Transit**: TLS 1.3
+- **Password Hashing**: bcrypt (cost factor 12)
+- **Sensitive Data**: PII encrypted in database
+
+### Input Validation
+
+- **XSS Prevention**: Output encoding
+- **SQL Injection Prevention**: Parameterized queries (ORM)
+- **CSRF Protection**: CSRF tokens
+- **Rate Limiting**: 100 requests/minute per IP
+
+---
+
+## Performance Design
+
+**Maps to Requirements**: REQ-PERF-001
+
+### Caching Strategy
+
+- **Layer**: Redis
+- **TTL**: 5 minutes
+- **Invalidation**: On write operations
+
+### Database Optimization
+
+- **Indexes**: See database schema section
+- **Connection Pooling**: 20 connections max
+- **Query Optimization**: N+1 prevention with eager loading
+
+### API Performance
+
+- **Response Time Target**: < 200ms (95th percentile)
+- **Pagination**: Limit 100 items per page
+- **Compression**: gzip for responses > 1KB
+
+---
+
+## Deployment Architecture
+
+**Maps to Requirements**: REQ-AVAIL-001
+
+### Infrastructure
+
+```
+[Load Balancer] --> [App Server 1]
+                --> [App Server 2]
+                --> [App Server 3]
+                        |
+                        v
+                  [Database Primary]
+                        |
+                        v
+                  [Database Replica]
+```
+
+### Containers
+
+**Docker Image**: `{{org}}/{{project}}:{{version}}`
+
+**Dockerfile**:
+```dockerfile
+FROM node:20-alpine
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --production
+COPY . .
+EXPOSE 3000
+CMD ["npm", "start"]
+```
+
+### Environment Variables
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| DATABASE_URL | PostgreSQL connection string | postgresql://user:pass@host:5432/db |
+| REDIS_URL | Redis connection string | redis://host:6379 |
+| JWT_SECRET | JWT signing secret | [secret] |
+| API_KEY | External API key | [key] |
+
+---
+
+## Monitoring and Observability
+
+**Maps to Requirements**: REQ-AVAIL-001
+
+### Metrics
+
+- **Response Time**: 95th/99th percentile
+- **Error Rate**: 4xx/5xx responses
+- **Throughput**: Requests per second
+- **Database Query Time**: Slow query log
+
+### Logging
+
+- **Format**: JSON
+- **Level**: INFO (production), DEBUG (development)
+- **Fields**: timestamp, level, message, context, trace_id
+
+### Alerting
+
+- **Response Time**: Alert if 95th percentile > 500ms
+- **Error Rate**: Alert if error rate > 1%
+- **Database**: Alert if connection pool exhausted
+
+---
+
+## Constitutional Compliance
+
+This design complies with:
+
+### Article I: Library-First Principle
+
+- ✅ {{COMPONENT}} implemented as library: `lib/{{component}}/`
+- ✅ Independent test suite: `lib/{{component}}/tests/`
+- ✅ CLI interface: `lib/{{component}}/cli.ts`
+
+### Article II: CLI Interface Mandate
+
+- ✅ CLI commands:
+  - `{{component}} create --field1=value --field2=value`
+  - `{{component}} get --id=uuid`
+  - `{{component}} list --user-id=uuid`
+
+### Article VI: Project Memory
+
+- ✅ Architecture aligns with `steering/structure.md`
+- ✅ Technology stack matches `steering/tech.md`
+- ✅ Product context from `steering/product.md`
+
+### Article VII: Simplicity Gate
+
+- ✅ Project count: [N] (≤ 3 or Phase -1 Gate approved)
+
+### Article VIII: Anti-Abstraction Gate
+
+- ✅ Framework APIs used directly (no custom wrappers)
+- OR
+- ⚠️ Custom abstraction requires Phase -1 Gate approval: [justification]
+
+---
+
+## Architecture Decision Records (ADR)
+
+### ADR-001: Use PostgreSQL for Database
+
+**Status**: Accepted
+**Date**: {{DATE}}
+
+**Context**:
+We need a database for storing {{resource}} data with ACID guarantees.
+
+**Decision**:
+Use PostgreSQL 15+ as the primary database.
+
+**Consequences**:
+- ✅ ACID transactions
+- ✅ Rich data types (JSONB, UUID)
+- ✅ Strong ecosystem
+- ❌ Requires relational schema design
+
+**Alternatives Considered**:
+- MongoDB: Rejected (ACID guarantees less strict)
+- MySQL: Rejected (less feature-rich than PostgreSQL)
+
+---
+
+### ADR-002: Use JWT for Authentication
+
+**Status**: Accepted
+**Date**: {{DATE}}
+
+**Context**:
+We need stateless authentication for API.
+
+**Decision**:
+Use JWT tokens stored in HTTP-only cookies.
+
+**Consequences**:
+- ✅ Stateless authentication
+- ✅ Scalable (no session storage)
+- ❌ Token revocation requires blocklist
+
+**Alternatives Considered**:
+- Session-based auth: Rejected (requires session storage)
+- OAuth 2.0: Deferred to future iteration
+
+---
+
+## Risk Assessment
+
+| Risk | Probability | Impact | Mitigation |
+|------|-------------|--------|------------|
+| Database performance degradation | Medium | High | Implement caching, indexing, monitoring |
+| External API unavailability | High | Medium | Circuit breaker, fallback to cache |
+| Security vulnerability | Low | Critical | Regular security audits, OWASP Top 10 |
+
+---
+
+## Open Questions
+
+- [ ] [Question 1]
+- [ ] [Question 2]
+
+---
+
+## References
+
+- [Requirements Specification](requirements.md)
+- [Steering Context](../../steering/)
+- [API Documentation](./api-docs.md)
+- [Database Schema](./schema.sql)
+
+---
+
+## Validation
+
+**Constitutional Validation**:
+```bash
+@constitution-enforcer validate design.md
+```
+
+**Requirements Coverage Validation**:
+```bash
+@traceability-auditor validate requirements.md design.md
+```
+
+---
+
+**Powered by MUSUBI** - Specification Driven Development