wicked-garden 12.27.0

package/skills/engineering/system-design/refs/dependencies-dependency-tracking.md

@@ -0,0 +1,261 @@
+---
+phase_relevance: ["design", "build"]
+archetype_relevance: ["*"]
+---
+# Dependency Management Guide: Dependency Tracking
+
+## Dependency Tracking
+
+### Dependency Matrix
+
+Track dependencies between components.
+
+| Component | Depends On |
+|-----------|------------|
+| UserController | UserService, AuthMiddleware |
+| UserService | UserRepository, EmailService |
+| OrderService | OrderRepository, UserService, PaymentService |
+| PaymentService | PaymentGateway, OrderRepository |
+
+### Dependency Metrics
+
+```typescript
+// Calculate coupling metrics
+function calculateAfferentCoupling(component: string): number {
+  // Number of components that depend on this component
+  return dependencies.filter(d => d.dependsOn === component).length;
+}
+
+function calculateEfferentCoupling(component: string): number {
+  // Number of components this component depends on
+  return dependencies.filter(d => d.component === component).length;
+}
+
+function calculateInstability(component: string): number {
+  const ce = calculateEfferentCoupling(component);
+  const ca = calculateAfferentCoupling(component);
+  // Instability = Ce / (Ce + Ca)
+  // 0 = maximally stable, 1 = maximally unstable
+  return ce / (ce + ca);
+}
+```
+
+## Anti-Patterns
+
+### 1. Circular Dependencies
+
+```typescript
+// Bad: Circular dependency
+class UserService {
+  constructor(private orderService: OrderService) {}
+}
+
+class OrderService {
+  constructor(private userService: UserService) {}
+}
+
+// Fix: Extract common logic or use events
+class UserService {
+  constructor(private eventBus: EventBus) {}
+
+  async createUser(data: UserData) {
+    const user = await this.saveUser(data);
+    this.eventBus.publish('user.created', { userId: user.id });
+    return user;
+  }
+}
+
+class OrderService {
+  constructor(private eventBus: EventBus) {
+    this.eventBus.subscribe('user.created', this.handleUserCreated);
+  }
+
+  private handleUserCreated = async (event: UserCreatedEvent) => {
+    // Initialize order data for new user
+  };
+}
+```
+
+### 2. God Object
+
+```typescript
+// Bad: God object with many dependencies
+class ApplicationService {
+  constructor(
+    private userRepo: UserRepository,
+    private orderRepo: OrderRepository,
+    private productRepo: ProductRepository,
+    private paymentService: PaymentService,
+    private emailService: EmailService,
+    private smsService: SMSService,
+    private notificationService: NotificationService,
+    private analyticsService: AnalyticsService,
+    private auditService: AuditService
+  ) {}
+}
+
+// Fix: Split into focused services
+class UserService {
+  constructor(
+    private userRepo: UserRepository,
+    private emailService: EmailService
+  ) {}
+}
+
+class OrderService {
+  constructor(
+    private orderRepo: OrderRepository,
+    private paymentService: PaymentService,
+    private notificationService: NotificationService
+  ) {}
+}
+```
+
+### 3. Hidden Dependencies
+
+```typescript
+// Bad: Hidden global dependency
+class UserService {
+  async getUser(id: string) {
+    return await globalDatabase.query('SELECT * FROM users WHERE id = $1', [id]);
+  }
+}
+
+// Fix: Explicit dependency
+class UserService {
+  constructor(private database: Database) {}
+
+  async getUser(id: string) {
+    return await this.database.query('SELECT * FROM users WHERE id = $1', [id]);
+  }
+}
+```
+
+### 4. Dependency on Unstable Components
+
+```typescript
+// Bad: Stable component depends on unstable component
+class DomainEntity {
+  constructor(private uiHelper: UIHelper) {}  // UI is unstable
+}
+
+// Fix: Invert dependency with abstraction
+interface Formatter {
+  format(value: any): string;
+}
+
+class DomainEntity {
+  constructor(private formatter: Formatter) {}
+}
+
+// UI implements the interface
+class UIFormatter implements Formatter {
+  format(value: any): string {
+    // UI-specific formatting
+  }
+}
+```
+
+### 5. Feature Envy
+
+```typescript
+// Bad: Component uses another's data extensively
+class OrderService {
+  async calculateTotal(order: Order): Promise<number> {
+    let total = 0;
+    for (const item of order.items) {
+      const product = await this.productRepo.findById(item.productId);
+      total += product.price * item.quantity;
+    }
+    return total;
+  }
+}
+
+// Fix: Move logic to data owner
+class Order {
+  calculateTotal(productPrices: Map<string, number>): number {
+    return this.items.reduce((total, item) => {
+      const price = productPrices.get(item.productId) || 0;
+      return total + (price * item.quantity);
+    }, 0);
+  }
+}
+```
+
+## Dependency Resolution Strategies
+
+### 1. Constructor Injection
+
+```typescript
+class UserService {
+  constructor(
+    private userRepo: UserRepository,
+    private emailService: EmailService
+  ) {}
+}
+
+// Wiring
+const userService = new UserService(userRepo, emailService);
+```
+
+**Pros**: Dependencies explicit, immutable
+**Cons**: Can lead to large constructors
+
+### 2. Property Injection
+
+```typescript
+class UserService {
+  userRepo: UserRepository;
+  emailService: EmailService;
+}
+
+// Wiring
+const userService = new UserService();
+userService.userRepo = userRepo;
+userService.emailService = emailService;
+```
+
+**Pros**: Optional dependencies
+**Cons**: Mutable, less explicit
+
+### 3. Method Injection
+
+```typescript
+class UserService {
+  async createUser(data: UserData, emailService: EmailService) {
+    const user = await this.saveUser(data);
+    await emailService.sendWelcome(user);
+    return user;
+  }
+}
+```
+
+**Pros**: Flexible, explicit per-call
+**Cons**: Verbose, repetitive
+
+### 4. Service Locator
+
+```typescript
+class ServiceLocator {
+  private services = new Map();
+
+  register<T>(name: string, instance: T): void {
+    this.services.set(name, instance);
+  }
+
+  resolve<T>(name: string): T {
+    return this.services.get(name);
+  }
+}
+
+class UserService {
+  async createUser(data: UserData) {
+    const emailService = ServiceLocator.resolve<EmailService>('EmailService');
+    await emailService.sendWelcome(data.email);
+  }
+}
+```
+
+**Pros**: Decoupled
+**Cons**: Hidden dependencies, testing harder
+

package/skills/engineering/system-design/refs/interface-template-lifecycle.md

@@ -0,0 +1,211 @@
+---
+phase_relevance: ["design", "build"]
+archetype_relevance: ["*"]
+---
+# Interface Documentation Template - Operations
+
+Testing, examples, client libraries, monitoring, migration guides, and changelog.
+
+## Testing
+
+### Contract Tests
+
+```typescript
+describe('Interface Contract', () => {
+  it('should return correct response format', async () => {
+    const response = await api.operation1({
+      field1: "test",
+      field2: 42
+    });
+
+    expect(response).toHaveProperty('result');
+    expect(response).toHaveProperty('metadata');
+    expect(response.metadata).toHaveProperty('timestamp');
+  });
+
+  it('should handle not found error', async () => {
+    await expect(
+      api.operation1({ field1: "nonexistent", field2: 999 })
+    ).rejects.toMatchObject({
+      code: 'RESOURCE_NOT_FOUND',
+      status: 404
+    });
+  });
+});
+```
+
+### Performance Tests
+
+```typescript
+describe('Performance', () => {
+  it('should respond within 200ms', async () => {
+    const start = Date.now();
+    await api.operation1({ field1: "test", field2: 42 });
+    const duration = Date.now() - start;
+
+    expect(duration).toBeLessThan(200);
+  });
+});
+```
+
+## Examples
+
+### Basic Usage
+
+```typescript
+import { APIClient } from '@example/api-client';
+
+const client = new APIClient({
+  apiKey: process.env.API_KEY,
+  baseURL: 'https://api.example.com'
+});
+
+// Create resource
+const resource = await client.createResource({
+  name: "My Resource",
+  status: "active"
+});
+
+console.log(resource.id);  // "550e8400-e29b-41d4-a716-446655440000"
+```
+
+### Error Handling
+
+```typescript
+try {
+  const resource = await client.getResource(id);
+} catch (error) {
+  if (error.code === 'RESOURCE_NOT_FOUND') {
+    console.log('Resource not found');
+  } else if (error.code === 'RATE_LIMIT_EXCEEDED') {
+    const retryAfter = error.retryAfter;
+    await sleep(retryAfter * 1000);
+    // Retry...
+  } else {
+    throw error;
+  }
+}
+```
+
+### Pagination
+
+```typescript
+let hasMore = true;
+let offset = 0;
+
+while (hasMore) {
+  const response = await client.listResources({
+    limit: 100,
+    offset
+  });
+
+  process(response.data);
+
+  hasMore = response.pagination.hasMore;
+  offset += 100;
+}
+```
+
+## Client Libraries
+
+**Official Clients**:
+- JavaScript/TypeScript: `@example/api-client`
+- Python: `example-api-client`
+- Go: `github.com/example/api-client-go`
+
+**Community Clients**:
+- Ruby: `example-api` (not officially supported)
+- Java: `com.example.api-client` (not officially supported)
+
+## Monitoring
+
+### Metrics
+
+Provider should expose:
+```
+interface_requests_total{operation, status}
+interface_request_duration_seconds{operation}
+interface_errors_total{operation, error_code}
+```
+
+Consumer should track:
+```
+interface_client_requests_total{operation, status}
+interface_client_errors_total{operation, error_code}
+interface_circuit_breaker_state{state}
+```
+
+### Health Check
+
+```http
+GET /health
+
+Response: 200 OK
+{
+  "status": "healthy",
+  "version": "2.1.0",
+  "uptime": 3600
+}
+```
+
+## Migration Guide
+
+### Migrating from v1 to v2
+
+**Breaking Changes**:
+
+1. **ID Format Change**
+   ```typescript
+   // v1
+   const id: number = 123;
+
+   // v2
+   const id: string = "550e8400-e29b-41d4-a716-446655440000";
+   ```
+
+2. **Field Rename**
+   ```typescript
+   // v1
+   const name = resource.user_name;
+
+   // v2
+   const name = resource.username;
+   ```
+
+**Step-by-Step**:
+
+1. Update client library to v2-compatible version
+2. Update ID handling in your code
+3. Update field names
+4. Test thoroughly
+5. Deploy
+6. Monitor for errors
+
+## Changelog
+
+### v2.1.0 (2025-01-20)
+
+**Added**:
+- Bulk operations
+- Filtering by status
+
+**Fixed**:
+- Race condition in concurrent updates
+
+### v2.0.0 (2024-12-01)
+
+**Breaking Changes**:
+- Changed ID format to UUID
+- Removed `description` field
+
+**Added**:
+- Pagination support
+- Rate limiting
+
+## Support
+
+**Documentation**: https://docs.example.com/api
+**Status Page**: https://status.example.com
+**Support Email**: api-support@example.com
+**Slack**: #api-support
+```

package/skills/engineering/system-design/refs/interface-template-maintenance.md

@@ -0,0 +1,212 @@
+---
+phase_relevance: ["design", "build"]
+archetype_relevance: ["*"]
+---
+# Interface Documentation Template - Examples and Tips
+
+Complete User Service interface example and tips for documenting interfaces.
+
+## Example: User Service Interface
+
+```markdown
+# User Service Interface
+
+## Overview
+
+Provides user management operations for all platform services.
+
+**Type**: REST API
+**Provider**: user-service
+**Consumers**: auth-service, order-service, notification-service
+**Stability**: Stable
+
+## Contract
+
+### Purpose
+
+Centralized user data management and profile operations.
+
+### Guarantees
+
+- User IDs are unique and immutable
+- Email addresses are unique across the system
+- Responses include all non-sensitive user fields
+- Operations are idempotent where applicable
+
+### Assumptions
+
+- Caller is authenticated and authorized
+- Email addresses are validated before submission
+- Rate limits are respected
+
+## Operations
+
+### GetUser
+
+**Description**: Retrieve user by ID
+
+**Input**:
+```typescript
+interface GetUserRequest {
+  userId: string;  // UUID format
+}
+```
+
+**Output**:
+```typescript
+interface User {
+  id: string;
+  email: string;
+  name: string;
+  role: 'admin' | 'user' | 'guest';
+  status: 'active' | 'suspended' | 'deleted';
+  createdAt: string;  // ISO 8601
+  updatedAt: string;  // ISO 8601
+}
+```
+
+**Errors**:
+- `USER_NOT_FOUND` (404): User with given ID doesn't exist
+- `UNAUTHORIZED` (401): Invalid or missing auth token
+- `FORBIDDEN` (403): Insufficient permissions
+
+**Example**:
+```http
+GET /api/users/550e8400-e29b-41d4-a716-446655440000
+Authorization: Bearer <token>
+
+Response: 200 OK
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "email": "alice@example.com",
+  "name": "Alice Smith",
+  "role": "user",
+  "status": "active",
+  "createdAt": "2025-01-24T10:00:00Z",
+  "updatedAt": "2025-01-24T10:00:00Z"
+}
+```
+
+**Performance**: P95 < 50ms
+**Idempotency**: Yes
+**Side Effects**: None
+
+### CreateUser
+
+**Description**: Create a new user account
+
+**Input**:
+```typescript
+interface CreateUserRequest {
+  email: string;        // Valid email, unique
+  name: string;         // 1-100 characters
+  password: string;     // Min 8 characters
+  role?: 'admin' | 'user' | 'guest';  // Default: 'user'
+}
+```
+
+**Output**:
+```typescript
+interface CreateUserResponse {
+  user: User;
+}
+```
+
+**Errors**:
+- `DUPLICATE_EMAIL` (409): Email already exists
+- `VALIDATION_ERROR` (400): Invalid input
+- `WEAK_PASSWORD` (400): Password doesn't meet requirements
+
+**Example**:
+```http
+POST /api/users
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "email": "bob@example.com",
+  "name": "Bob Jones",
+  "password": "SecurePass123!"
+}
+
+Response: 201 Created
+Location: /api/users/660e8400-e29b-41d4-a716-446655440000
+{
+  "user": {
+    "id": "660e8400-e29b-41d4-a716-446655440000",
+    "email": "bob@example.com",
+    "name": "Bob Jones",
+    "role": "user",
+    "status": "active",
+    "createdAt": "2025-01-24T10:05:00Z",
+    "updatedAt": "2025-01-24T10:05:00Z"
+  }
+}
+```
+
+**Performance**: P95 < 200ms
+**Idempotency**: No (generates new ID each time)
+**Side Effects**:
+- Publishes `user.created` event
+- Sends welcome email
+
+## Authentication & Authorization
+
+### Authentication
+
+Bearer token required for all endpoints:
+```http
+Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
+```
+
+### Authorization
+
+| Operation | Required Permission |
+|-----------|-------------------|
+| GetUser | `user:read` (own) or `user:read:all` (any) |
+| CreateUser | `user:create` |
+| UpdateUser | `user:write` (own) or `user:write:all` (any) |
+| DeleteUser | `user:delete` |
+
+## Service Level Agreement (SLA)
+
+**Availability**: 99.9%
+
+**Performance**:
+- GET operations: P95 < 50ms
+- POST/PUT operations: P95 < 200ms
+
+**Support**:
+- Response time: 2 hours
+- Resolution time: 8 hours
+
+## Client Library Example
+
+```typescript
+import { UserServiceClient } from '@example/user-service-client';
+
+const client = new UserServiceClient({
+  baseURL: 'https://api.example.com',
+  apiKey: process.env.API_KEY
+});
+
+// Get user
+const user = await client.getUser('550e8400-...');
+
+// Create user
+const newUser = await client.createUser({
+  email: 'new@example.com',
+  name: 'New User',
+  password: 'SecurePass123!'
+});
+```
+```
+
+## Tips for Documenting Interfaces
+
+1. **Be Explicit**: Don't assume consumers understand context
+2. **Show Examples**: Real request/response examples
+3. **Document Errors**: All possible error conditions
+4. **Version Everything**: Track changes over time
+5. **Performance Targets**: Set clear expectations
+6. **Keep Updated**: Interface docs should match implementation