wicked-garden 12.27.0

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

@@ -0,0 +1,269 @@
+---
+phase_relevance: ["design", "build"]
+archetype_relevance: ["*"]
+---
+# Interface Documentation Template - Structure
+
+Template for documenting component interfaces, contracts, and integration points. Covers overview, contracts, operations, data types, error handling, and auth.
+
+## Template Structure
+
+```markdown
+# Interface Name
+
+## Overview
+
+Brief description of what this interface provides and who uses it.
+
+**Type**: [REST API | GraphQL | gRPC | Event Stream | Library]
+**Provider**: [Component Name]
+**Consumers**: [List of components that use this interface]
+**Stability**: [Stable | Beta | Experimental | Deprecated]
+
+## Contract
+
+### Purpose
+
+What problem does this interface solve? What functionality does it provide?
+
+### Guarantees
+
+What this interface guarantees to consumers:
+
+- Guarantee 1 (e.g., idempotency)
+- Guarantee 2 (e.g., response time)
+- Guarantee 3 (e.g., data consistency)
+
+### Assumptions
+
+What this interface assumes about consumers:
+
+- Assumption 1 (e.g., authentication)
+- Assumption 2 (e.g., rate limits respected)
+- Assumption 3 (e.g., proper error handling)
+
+## Operations
+
+### Operation 1: [Name]
+
+**Description**: What this operation does
+
+**Input**:
+```typescript
+interface Input {
+  field1: string;
+  field2: number;
+  field3?: boolean;  // Optional
+}
+```
+
+**Output**:
+```typescript
+interface Output {
+  result: string;
+  metadata: {
+    timestamp: string;
+    version: string;
+  };
+}
+```
+
+**Errors**:
+- `ERROR_CODE_1`: Description and recovery
+- `ERROR_CODE_2`: Description and recovery
+
+**Example**:
+```typescript
+const result = await interface.operation1({
+  field1: "value",
+  field2: 42,
+  field3: true
+});
+```
+
+**Performance**:
+- Expected latency: < 100ms
+- Throughput: 1000 ops/sec
+
+**Idempotency**: [Yes | No | Conditional]
+
+**Side Effects**: [None | List of side effects]
+
+### Operation 2: [Name]
+
+[Same structure]
+
+## Data Types
+
+### Type1
+
+```typescript
+interface Type1 {
+  id: string;
+  name: string;
+  status: 'active' | 'inactive' | 'pending';
+  metadata: Record<string, any>;
+  createdAt: Date;
+  updatedAt: Date;
+}
+```
+
+**Validation Rules**:
+- `id`: UUID format
+- `name`: 1-100 characters, alphanumeric
+- `status`: Must be one of allowed values
+
+**Invariants**:
+- `createdAt` <= `updatedAt`
+- `status` transitions follow workflow
+
+### Type2
+
+[Same structure]
+
+## Error Handling
+
+### Error Categories
+
+| Category | HTTP Status | Retry | Description |
+|----------|-------------|-------|-------------|
+| Validation | 400 | No | Invalid input |
+| Authentication | 401 | No | Missing/invalid auth |
+| Authorization | 403 | No | Insufficient permissions |
+| Not Found | 404 | No | Resource doesn't exist |
+| Conflict | 409 | No | State conflict |
+| Rate Limit | 429 | Yes | Too many requests |
+| Server Error | 500 | Yes | Internal error |
+| Unavailable | 503 | Yes | Service down |
+
+### Error Response Format
+
+```typescript
+interface ErrorResponse {
+  error: {
+    code: string;
+    message: string;
+    details?: any;
+    requestId: string;
+    timestamp: string;
+  };
+}
+```
+
+### Example Error
+
+```json
+{
+  "error": {
+    "code": "RESOURCE_NOT_FOUND",
+    "message": "User with ID 123 not found",
+    "requestId": "req_abc123",
+    "timestamp": "2025-01-24T10:00:00Z"
+  }
+}
+```
+
+## Authentication & Authorization
+
+### Authentication Method
+
+[Bearer Token | API Key | OAuth2 | mTLS | None]
+
+**Example**:
+```http
+Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
+```
+
+### Authorization
+
+**Required Permissions**:
+- `operation1`: `resource:read`
+- `operation2`: `resource:write`
+- `operation3`: `resource:admin`
+
+**Scopes**:
+- `read`: Read-only access
+- `write`: Create and update
+- `admin`: Full access including delete
+
+## Versioning
+
+**Current Version**: 2.1.0
+
+**Supported Versions**:
+- v1.x: Deprecated, sunset 2026-01-01
+- v2.x: Current, stable
+
+**Version Specification**:
+[URL | Header | Query Parameter]
+
+**Example**:
+```
+/api/v2/resources
+Accept: application/vnd.api.v2+json
+?version=2
+```
+
+### Breaking Changes
+
+Documented in [CHANGELOG.md](./CHANGELOG.md)
+
+**v2.0.0**:
+- Changed ID format from integer to UUID
+- Removed `description` field
+- Renamed `user_name` to `username`
+
+## Rate Limiting
+
+**Limits**:
+- Authenticated: 1000 requests/hour
+- Unauthenticated: 100 requests/hour
+- Burst: 20 requests/second
+
+**Headers**:
+```http
+X-RateLimit-Limit: 1000
+X-RateLimit-Remaining: 999
+X-RateLimit-Reset: 1611218400
+```
+
+**Exceeded Response**:
+```http
+HTTP/1.1 429 Too Many Requests
+Retry-After: 3600
+
+{
+  "error": {
+    "code": "RATE_LIMIT_EXCEEDED",
+    "message": "Rate limit exceeded",
+    "retryAfter": 3600
+  }
+}
+```
+
+## Service Level Agreement (SLA)
+
+**Availability**: 99.9% uptime
+
+**Performance**:
+- P50 latency: < 50ms
+- P95 latency: < 200ms
+- P99 latency: < 500ms
+
+**Support**:
+- Response time: 4 hours
+- Resolution time: 24 hours
+
+## Deprecation Policy
+
+1. **Announcement**: 6 months before deprecation
+2. **Warnings**: Deprecation headers in responses
+3. **Sunset**: Version removed after sunset date
+
+**Deprecation Headers**:
+```http
+Warning: 299 - "This API version is deprecated"
+Sunset: Mon, 01 Jan 2026 00:00:00 GMT
+Link: <https://docs.example.com/migration>; rel="deprecation"
+```
+```

package/skills/engineering/system-design/refs/patterns-dependency-injection.md

@@ -0,0 +1,151 @@
+---
+phase_relevance: ["design", "build"]
+archetype_relevance: ["*"]
+---
+# Component Design Patterns: Dependency Injection
+
+## Dependency Injection
+
+### Structure
+
+```
+┌──────────────┐
+│  Container   │
+└──────┬───────┘
+       │ Resolves
+       │
+┌──────▼──────────┐
+│    Service      │
+└──────┬──────────┘
+       │ Depends on
+       │
+┌──────▼──────────┐
+│   Dependency    │ (Injected)
+└─────────────────┘
+```
+
+### Example
+
+```typescript
+// Dependencies
+interface Logger {
+  log(message: string): void;
+}
+
+class ConsoleLogger implements Logger {
+  log(message: string): void {
+    console.log(message);
+  }
+}
+
+class FileLogger implements Logger {
+  constructor(private filename: string) {}
+
+  log(message: string): void {
+    fs.appendFileSync(this.filename, message + '\n');
+  }
+}
+
+// Service with dependencies
+class UserService {
+  constructor(
+    private userRepo: UserRepository,
+    private logger: Logger,
+    private emailService: EmailService
+  ) {}
+
+  async createUser(data: CreateUserDTO): Promise<User> {
+    this.logger.log(`Creating user: ${data.email}`);
+
+    const user = await this.userRepo.save(User.create(data));
+
+    await this.emailService.sendWelcome(user.email);
+
+    this.logger.log(`User created: ${user.id}`);
+
+    return user;
+  }
+}
+
+// DI Container
+class Container {
+  private services = new Map<string, any>();
+
+  register<T>(token: string, factory: () => T): void {
+    this.services.set(token, factory);
+  }
+
+  resolve<T>(token: string): T {
+    const factory = this.services.get(token);
+    if (!factory) {
+      throw new Error(`Service ${token} not registered`);
+    }
+    return factory();
+  }
+}
+
+// Setup
+const container = new Container();
+
+container.register<Logger>('Logger', () => new ConsoleLogger());
+container.register<UserRepository>('UserRepository', () => new PostgresUserRepository(db));
+container.register<EmailService>('EmailService', () => new EmailService());
+
+container.register<UserService>('UserService', () => {
+  return new UserService(
+    container.resolve('UserRepository'),
+    container.resolve('Logger'),
+    container.resolve('EmailService')
+  );
+});
+
+// Usage
+const userService = container.resolve<UserService>('UserService');
+await userService.createUser({ email: 'test@example.com', name: 'Test' });
+```
+
+### When to Use
+
+- Need loose coupling
+- Multiple implementations
+- Testability important
+- Configuration flexibility
+
+### Trade-offs
+
+**Pros**: Testable, flexible, decoupled
+**Cons**: Indirection, learning curve
+
+## Best Practices
+
+### 1. Single Responsibility
+
+Each component should have one reason to change.
+
+### 2. Interface Segregation
+
+Prefer many small interfaces over large ones.
+
+### 3. Dependency Inversion
+
+Depend on abstractions, not concretions.
+
+### 4. Composition over Inheritance
+
+Favor composing objects over class hierarchies.
+
+### 5. Keep It Simple
+
+Don't over-engineer. Start simple, refactor when needed.
+
+### 6. Document Patterns
+
+Make it clear which patterns are used and why.
+
+### 7. Consistent Structure
+
+Use consistent patterns across similar components.
+
+### 8. Test Boundaries
+
+Test component interfaces and contracts.

package/skills/engineering/system-design/refs/patterns-facade-pattern.md

@@ -0,0 +1,257 @@
+---
+phase_relevance: ["design", "build"]
+archetype_relevance: ["*"]
+---
+# Component Design Patterns: Facade Pattern
+
+## Facade Pattern
+
+### Structure
+
+```
+┌──────────┐
+│  Client  │
+└────┬─────┘
+     │
+     │ Simple Interface
+     │
+┌────▼────────────┐
+│     Facade      │
+└────┬────┬───┬───┘
+     │    │   │
+┌────▼┐ ┌─▼─┐ ┌▼────┐
+│Sub1 │ │S2 │ │ S3  │ (Complex Subsystems)
+└─────┘ └───┘ └─────┘
+```
+
+### Example
+
+```typescript
+// Complex Subsystems
+class PaymentProcessor {
+  async charge(amount: number, token: string): Promise<string> {
+    // Complex payment logic
+  }
+}
+
+class InventoryManager {
+  async reserve(productId: string, quantity: number): Promise<void> {
+    // Complex inventory logic
+  }
+
+  async release(productId: string, quantity: number): Promise<void> {
+    // Release reserved inventory
+  }
+}
+
+class ShippingService {
+  async createShipment(order: Order): Promise<string> {
+    // Complex shipping logic
+  }
+}
+
+class NotificationService {
+  async sendOrderConfirmation(userId: string, orderId: string): Promise<void> {
+    // Send notifications
+  }
+}
+
+// Facade - Simple Interface
+class OrderFacade {
+  constructor(
+    private payment: PaymentProcessor,
+    private inventory: InventoryManager,
+    private shipping: ShippingService,
+    private notifications: NotificationService
+  ) {}
+
+  async createOrder(request: CreateOrderRequest): Promise<Order> {
+    // Simple interface hiding complex workflow
+    try {
+      // Reserve inventory
+      for (const item of request.items) {
+        await this.inventory.reserve(item.productId, item.quantity);
+      }
+
+      // Process payment
+      const transactionId = await this.payment.charge(
+        request.total,
+        request.paymentToken
+      );
+
+      // Create order record
+      const order = await this.saveOrder({
+        ...request,
+        transactionId,
+        status: 'confirmed'
+      });
+
+      // Create shipment
+      await this.shipping.createShipment(order);
+
+      // Send confirmation
+      await this.notifications.sendOrderConfirmation(
+        request.userId,
+        order.id
+      );
+
+      return order;
+    } catch (error) {
+      // Rollback on failure
+      for (const item of request.items) {
+        await this.inventory.release(item.productId, item.quantity);
+      }
+      throw error;
+    }
+  }
+
+  private async saveOrder(data: any): Promise<Order> {
+    // Save order logic
+    return {} as Order;
+  }
+}
+
+// Client Usage
+const orderFacade = new OrderFacade(
+  paymentProcessor,
+  inventoryManager,
+  shippingService,
+  notificationService
+);
+
+// Simple call, complex workflow hidden
+const order = await orderFacade.createOrder({
+  userId: 'user123',
+  items: [{ productId: 'prod1', quantity: 2 }],
+  total: 99.99,
+  paymentToken: 'tok_123'
+});
+```
+
+### When to Use
+
+- Simplify complex subsystems
+- Provide unified interface
+- Reduce client dependencies
+- Hide implementation complexity
+
+### Trade-offs
+
+**Pros**: Simplified interface, loose coupling
+**Cons**: Can become a god object
+
+## Strategy Pattern
+
+### Structure
+
+```
+┌──────────┐
+│ Context  │
+└────┬─────┘
+     │
+     │ Uses
+     │
+┌────▼────────┐
+│  Strategy   │ (Interface)
+└────┬────────┘
+     │
+     │ Implements
+     │
+  ┌──┼────┬──────┐
+  │  │    │      │
+┌─▼┐ ┌▼─┐ ┌▼──┐ ┌▼─┐
+│S1│ │S2│ │S3 │ │S4│
+└──┘ └──┘ └───┘ └──┘
+```
+
+### Example
+
+```typescript
+// Strategy Interface
+interface PricingStrategy {
+  calculatePrice(basePrice: number, quantity: number): number;
+}
+
+// Concrete Strategies
+class RegularPricing implements PricingStrategy {
+  calculatePrice(basePrice: number, quantity: number): number {
+    return basePrice * quantity;
+  }
+}
+
+class BulkPricing implements PricingStrategy {
+  constructor(private discount: number) {}
+
+  calculatePrice(basePrice: number, quantity: number): number {
+    const subtotal = basePrice * quantity;
+    if (quantity >= 10) {
+      return subtotal * (1 - this.discount);
+    }
+    return subtotal;
+  }
+}
+
+class MemberPricing implements PricingStrategy {
+  constructor(private memberDiscount: number) {}
+
+  calculatePrice(basePrice: number, quantity: number): number {
+    return basePrice * quantity * (1 - this.memberDiscount);
+  }
+}
+
+class SeasonalPricing implements PricingStrategy {
+  constructor(private season: 'peak' | 'off-peak') {}
+
+  calculatePrice(basePrice: number, quantity: number): number {
+    const multiplier = this.season === 'peak' ? 1.2 : 0.8;
+    return basePrice * quantity * multiplier;
+  }
+}
+
+// Context
+class ShoppingCart {
+  private items: Array<{ productId: string; basePrice: number; quantity: number }> = [];
+
+  constructor(private pricingStrategy: PricingStrategy) {}
+
+  addItem(productId: string, basePrice: number, quantity: number): void {
+    this.items.push({ productId, basePrice, quantity });
+  }
+
+  getTotal(): number {
+    return this.items.reduce((total, item) => {
+      return total + this.pricingStrategy.calculatePrice(item.basePrice, item.quantity);
+    }, 0);
+  }
+
+  setPricingStrategy(strategy: PricingStrategy): void {
+    this.pricingStrategy = strategy;
+  }
+}
+
+// Usage
+const cart = new ShoppingCart(new RegularPricing());
+cart.addItem('prod1', 29.99, 5);
+console.log(cart.getTotal());  // Regular pricing
+
+// Switch to bulk pricing
+cart.setPricingStrategy(new BulkPricing(0.1));  // 10% discount
+console.log(cart.getTotal());  // Bulk pricing
+
+// Switch to member pricing
+cart.setPricingStrategy(new MemberPricing(0.15));  // 15% discount
+console.log(cart.getTotal());  // Member pricing
+```
+
+### When to Use
+
+- Multiple algorithms for same task
+- Runtime algorithm selection needed
+- Avoid large conditionals
+- Encapsulate varying behavior
+
+### Trade-offs
+
+**Pros**: Flexible, testable, follows Open/Closed
+**Cons**: More classes, client must know strategies
+