vibes-plug 1.0.0

package/skills/fullstack-expert/references/system_design_patterns.md

@@ -0,0 +1,358 @@
+# System Design Patterns
+
+## Overview
+This reference documents production-grade system design patterns for fullstack expert architects. Covers distributed systems, event-driven architectures, and scalable microservice topologies.
+
+---
+
+## 1. Microservices Communication Patterns
+
+### Synchronous: API Gateway + Service Mesh
+
+Use an API Gateway (Kong, AWS API Gateway, Envoy) as the single entry point. Behind it, services communicate via gRPC for internal calls (binary protocol, code-gen, strict contracts).
+
+```
+┌──────────────┐
+│   Client      │
+└──────┬───────┘
+       │ HTTPS
+┌──────▼───────┐
+│  API Gateway  │  (Rate limiting, Auth, Routing)
+└──────┬───────┘
+       │ gRPC / HTTP
+  ┌────┼────┐
+  ▼    ▼    ▼
+┌───┐┌───┐┌───┐
+│Svc││Svc││Svc│
+│ A ││ B ││ C │
+└─┬─┘└─┬─┘└─┬─┘
+  │    │    │
+  ▼    ▼    ▼
+┌───────────────┐
+│  Database(s)  │
+└───────────────┘
+```
+
+### Asynchronous: Event-Driven Architecture (EDA)
+
+For decoupled, resilient communication:
+
+```typescript
+// Producer: Order Service (TypeScript + BullMQ)
+import { Queue } from 'bullmq';
+import IORedis from 'ioredis';
+
+const connection = new IORedis(process.env.REDIS_URL!);
+const orderEventsQueue = new Queue('OrderEvents', { connection });
+
+export async function publishOrderCreated(order: Order) {
+  await orderEventsQueue.add('order.created', {
+    orderId: order.id,
+    userId: order.userId,
+    total: order.total,
+    items: order.items,
+    timestamp: new Date().toISOString(),
+  }, {
+    attempts: 5,
+    backoff: { type: 'exponential', delay: 3000 },
+    removeOnComplete: { age: 86400 }, // Keep completed jobs for 24h
+  });
+}
+```
+
+```typescript
+// Consumer: Notification Service (TypeScript + BullMQ Worker)
+import { Worker, Job } from 'bullmq';
+import IORedis from 'ioredis';
+
+const connection = new IORedis(process.env.REDIS_URL!);
+
+const notificationWorker = new Worker(
+  'OrderEvents',
+  async (job: Job) => {
+    switch (job.name) {
+      case 'order.created':
+        await sendOrderConfirmationEmail(job.data);
+        await sendPushNotification(job.data.userId, 'Order confirmed!');
+        break;
+      case 'order.shipped':
+        await sendShippingNotification(job.data);
+        break;
+    }
+  },
+  { connection, concurrency: 5 }
+);
+```
+
+---
+
+## 2. Saga Pattern for Distributed Transactions
+
+When a business operation spans multiple services, use the Saga pattern (choreography or orchestration) instead of distributed 2PC.
+
+### Orchestrator-Based Saga
+
+```typescript
+// Saga Orchestrator (TypeScript)
+interface SagaStep<T> {
+  name: string;
+  execute: (context: T) => Promise<void>;
+  compensate: (context: T) => Promise<void>;
+}
+
+class SagaOrchestrator<T> {
+  private steps: SagaStep<T>[] = [];
+  private completedSteps: SagaStep<T>[] = [];
+
+  addStep(step: SagaStep<T>): this {
+    this.steps.push(step);
+    return this;
+  }
+
+  async execute(context: T): Promise<void> {
+    for (const step of this.steps) {
+      try {
+        console.log(`▶ Executing: ${step.name}`);
+        await step.execute(context);
+        this.completedSteps.push(step);
+      } catch (error) {
+        console.error(`✗ Failed at: ${step.name}`, error);
+        await this.rollback(context);
+        throw new SagaFailedError(step.name, error);
+      }
+    }
+  }
+
+  private async rollback(context: T): Promise<void> {
+    // Compensate in reverse order
+    for (const step of [...this.completedSteps].reverse()) {
+      try {
+        console.log(`↩ Compensating: ${step.name}`);
+        await step.compensate(context);
+      } catch (error) {
+        console.error(`⚠ Compensation failed: ${step.name}`, error);
+        // Log to dead letter queue for manual intervention
+      }
+    }
+  }
+}
+
+// Usage: Order Creation Saga
+const orderSaga = new SagaOrchestrator<OrderContext>()
+  .addStep({
+    name: 'Reserve Inventory',
+    execute: async (ctx) => await inventoryService.reserve(ctx.items),
+    compensate: async (ctx) => await inventoryService.release(ctx.items),
+  })
+  .addStep({
+    name: 'Process Payment',
+    execute: async (ctx) => await paymentService.charge(ctx.paymentMethod, ctx.total),
+    compensate: async (ctx) => await paymentService.refund(ctx.paymentId),
+  })
+  .addStep({
+    name: 'Create Order Record',
+    execute: async (ctx) => await orderService.create(ctx),
+    compensate: async (ctx) => await orderService.cancel(ctx.orderId),
+  });
+```
+
+---
+
+## 3. CQRS (Command Query Responsibility Segregation)
+
+Separate write models (commands) from read models (queries) when read/write patterns differ significantly.
+
+```
+┌─────────────┐    ┌─────────────┐
+│  Write API   │    │  Read API    │
+│  (Commands)  │    │  (Queries)   │
+└──────┬──────┘    └──────┬──────┘
+       │                  │
+       ▼                  ▼
+┌─────────────┐    ┌─────────────┐
+│  Write DB    │──▶│  Read DB     │
+│ (PostgreSQL) │    │   (Redis /   │
+│ Normalized   │    │  Elasticsearch)
+└─────────────┘    └─────────────┘
+       │
+       ▼  (Domain Events)
+┌─────────────┐
+│  Event Bus   │
+│  (Kafka)     │
+└─────────────┘
+```
+
+```typescript
+// Write side: Command Handler
+async function handleCreateProduct(cmd: CreateProductCommand): Promise<string> {
+  // Validate business rules
+  const product = Product.create(cmd);
+
+  // Persist to write store
+  await db.insert(products).values(product.toRow());
+
+  // Publish domain event for read model projection
+  await eventBus.publish('product.created', {
+    id: product.id,
+    name: product.name,
+    price: product.price,
+    category: product.category,
+  });
+
+  return product.id;
+}
+
+// Read side: Event Projector
+eventBus.subscribe('product.created', async (event) => {
+  // Project into denormalized read model optimized for queries
+  await redis.hset(`product:${event.id}`, {
+    ...event,
+    searchText: `${event.name} ${event.category}`.toLowerCase(),
+  });
+
+  // Also index in Elasticsearch for full-text search
+  await esClient.index({
+    index: 'products',
+    id: event.id,
+    body: event,
+  });
+});
+```
+
+---
+
+## 4. Circuit Breaker Pattern
+
+Prevent cascading failures in distributed systems by wrapping external service calls with circuit breakers.
+
+```typescript
+// Circuit Breaker Implementation (TypeScript)
+enum CircuitState {
+  CLOSED = 'CLOSED',     // Normal operation
+  OPEN = 'OPEN',         // Failing, reject calls
+  HALF_OPEN = 'HALF_OPEN' // Testing recovery
+}
+
+class CircuitBreaker {
+  private state = CircuitState.CLOSED;
+  private failureCount = 0;
+  private lastFailureTime = 0;
+
+  constructor(
+    private readonly name: string,
+    private readonly threshold: number = 5,
+    private readonly resetTimeoutMs: number = 30000,
+  ) {}
+
+  async call<T>(fn: () => Promise<T>): Promise<T> {
+    if (this.state === CircuitState.OPEN) {
+      if (Date.now() - this.lastFailureTime > this.resetTimeoutMs) {
+        this.state = CircuitState.HALF_OPEN;
+      } else {
+        throw new CircuitOpenError(`Circuit ${this.name} is OPEN`);
+      }
+    }
+
+    try {
+      const result = await fn();
+      this.onSuccess();
+      return result;
+    } catch (error) {
+      this.onFailure();
+      throw error;
+    }
+  }
+
+  private onSuccess(): void {
+    this.failureCount = 0;
+    this.state = CircuitState.CLOSED;
+  }
+
+  private onFailure(): void {
+    this.failureCount++;
+    this.lastFailureTime = Date.now();
+    if (this.failureCount >= this.threshold) {
+      this.state = CircuitState.OPEN;
+      console.warn(`⚡ Circuit ${this.name} opened after ${this.failureCount} failures`);
+    }
+  }
+}
+
+// Usage
+const paymentCircuit = new CircuitBreaker('payment-service', 5, 30000);
+
+async function processPayment(order: Order) {
+  return paymentCircuit.call(() =>
+    fetch('https://payment-api.example.com/charge', {
+      method: 'POST',
+      body: JSON.stringify({ amount: order.total }),
+    })
+  );
+}
+```
+
+---
+
+## 5. Service Discovery & Load Balancing
+
+### DNS-Based (Kubernetes)
+
+```yaml
+# Kubernetes Service (ClusterIP) for internal discovery
+apiVersion: v1
+kind: Service
+metadata:
+  name: user-service
+  namespace: production
+spec:
+  selector:
+    app: user-service
+  ports:
+    - port: 80
+      targetPort: 3000
+  type: ClusterIP
+---
+# HorizontalPodAutoscaler for dynamic scaling
+apiVersion: autoscaling/v2
+kind: HorizontalPodAutoscaler
+metadata:
+  name: user-service-hpa
+spec:
+  scaleTargetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: user-service
+  minReplicas: 2
+  maxReplicas: 10
+  metrics:
+    - type: Resource
+      resource:
+        name: cpu
+        target:
+          type: Utilization
+          averageUtilization: 70
+    - type: Resource
+      resource:
+        name: memory
+        target:
+          type: Utilization
+          averageUtilization: 80
+```
+
+---
+
+## Anti-Patterns to Avoid
+
+### 🚫 Distributed Monolith
+Don't create microservices that are tightly coupled and must be deployed together. If services can't be deployed independently, they're a distributed monolith — worse than a proper monolith.
+
+### 🚫 Shared Database Between Services
+Each service should own its data store. Cross-service data access should happen via APIs or events, never direct database queries.
+
+### 🚫 Synchronous Call Chains
+Avoid long chains of synchronous HTTP calls (`A → B → C → D`). Each hop adds latency and a failure point. Use async messaging for non-critical paths.
+
+---
+
+## Conclusion
+Choosing the right system design patterns depends on your scale, team size, and consistency requirements. Start with a modular monolith and extract services only when you have clear domain boundaries and operational maturity.

package/skills/fullstack-expert/scripts/api_contract_validator.py

@@ -0,0 +1,253 @@
+#!/usr/bin/env python3
+"""
+API Contract Validator
+Validates API contracts (OpenAPI specs) and checks for best practices.
+"""
+
+import os
+import sys
+import json
+import argparse
+from pathlib import Path
+from typing import Dict, List, Optional
+
+
+class ApiContractValidator:
+    """Validates OpenAPI specs and API route files for best practices."""
+
+    def __init__(self, target_path: str, verbose: bool = False):
+        self.target_path = Path(target_path)
+        self.verbose = verbose
+        self.results: Dict = {
+            'status': 'pending',
+            'target': str(self.target_path),
+            'findings': [],
+            'api_routes': [],
+            'score': 100,
+        }
+
+    def run(self) -> Dict:
+        """Execute the API contract validation."""
+        print(f"📋 Running API Contract Validator...")
+        print(f"📁 Target: {self.target_path}")
+
+        try:
+            self.validate_target()
+            self.scan_api_routes()
+            self.check_openapi_spec()
+            self.check_validation_schemas()
+            self.check_error_handling()
+            self.check_authentication()
+            self.check_rate_limiting()
+            self.generate_report()
+
+            self.results['status'] = 'success'
+            print("✅ Validation completed!")
+            return self.results
+
+        except Exception as e:
+            print(f"❌ Error: {e}")
+            sys.exit(1)
+
+    def validate_target(self):
+        """Validate the target path exists."""
+        if not self.target_path.exists():
+            raise ValueError(f"Target path does not exist: {self.target_path}")
+
+    def scan_api_routes(self):
+        """Scan for API route definitions."""
+        api_dirs = [
+            'app/api', 'src/routes', 'src/api', 'routes',
+            'internal/handler', 'src/handlers',
+        ]
+        route_files = []
+
+        for api_dir in api_dirs:
+            dir_path = self.target_path / api_dir
+            if dir_path.is_dir():
+                for f in dir_path.rglob('*'):
+                    if f.is_file() and f.suffix in {'.ts', '.tsx', '.js', '.py', '.go', '.rs'}:
+                        route_files.append(str(f.relative_to(self.target_path)))
+
+        self.results['api_routes'] = route_files
+        if self.verbose:
+            print(f"✓ Found {len(route_files)} API route files")
+
+        if not route_files:
+            self._add_finding('info', 'No API routes found in standard directories')
+
+    def check_openapi_spec(self):
+        """Check for OpenAPI specification file."""
+        spec_files = ['openapi.yaml', 'openapi.yml', 'openapi.json', 'swagger.yaml', 'swagger.json']
+        has_spec = any((self.target_path / f).exists() for f in spec_files)
+
+        # Also check in docs/ or api/ directories
+        for subdir in ['docs', 'api', 'spec']:
+            if (self.target_path / subdir).is_dir():
+                has_spec = has_spec or any(
+                    (self.target_path / subdir / f).exists() for f in spec_files
+                )
+
+        if not has_spec and self.results['api_routes']:
+            self._add_finding('warning', 'No OpenAPI spec found — consider spec-first API design')
+            self.results['score'] -= 10
+
+    def check_validation_schemas(self):
+        """Check for input validation schemas (Zod, Pydantic, etc.)."""
+        validation_patterns = ['zod', 'pydantic', 'joi', 'yup', 'class-validator']
+        has_validation = False
+
+        pkg_json = self.target_path / 'package.json'
+        if pkg_json.exists():
+            try:
+                with open(pkg_json) as f:
+                    pkg = json.load(f)
+                deps = {**pkg.get('dependencies', {}), **pkg.get('devDependencies', {})}
+                has_validation = any(v in deps for v in validation_patterns)
+            except (json.JSONDecodeError, IOError):
+                pass
+
+        # Check Python
+        pyproject = self.target_path / 'pyproject.toml'
+        if pyproject.exists():
+            try:
+                content = pyproject.read_text()
+                has_validation = has_validation or 'pydantic' in content
+            except IOError:
+                pass
+
+        if not has_validation and self.results['api_routes']:
+            self._add_finding('warning', 'No input validation library detected (Zod, Pydantic, etc.)')
+            self.results['score'] -= 15
+
+    def check_error_handling(self):
+        """Check for structured error handling patterns."""
+        error_files = []
+        for pattern in ['**/error*.ts', '**/error*.py', '**/error*.go', '**/error*.rs']:
+            error_files.extend(self.target_path.glob(pattern))
+
+        if not error_files and self.results['api_routes']:
+            self._add_finding('info', 'No dedicated error handling module found — consider structured error responses (RFC 7807)')
+
+    def check_authentication(self):
+        """Check for authentication middleware setup."""
+        auth_indicators = ['auth', 'jwt', 'clerk', 'nextauth', 'lucia', 'passport']
+        has_auth = False
+
+        pkg_json = self.target_path / 'package.json'
+        if pkg_json.exists():
+            try:
+                with open(pkg_json) as f:
+                    pkg = json.load(f)
+                deps = {**pkg.get('dependencies', {}), **pkg.get('devDependencies', {})}
+                has_auth = any(
+                    any(indicator in dep for indicator in auth_indicators)
+                    for dep in deps
+                )
+            except (json.JSONDecodeError, IOError):
+                pass
+
+        if not has_auth and self.results['api_routes']:
+            self._add_finding('info', 'No authentication library detected — ensure API endpoints are protected')
+
+    def check_rate_limiting(self):
+        """Check for rate limiting setup."""
+        rate_limit_deps = ['rate-limit', 'ratelimit', 'limiter', 'throttle']
+        has_rate_limit = False
+
+        pkg_json = self.target_path / 'package.json'
+        if pkg_json.exists():
+            try:
+                with open(pkg_json) as f:
+                    pkg = json.load(f)
+                deps = {**pkg.get('dependencies', {}), **pkg.get('devDependencies', {})}
+                has_rate_limit = any(
+                    any(rl in dep for rl in rate_limit_deps)
+                    for dep in deps
+                )
+            except (json.JSONDecodeError, IOError):
+                pass
+
+        if not has_rate_limit and self.results['api_routes']:
+            self._add_finding('warning', 'No rate limiting detected — protect API endpoints from abuse')
+            self.results['score'] -= 5
+
+    def _add_finding(self, severity: str, message: str):
+        """Add a finding to the results."""
+        self.results['findings'].append({
+            'severity': severity,
+            'message': message,
+        })
+        if self.verbose:
+            icon = {'critical': '🔴', 'warning': '🟡', 'info': '🔵'}.get(severity, '⚪')
+            print(f"  {icon} [{severity.upper()}] {message}")
+
+    def generate_report(self):
+        """Generate and display the validation report."""
+        findings = self.results['findings']
+        critical = len([f for f in findings if f['severity'] == 'critical'])
+        warnings = len([f for f in findings if f['severity'] == 'warning'])
+        info = len([f for f in findings if f['severity'] == 'info'])
+
+        score = max(0, self.results['score'])
+        self.results['score'] = score
+
+        print(f"\n{'='*60}")
+        print("📋 API CONTRACT VALIDATION REPORT")
+        print(f"{'='*60}")
+        print(f"Target:     {self.results['target']}")
+        print(f"Score:      {score}/100")
+        print(f"API Routes: {len(self.results['api_routes'])} files found")
+        print(f"Findings:   {critical} critical, {warnings} warnings, {info} info")
+        print(f"\nFindings:")
+        for f in findings:
+            icon = {'critical': '🔴', 'warning': '🟡', 'info': '🔵'}.get(f['severity'], '⚪')
+            print(f"  {icon} [{f['severity'].upper()}] {f['message']}")
+        print(f"{'='*60}\n")
+
+
+def main():
+    """Main entry point."""
+    parser = argparse.ArgumentParser(
+        description="API Contract Validator — validates API design best practices"
+    )
+    parser.add_argument(
+        'target',
+        help='Target project path to validate'
+    )
+    parser.add_argument(
+        '--verbose', '-v',
+        action='store_true',
+        help='Enable verbose output'
+    )
+    parser.add_argument(
+        '--json',
+        action='store_true',
+        help='Output results as JSON'
+    )
+    parser.add_argument(
+        '--output', '-o',
+        help='Output file path'
+    )
+
+    args = parser.parse_args()
+
+    validator = ApiContractValidator(
+        args.target,
+        verbose=args.verbose
+    )
+
+    results = validator.run()
+
+    if args.json:
+        output = json.dumps(results, indent=2)
+        if args.output:
+            with open(args.output, 'w') as f:
+                f.write(output)
+            print(f"Results written to {args.output}")
+        else:
+            print(output)
+
+
+if __name__ == '__main__':
+    main()