@wipal/agent-team 1.0.0

package/.claude/skills/domain/architecture/architecture-patterns/references/serverless.md

@@ -0,0 +1,457 @@
+# Serverless Architecture
+
+## Overview
+Serverless is a cloud execution model where the cloud provider dynamically manages infrastructure allocation and scaling. You focus on code, not servers.
+
+## Core Concepts
+
+### What "Serverless" Really Means
+```
+Not "no servers" but "no server management":
+
+Traditional:                    Serverless:
+┌─────────────────────┐        ┌─────────────────────┐
+│ Your Responsibility │        │ Your Responsibility │
+├─────────────────────┤        ├─────────────────────┤
+│ - Application code  │        │ - Application code  │
+│ - Runtime           │        │ - Function logic    │
+│ - OS updates        │        │                     │
+│ - Server patching   │        │                     │
+│ - Scaling           │        │                     │
+│ - High availability │        │                     │
+└─────────────────────┘        └─────────────────────┘
+
+Cloud Provider handles:
+- Server provisioning
+- OS management
+- Scaling (auto)
+- High availability
+- Security patching
+```
+
+## Serverless Components
+
+### 1. Function as a Service (FaaS)
+```
+┌─────────────────────────────────────────────┐
+│              Lambda / Function              │
+├─────────────────────────────────────────────┤
+│ - Event-triggered execution                │
+│ - Stateless                                │
+│ - Short-lived (15 min max typically)       │
+│ - Pay per invocation + execution time      │
+└─────────────────────────────────────────────┘
+
+Triggers:
+- HTTP requests (API Gateway)
+- Database changes (DynamoDB Streams)
+- File uploads (S3)
+- Messages (SQS, SNS, EventBridge)
+- Scheduled (CloudWatch Events)
+- Custom events
+```
+
+### 2. Backend as a Service (BaaS)
+```
+Managed Services (no code needed):
+
+┌──────────────┐ ┌──────────────┐ ┌──────────────┐
+│   Database   │ │   Storage    │ │   Auth       │
+│ (DynamoDB,   │ │ (S3, Blob    │ │ (Cognito,    │
+│  Firestore)  │ │  Storage)    │ │  Auth0)      │
+└──────────────┘ └──────────────┘ └──────────────┘
+
+┌──────────────┐ ┌──────────────┐ ┌──────────────┐
+│   Queue      │ │   Cache      │ │   Search     │
+│ (SQS, Pub/Sub│ │ (ElastiCache,│ │ (Elasticsearch│
+│  Service Bus)│ │  Redis Cloud)│ │  Cloud Search)│
+└──────────────┘ └──────────────┘ └──────────────┘
+```
+
+## Architecture Patterns
+
+### 1. API Backend
+```
+┌─────────┐     ┌─────────────┐     ┌─────────────┐
+│ Client  │────▶│ API Gateway │────▶│  Lambda     │
+│ (Web/   │     │             │     │  Function   │
+│  Mobile)│     │             │     └──────┬──────┘
+└─────────┘     └─────────────┘            │
+                                           ▼
+                                    ┌─────────────┐
+                                    │  DynamoDB   │
+                                    └─────────────┘
+
+Flow:
+1. Client makes HTTP request
+2. API Gateway routes to Lambda
+3. Lambda processes, reads/writes DB
+4. Response returned
+
+Cost: Pay per API call + Lambda execution
+```
+
+### 2. Event Processing
+```
+┌─────────┐     ┌─────────────┐     ┌─────────────┐
+│ S3      │────▶│   Lambda    │────▶│   SNS       │
+│ Upload  │     │ (resize)    │     │(notify)     │
+└─────────┘     └─────────────┘     └─────────────┘
+                      │
+                      ▼
+               ┌─────────────┐
+               │ S3 (thumb)  │
+               └─────────────┘
+
+Flow:
+1. Image uploaded to S3
+2. S3 triggers Lambda
+3. Lambda creates thumbnail
+4. Stores in another S3 bucket
+5. Sends notification
+```
+
+### 3. Data Pipeline
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│ Kinesis/    │────▶│   Lambda    │────▶│   Redshift/ │
+│ EventBridge │     │ (transform) │     │   S3        │
+└─────────────┘     └─────────────┘     └─────────────┘
+
+Flow:
+1. Events stream in
+2. Lambda transforms data
+3. Loads to data warehouse
+```
+
+### 4. Chatbot / Webhook
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│ Slack/Teams │────▶│ API Gateway │────▶│   Lambda    │
+│ Webhook     │     │             │     │             │
+└─────────────┘     └─────────────┘     └──────┬──────┘
+                                               │
+                                               ▼
+                                        ┌─────────────┐
+                                        │ Third-party │
+                                        │    API      │
+                                        └─────────────┘
+```
+
+## Provider Comparison
+
+### Major Providers
+```
+┌──────────────┬────────────────┬────────────────┬────────────────┐
+│   Feature    │   AWS Lambda   │ Azure Functions │ Google Cloud   │
+├──────────────┼────────────────┼────────────────┼────────────────┤
+│ Max runtime  │ 15 minutes     │ 10 minutes     │ 9 minutes      │
+│ Memory       │ 128MB - 10GB   │ 128MB - 1.5GB  │ 128MB - 32GB   │
+│ Cold start   │ 100-500ms      │ 100-300ms      │ 100-300ms      │
+│ Triggers     │ 20+ services   │ 15+ services   │ 15+ services   │
+│ Languages    │ Node, Python,  │ C#, Node,      │ Node, Python,  │
+│              │ Java, Go, C#   │ Python, Java   │ Go, Java       │
+└──────────────┴────────────────┴────────────────┴────────────────┘
+```
+
+### Cold Starts
+```
+Why cold starts happen:
+1. No warm instances available
+2. New container needs to be created
+3. Runtime initialized
+4. Function code loaded
+5. Handler executed
+
+Cold start times:
+- Node.js: 100-200ms
+- Python: 100-300ms
+- Java: 500-2000ms
+- .NET: 500-1500ms
+
+Mitigation:
+- Provisioned concurrency (keep warm)
+- Smaller deployment packages
+- Choose faster runtime
+- Connection pooling
+```
+
+## Best Practices
+
+### 1. Function Design
+```
+DO:
+✅ Single responsibility
+✅ Stateless functions
+✅ Idempotent operations
+✅ Quick execution (< 5 seconds ideal)
+✅ Handle retries gracefully
+
+DON'T:
+❌ Long-running processes
+❌ Stateful logic
+❌ Heavy initialization
+❌ Synchronous external calls (if avoidable)
+❌ Large dependencies
+```
+
+### 2. Cold Start Optimization
+```
+1. Minimize dependencies:
+   - Use tree-shaking
+   - Only import what you need
+   - Consider bundle size
+
+2. Lazy loading:
+   const heavyLib = null;
+
+   export const handler = async (event) => {
+     if (!heavyLib) {
+       heavyLib = await import('heavy-library');
+     }
+     // ...
+   };
+
+3. Connection reuse:
+   // Outside handler - reused across invocations
+   const db = new DatabaseClient();
+
+   export const handler = async (event) => {
+     return db.query(...);
+   };
+
+4. Provisioned concurrency:
+   - Pre-warmed instances
+   - Pay for reserved capacity
+   - Use for latency-sensitive functions
+```
+
+### 3. Error Handling
+```
+Structued error handling:
+
+export const handler = async (event) => {
+   try {
+     const result = await processEvent(event);
+     return {
+       statusCode: 200,
+       body: JSON.stringify(result)
+     };
+   } catch (error) {
+     console.error('Error:', error);
+
+     // DLQ for failed events
+     if (error.isRetryable) {
+       throw error; // Will retry
+     }
+
+     return {
+       statusCode: 500,
+       body: JSON.stringify({
+         error: error.message,
+         requestId: event.requestContext.requestId
+       })
+     };
+   }
+ };
+```
+
+### 4. Security
+```
+1. Least privilege IAM:
+   - Function-specific roles
+   - Minimum required permissions
+   - No wildcard permissions
+
+2. Secrets management:
+   - Use Secrets Manager / Parameter Store
+   - Never hardcode secrets
+   - Rotate credentials
+
+3. VPC configuration:
+   - Place in VPC if accessing private resources
+   - Use VPC endpoints for AWS services
+   - Consider NAT gateway costs
+
+4. Input validation:
+   - Validate all inputs
+   - Sanitize user data
+   - Rate limiting at API Gateway
+```
+
+## Cost Optimization
+
+### Pricing Model
+```
+AWS Lambda example:
+- Request price: $0.20 per 1M requests
+- Duration price: $0.00001667 per GB-second
+
+Monthly cost calculation:
+- 1M requests/month
+- 256MB memory
+- 100ms average duration
+
+Cost = (1M × $0.20/1M) + (1M × 0.1s × 0.25GB × $0.00001667)
+     = $0.20 + $0.42
+     = $0.62/month
+
+vs EC2 t3.micro (always on): ~$8.50/month
+```
+
+### Cost Optimization Tips
+```
+1. Right-size memory:
+   - More memory = faster execution
+   - Test different configurations
+   - Find cost/performance sweet spot
+
+2. Optimize duration:
+   - Faster code = less cost
+   - Cache expensive operations
+   - Minimize cold starts
+
+3. Reduce requests:
+   - Batch processing
+   - Combine functions
+   - Use caching at API Gateway
+
+4. Free tier awareness:
+   - AWS: 1M requests + 400K GB-seconds/month free
+   - Monitor usage
+```
+
+## Limitations & Challenges
+
+### Technical Limitations
+```
+1. Execution time:
+   - AWS Lambda: 15 minutes max
+   - Not for long-running jobs
+
+2. Memory:
+   - AWS Lambda: 128MB - 10GB
+   - Limited for memory-intensive tasks
+
+3. Deployment size:
+   - AWS Lambda: 250MB (unzipped)
+   - Large dependencies problematic
+
+4. Cold starts:
+   - Latency spikes
+   - Not ideal for real-time apps
+
+5. Vendor lock-in:
+   - Provider-specific APIs
+   - Migration challenges
+```
+
+### Operational Challenges
+```
+1. Debugging:
+   - Distributed tracing needed
+   - Local testing differs from production
+   - Limited visibility
+
+2. Monitoring:
+   - Need specialized tools
+   - Multiple data sources
+   - Complex alerting
+
+3. Testing:
+   - Local emulation imperfect
+   - Integration testing complex
+   - End-to-end testing challenging
+```
+
+## When to Use Serverless
+
+### ✅ Best Use Cases
+```
+- Variable/unpredictable traffic
+- Event-driven processing
+- API backends for mobile/web
+- Scheduled tasks
+- Data transformation pipelines
+- Chatbots and webhooks
+- File processing
+- Quick prototypes and MVPs
+```
+
+### ❌ Avoid Serverless For
+```
+- Long-running processes (> 15 min)
+- Consistent, high traffic (EC2 cheaper)
+- Real-time/gaming applications
+- Complex state management
+- Predictable workload (reserved instances)
+- Heavy computational tasks
+- Strict latency requirements (< 100ms)
+```
+
+## Serverless Frameworks
+
+### Infrastructure as Code
+```
+1. AWS SAM (Serverless Application Model):
+   - AWS-native
+   - YAML-based
+   - Good for AWS-only projects
+
+2. Serverless Framework:
+   - Multi-cloud
+   - YAML-based
+   - Large plugin ecosystem
+
+3. Terraform:
+   - Multi-cloud
+   - HCL language
+   - Full infrastructure management
+
+4. AWS CDK:
+   - AWS-native
+   - TypeScript/Python/Java
+   - Programmatic infrastructure
+```
+
+### Example: Serverless Framework
+```yaml
+# serverless.yml
+service: my-api
+
+provider:
+  name: aws
+  runtime: nodejs18.x
+  region: us-east-1
+
+functions:
+  getUser:
+    handler: src/handlers/getUser.handler
+    events:
+      - http:
+          path: users/{id}
+          method: get
+    environment:
+      TABLE_NAME: ${self:service}-users
+
+resources:
+  Resources:
+    UsersTable:
+      Type: AWS::DynamoDB::Table
+      Properties:
+        TableName: ${self:service}-users
+        BillingMode: PAY_PER_REQUEST
+        AttributeDefinitions:
+          - AttributeName: id
+            AttributeType: S
+        KeySchema:
+          - AttributeName: id
+            KeyType: HASH
+```
+
+## Further Reading
+
+- "Serverless Architectures on AWS" - Peter Sbarski
+- AWS Serverless Application Lens
+- serverless.com/learn
+- AWS Well-Architected Serverless Lens

package/.claude/skills/domain/architecture/performance-engineering/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: performance-engineering
+description: |
+  Use when optimizing system performance, designing caching strategies,
+  or planning for scalability. Covers caching, optimization techniques,
+  and performance testing.
+version: 1.0.0
+category: performance
+tags:
+  - performance
+  - caching
+  - optimization
+  - benchmarking
+dependencies:
+  - system-design
+references:
+  - references/caching-strategies.md
+  - references/optimization.md
+  - references/benchmarking.md
+---
+
+# Performance Engineering
+
+## Core Principle
+**Measure first, optimize what matters, trade-off consciously.**
+
+## When to Use This Skill
+
+### Trigger Conditions
+- System performance issues
+- Capacity planning
+- Caching strategy design
+- Performance optimization
+- Load testing
+
+### Keywords
+- "performance"
+- "optimization"
+- "caching"
+- "latency"
+- "throughput"
+- "load testing"
+
+## Performance Metrics
+
+### Key Metrics (USE/RED)
+```
+USE Method (Resources):
+- Utilization: % busy
+- Saturation: Queue length
+- Errors: Error count
+
+RED Method (Services):
+- Rate: Requests/second
+- Errors: Failed requests/second
+- Duration: Latency distribution (p50, p95, p99)
+```
+
+### Latency Percentiles
+```
+p50 (median): 50% of requests faster than this
+p95: 95% of requests faster than this
+p99: 99% of requests faster than this
+
+Example:
+p50: 100ms - Most users see this
+p95: 250ms - 5% see slower
+p99: 500ms - 1% see slower (often problematic queries)
+
+Target: Focus on p95/p99 for user experience
+```
+
+## Caching Strategies
+
+### Cache Locations
+```
+┌─────────┐     ┌─────────┐     ┌─────────┐     ┌─────────┐
+│ Browser │────▶│   CDN   │────▶│  Load   │────▶│   App   │
+│  Cache  │     │  Cache  │     │Balancer │     │  Cache  │
+└─────────┘     └─────────┘     └─────────┘     └────┬────┘
+                                                     │
+                                                ┌────┴────┐
+                                                │Database │
+                                                │  Cache  │
+                                                └─────────┘
+```
+
+### Caching Patterns
+```
+1. Cache-Aside (Lazy Load)
+   - Check cache first
+   - On miss, load from DB
+   - Populate cache
+   - Return data
+
+2. Write-Through
+   - Write to cache AND DB
+   - Always consistent
+   - Higher write latency
+
+3. Write-Behind
+   - Write to cache
+   - Async write to DB
+   - Risk of data loss
+
+4. Refresh-Ahead
+   - Pre-refresh before expiry
+   - Good for predictable access
+```
+
+## Optimization Techniques
+
+### Application Level
+```
+1. Database Queries
+   - Use indexes effectively
+   - Avoid N+1 queries
+   - Use connection pooling
+   - Query optimization
+
+2. Code Optimization
+   - Algorithm efficiency
+   - Memory management
+   - Avoid premature optimization
+   - Profile before optimizing
+
+3. Concurrency
+   - Async/await patterns
+   - Thread pools
+   - Non-blocking I/O
+```
+
+### Infrastructure Level
+```
+1. Horizontal Scaling
+   - Add more instances
+   - Load balance
+
+2. Vertical Scaling
+   - More CPU/RAM
+   - Faster storage
+
+3. CDN
+   - Static assets
+   - Edge caching
+   - Geographic distribution
+```
+
+## Performance Testing
+
+### Types of Tests
+```
+1. Load Testing
+   - Expected load
+   - Normal conditions
+
+2. Stress Testing
+   - Beyond capacity
+   - Find breaking point
+
+3. Spike Testing
+   - Sudden traffic increase
+   - Auto-scaling validation
+
+4. Soak Testing
+   - Extended period
+   - Memory leaks, resource exhaustion
+```
+
+### Testing Tools
+```
+- k6: Modern load testing
+- JMeter: Feature-rich, Java-based
+- Locust: Python-based
+- Artillery: Node.js based
+- Gatling: Scala-based, high performance
+```
+
+## Performance Checklist
+
+### Frontend
+- [ ] Minimize HTTP requests
+- [ ] Enable compression (gzip/brotli)
+- [ ] Optimize images
+- [ ] Use CDN
+- [ ] Minify CSS/JS
+- [ ] Lazy loading
+- [ ] Code splitting
+
+### Backend
+- [ ] Database indexing
+- [ ] Query optimization
+- [ ] Connection pooling
+- [ ] Caching implemented
+- [ ] Async processing
+- [ ] Rate limiting
+
+### Infrastructure
+- [ ] Load balancing
+- [ ] Auto-scaling
+- [ ] Monitoring & alerting
+- [ ] CDN configuration
+- [ ] SSL termination
+
+## Output
+
+When optimizing performance:
+1. **Performance Report** - Current metrics, bottlenecks
+2. **Optimization Plan** - Prioritized improvements
+3. **Before/After Metrics** - Measured impact
+4. **ADR** - Significant performance decisions
+
+## Rules
+
+### DO
+- ✅ Measure before optimizing
+- ✅ Focus on bottlenecks
+- ✅ Set performance targets
+- ✅ Monitor continuously
+- ✅ Test at production scale
+
+### DON'T
+- ❌ Premature optimization
+- ❌ Optimize without profiling
+- ❌ Ignore trade-offs
+- ❌ Skip load testing
+- ❌ Trust benchmarks blindly