moai-adk 0.8.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-domain-backend/reference.md

@@ -1,660 +1,464 @@
-# Backend Architecture Reference
-
-## Architecture Decision Matrix
-
-### When to Choose Each Pattern
-
-| Pattern | Team Size | Complexity | Deployment | Scaling | Use Cases |
-|---------|-----------|------------|------------|---------|-----------|
-| **Layered Monolith** | 1-5 | Low-Medium | Simple | Vertical | MVPs, startups, internal tools |
-| **Modular Monolith** | 5-15 | Medium | Simple | Vertical | Growing products, clear domains |
-| **Microservices** | 15+ | High | Complex | Horizontal | Large-scale, multi-team, polyglot |
-| **Serverless** | Any | Low-Medium | Managed | Auto | Event-driven, spiky traffic, rapid prototyping |
-| **Event-Driven** | 10+ | High | Complex | Horizontal | Real-time analytics, decoupled systems, audit logs |
-
-### Decision Criteria
-
-**Choose Layered Monolith when**:
-- Small team (1-5 developers)
-- Rapid prototyping phase
-- Simple deployment requirements
-- Limited operational expertise
-- Cost-sensitive project
-
-**Choose Modular Monolith when**:
-- Growing team (5-15 developers)
-- Clear domain boundaries emerging
-- Need independent module development
-- Want extraction path to microservices
-- Prefer simple deployment
-
-**Choose Microservices when**:
-- Large team (15+ developers)
-- Multiple independent products/teams
-- Polyglot technology requirements
-- Need independent scaling per service
-- High operational maturity (Kubernetes, Istio)
-
-**Choose Serverless when**:
-- Event-driven workloads
-- Spiky or unpredictable traffic
-- Want zero infrastructure management
-- Cost optimization for low usage
-- Rapid feature iteration
-
-**Choose Event-Driven when**:
-- Real-time data processing
-- Audit logging requirements
-- Decoupled system integration
-- Complex business workflows
-- Need event replay capability
+# Backend Development Reference
 
-## Cloud-Native Tool Comparison
-
-### Container Orchestration
-
-| Tool | Complexity | Ecosystem | Scaling | Multi-cloud | Production Ready |
-|------|------------|-----------|---------|-------------|------------------|
-| **Kubernetes 1.31.x** | High | Massive | Excellent | Yes | Yes |
-| **Docker Swarm** | Low | Limited | Good | Partial | Yes |
-| **AWS ECS** | Medium | AWS only | Good | No | Yes |
-| **Nomad** | Medium | HashiCorp | Good | Yes | Yes |
-
-**Recommendation**: Kubernetes 1.31.x for production, Docker Compose for local dev.
-
-### Service Mesh
-
-| Tool | Complexity | Features | Performance | Maturity |
-|------|------------|----------|-------------|----------|
-| **Istio 1.21.x** | High | Comprehensive | Good | Mature |
-| **Linkerd 2.14.x** | Low | Core features | Excellent | Mature |
-| **Consul Connect** | Medium | Full stack | Good | Mature |
-| **AWS App Mesh** | Medium | AWS native | Good | Growing |
-
-**Recommendation**: Istio 1.21.x for full features, Linkerd for simplicity.
-
-### Message Brokers
-
-| Tool | Throughput | Durability | Ordering | Complexity | Use Case |
-|------|------------|------------|----------|------------|----------|
-| **Apache Kafka 3.7.x** | Very High | Excellent | Partition | High | Event streaming, logs |
-| **RabbitMQ 3.13.x** | High | Good | Queue | Medium | Task queues, RPC |
-| **Redis Streams 7.2.x** | Very High | Good | Stream | Low | Real-time, lightweight |
-| **Amazon SQS** | Medium | Excellent | Best-effort | Low | Serverless, AWS |
-| **NATS 2.10.x** | Very High | Good | Stream | Low | Microservices messaging |
-| **Apache Pulsar 3.2.x** | Very High | Excellent | Partition | High | Multi-tenancy, geo-replication |
-
-**Recommendation**: Kafka 3.7.x for event streaming, RabbitMQ 3.13.x for task queues, NATS for lightweight microservices messaging.
-
-### Observability Stack Comparison
-
-| Stack | Traces | Metrics | Logs | Complexity | Cost |
-|-------|--------|---------|------|------------|------|
-| **OpenTelemetry + Prometheus + Jaeger + ELK** | Yes | Yes | Yes | High | OSS |
-| **Datadog** | Yes | Yes | Yes | Low | High |
-| **New Relic** | Yes | Yes | Yes | Low | High |
-| **AWS X-Ray + CloudWatch** | Yes | Yes | Yes | Medium | Medium |
-| **Grafana Cloud** | Yes | Yes | Yes | Low | Medium |
-
-**Recommendation**: OpenTelemetry 1.24.0 + Prometheus 2.48.x + Jaeger 1.51.x for vendor-neutral OSS stack.
-
-### Database Selection Matrix
+## API Reference
 
-| Database | Type | Scalability | Consistency | Query Flexibility | Use Case |
-|----------|------|-------------|-------------|-------------------|----------|
-| **PostgreSQL 16.x** | SQL | Vertical + Read Replicas | Strong ACID | SQL + JSONB | Relational, complex queries |
-| **MongoDB 8.0.x** | Document | Horizontal (Sharding) | Tunable | Flexible schema | Rapid prototyping, catalogs |
-| **Redis 7.2.x** | Key-Value | Horizontal (Cluster) | Eventual | Limited | Caching, sessions, pub/sub |
-| **Cassandra 4.1.x** | Wide-Column | Horizontal | Tunable | CQL | Time-series, write-heavy |
-
-**Recommendation**: PostgreSQL 16.x as default, MongoDB 8.0.x for schema flexibility.
-
-## Deployment Strategies
-
-### Blue-Green Deployment
-
-**Pattern**:
-- Two identical production environments (Blue = current, Green = new)
-- Switch traffic after validation
-- Instant rollback capability
-
-**Pros**:
-- Zero downtime
-- Easy rollback
-- Full validation before switch
-
-**Cons**:
-- Double infrastructure cost
-- Data migration complexity
-- Requires load balancer
+### FastAPI Application Setup
 
-**Best for**: Critical services with infrequent releases.
-
-### Canary Deployment
-
-**Pattern**:
-- Gradually shift traffic to new version (5% → 25% → 50% → 100%)
-- Monitor metrics at each stage
-- Auto-rollback on errors
-
-**Pros**:
-- Risk mitigation
-- Real-world testing
-- Minimal infrastructure duplication
-
-**Cons**:
-- Requires advanced routing (Istio)
-- Longer deployment time
-- Version compatibility required
-
-**Best for**: User-facing services with high traffic.
-
-**Istio 1.21.x Implementation**:
-```yaml
-apiVersion: networking.istio.io/v1beta1
-kind: VirtualService
-metadata:
-  name: backend-canary
-spec:
-  hosts:
-  - backend.example.com
-  http:
-  - match:
-    - headers:
-        x-canary:
-          exact: "true"
-    route:
-    - destination:
-        host: backend
-        subset: v2
-  - route:
-    - destination:
-        host: backend
-        subset: v1
-      weight: 90
-    - destination:
-        host: backend
-        subset: v2
-      weight: 10
+Complete application structure:
+```python
+from fastapi import FastAPI, Depends, HTTPException, status
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.security import OAuth2PasswordBearer
+from contextlib import asynccontextmanager
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Startup
+    await database.connect()
+    await cache.connect()
+    yield
+    # Shutdown
+    await database.disconnect()
+    await cache.disconnect()
+
+app = FastAPI(
+    title="API Service",
+    version="2.0.0",
+    lifespan=lifespan,
+    docs_url="/docs",
+    redoc_url="/redoc",
+    openapi_url="/openapi.json"
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
 ```
 
-### Rolling Update
-
-**Pattern**:
-- Incrementally replace instances (pod-by-pod)
-- Kubernetes default strategy
-- Health checks control rollout
-
-**Pros**:
-- Built-in Kubernetes support
-- No extra infrastructure
-- Automatic rollback on failure
-
-**Cons**:
-- Version compatibility required
-- Slower than blue-green
-- Mixed versions during rollout
+### Database Connection Patterns
 
-**Best for**: Standard microservices deployments.
-
-**Kubernetes Configuration**:
-```yaml
-spec:
-  replicas: 10
-  strategy:
-    type: RollingUpdate
-    rollingUpdate:
-      maxSurge: 2
-      maxUnavailable: 1
+SQLAlchemy Async Engine:
+```python
+from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
+from sqlalchemy.orm import sessionmaker
+
+DATABASE_URL = "postgresql+asyncpg://user:pass@localhost/db"
+
+engine = create_async_engine(
+    DATABASE_URL,
+    pool_size=20,
+    max_overflow=30,
+    pool_pre_ping=True,
+    pool_recycle=3600,
+    echo=False
+)
+
+async_session = sessionmaker(
+    engine, class_=AsyncSession, expire_on_commit=False
+)
+
+async def get_db():
+    async with async_session() as session:
+        try:
+            yield session
+            await session.commit()
+        except Exception:
+            await session.rollback()
+            raise
 ```
 
-### A/B Testing (Feature Flags)
-
-**Pattern**:
-- Route users to different features based on criteria
-- Measure business metrics
-- Gradual feature rollout
-
-**Pros**:
-- Business metric validation
-- User segmentation
-- Independent of deployment
-
-**Cons**:
-- Code complexity (feature flags)
-- Requires analytics
-- Technical debt if not cleaned
-
-**Best for**: Product experiments, new features.
-
-**Tools**: LaunchDarkly, Split.io, Unleash, AWS AppConfig.
-
-## Monitoring and Observability Setup
-
-### OpenTelemetry 1.24.0 Integration
-
-**Step 1: Instrument Application**:
+Motor (MongoDB) Connection:
 ```python
-from opentelemetry import trace
-from opentelemetry.sdk.trace import TracerProvider
-from opentelemetry.sdk.trace.export import BatchSpanProcessor
-from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
+from motor.motor_asyncio import AsyncIOMotorClient
 
-trace.set_tracer_provider(TracerProvider())
-tracer = trace.get_tracer(__name__)
+MONGODB_URL = "mongodb://localhost:27017"
 
-otlp_exporter = OTLPSpanExporter(endpoint="otel-collector:4317")
-span_processor = BatchSpanProcessor(otlp_exporter)
-trace.get_tracer_provider().add_span_processor(span_processor)
-```
+client = AsyncIOMotorClient(
+    MONGODB_URL,
+    maxPoolSize=50,
+    minPoolSize=10,
+    maxIdleTimeMS=50000,
+    waitQueueTimeoutMS=5000
+)
 
-**Step 2: Deploy Collector**:
-```yaml
-apiVersion: apps/v1
-kind: Deployment
-metadata:
-  name: otel-collector
-spec:
-  template:
-    spec:
-      containers:
-      - name: otel-collector
-        image: otel/opentelemetry-collector:0.92.0
-        ports:
-        - containerPort: 4317  # OTLP gRPC
-        - containerPort: 4318  # OTLP HTTP
-```
+db = client.myapp
 
-**Step 3: Configure Backends**:
-```yaml
-# otel-collector-config.yaml
-receivers:
-  otlp:
-    protocols:
-      grpc:
-      http:
-
-processors:
-  batch:
-
-exporters:
-  prometheus:
-    endpoint: "0.0.0.0:8889"
-  jaeger:
-    endpoint: "jaeger:14250"
-  elasticsearch:
-    endpoints: ["http://elasticsearch:9200"]
-
-service:
-  pipelines:
-    traces:
-      receivers: [otlp]
-      processors: [batch]
-      exporters: [jaeger]
-    metrics:
-      receivers: [otlp]
-      processors: [batch]
-      exporters: [prometheus]
-    logs:
-      receivers: [otlp]
-      processors: [batch]
-      exporters: [elasticsearch]
+async def get_mongodb():
+    return db
 ```
 
-### Prometheus 2.48.x Setup
+Redis Connection:
+```python
+import redis.asyncio as redis
 
-**Step 1: Install Prometheus Operator**:
-```bash
-helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
-helm install prometheus prometheus-community/kube-prometheus-stack \
-  --set prometheus.prometheusSpec.retention=30d \
-  --set prometheus.prometheusSpec.storageSpec.volumeClaimTemplate.spec.resources.requests.storage=50Gi
-```
+REDIS_URL = "redis://localhost:6379"
 
-**Step 2: ServiceMonitor for Application**:
-```yaml
-apiVersion: monitoring.coreos.com/v1
-kind: ServiceMonitor
-metadata:
-  name: backend-metrics
-spec:
-  selector:
-    matchLabels:
-      app: backend
-  endpoints:
-  - port: metrics
-    interval: 15s
-```
+redis_pool = redis.ConnectionPool.from_url(
+    REDIS_URL,
+    max_connections=50,
+    decode_responses=True
+)
 
-**Step 3: Alerting Rules**:
-```yaml
-apiVersion: monitoring.coreos.com/v1
-kind: PrometheusRule
-metadata:
-  name: backend-alerts
-spec:
-  groups:
-  - name: backend
-    interval: 30s
-    rules:
-    - alert: HighErrorRate
-      expr: rate(http_requests_total{status=~"5.."}[5m]) > 0.05
-      for: 5m
-      labels:
-        severity: critical
-      annotations:
-        summary: "High error rate detected"
+async def get_redis():
+    return redis.Redis(connection_pool=redis_pool)
 ```
 
-### Jaeger 1.51.x Deployment
+### Authentication Middleware
 
-**All-in-One (Development)**:
-```bash
-kubectl create deployment jaeger --image=jaegertracing/all-in-one:1.51
-kubectl expose deployment jaeger --port=16686 --target-port=16686 --type=LoadBalancer
+JWT Authentication:
+```python
+from jose import jwt, JWTError
+from datetime import datetime, timedelta
+from passlib.context import CryptContext
+
+pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="auth/login")
+
+SECRET_KEY = "your-secret-key"
+ALGORITHM = "HS256"
+ACCESS_TOKEN_EXPIRE_MINUTES = 30
+
+def create_access_token(data: dict, expires_delta: timedelta = None):
+    to_encode = data.copy()
+    expire = datetime.utcnow() + (expires_delta or timedelta(minutes=15))
+    to_encode.update({"exp": expire})
+    return jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)
+
+async def get_current_user(token: str = Depends(oauth2_scheme)):
+    credentials_exception = HTTPException(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        detail="Could not validate credentials",
+        headers={"WWW-Authenticate": "Bearer"},
+    )
+    try:
+        payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
+        user_id: str = payload.get("sub")
+        if user_id is None:
+            raise credentials_exception
+    except JWTError:
+        raise credentials_exception
+    return await get_user_by_id(user_id)
 ```
 
-**Production (with Elasticsearch)**:
-```bash
-helm repo add jaegertracing https://jaegertracing.github.io/helm-charts
-helm install jaeger jaegertracing/jaeger \
-  --set provisionDataStore.cassandra=false \
-  --set provisionDataStore.elasticsearch=true \
-  --set storage.type=elasticsearch \
-  --set storage.elasticsearch.host=elasticsearch-master \
-  --set storage.elasticsearch.port=9200
-```
+---
 
-### Grafana 10.x Dashboards
-
-**Key Dashboards**:
-- **RED Metrics**: Rate, Errors, Duration per service
-- **Kubernetes Cluster**: Node/pod resource usage
-- **Database Performance**: Query latency, connection pool
-- **Application Logs**: Error rate trends, log volume
-
-**Import Community Dashboards**:
-- Kubernetes Cluster Monitoring (ID: 7249)
-- Node Exporter Full (ID: 1860)
-- PostgreSQL Database (ID: 9628)
-
-## Performance Benchmarking
-
-### Load Testing Tools
-
-| Tool | Protocol | Complexity | Reporting | Use Case |
-|------|----------|------------|-----------|----------|
-| **k6** | HTTP, gRPC, WebSocket | Low | Good | API load testing |
-| **Gatling** | HTTP, WebSocket | Medium | Excellent | Complex scenarios |
-| **JMeter** | HTTP, JDBC, JMS, etc. | High | Good | Enterprise testing |
-| **Locust** | HTTP, custom | Low | Good | Python-based scripting |
-
-**Recommendation**: k6 for API load testing, Gatling for complex user journeys.
-
-### k6 Example (HTTP API)
-
-```javascript
-import http from 'k6/http';
-import { check, sleep } from 'k6';
-
-export let options = {
-  stages: [
-    { duration: '2m', target: 100 },  // Ramp-up
-    { duration: '5m', target: 100 },  // Steady
-    { duration: '2m', target: 0 },    // Ramp-down
-  ],
-  thresholds: {
-    http_req_duration: ['p(95)<500'],  // 95% under 500ms
-    http_req_failed: ['rate<0.01'],    // Error rate < 1%
-  },
-};
-
-export default function () {
-  let res = http.get('https://api.example.com/users');
-  check(res, {
-    'status is 200': (r) => r.status === 200,
-    'response time < 500ms': (r) => r.timings.duration < 500,
-  });
-  sleep(1);
-}
-```
+## Configuration Options
+
+### Application Configuration
 
-**Run**:
-```bash
-k6 run --vus 100 --duration 10m load-test.js
+```yaml
+# config/settings.yaml
+app:
+  name: "Backend Service"
+  version: "2.0.0"
+  debug: false
+  environment: "production"
+
+server:
+  host: "0.0.0.0"
+  port: 8000
+  workers: 4
+  reload: false
+
+database:
+  postgresql:
+    url: "postgresql+asyncpg://user:pass@localhost/db"
+    pool_size: 20
+    max_overflow: 30
+    pool_pre_ping: true
+  mongodb:
+    url: "mongodb://localhost:27017"
+    database: "myapp"
+    max_pool_size: 50
+  redis:
+    url: "redis://localhost:6379"
+    max_connections: 50
+
+security:
+  secret_key: "${SECRET_KEY}"
+  algorithm: "HS256"
+  access_token_expire_minutes: 30
+  refresh_token_expire_days: 7
+
+cors:
+  allow_origins:
+    - "http://localhost:3000"
+    - "https://myapp.com"
+  allow_credentials: true
+  allow_methods: ["*"]
+  allow_headers: ["*"]
+
+logging:
+  level: "INFO"
+  format: "json"
+  handlers:
+    - console
+    - file
 ```
 
-### Performance Targets
-
-| Metric | Target | Good | Excellent |
-|--------|--------|------|-----------|
-| **API Response Time (p95)** | <500ms | <200ms | <100ms |
-| **Error Rate** | <1% | <0.1% | <0.01% |
-| **Throughput** | 1000 req/s | 5000 req/s | 10000 req/s |
-| **Database Query (p95)** | <100ms | <50ms | <10ms |
-| **CPU Usage** | <70% | <50% | <30% |
-| **Memory Usage** | <80% | <60% | <40% |
-
-## Security Best Practices
-
-### OWASP API Security Top 10 2023 Checklist
-
-- [ ] **API1: Broken Object Level Authorization**
-  - Implement per-object access control checks
-  - Validate user owns the resource before access
-  - Use UUIDs instead of sequential IDs
-
-- [ ] **API2: Broken Authentication**
-  - Use industry-standard auth (OAuth 2.0, OpenID Connect)
-  - Implement rate limiting on auth endpoints
-  - Rotate secrets regularly
-
-- [ ] **API3: Broken Object Property Level Authorization**
-  - Use response DTOs to filter sensitive fields
-  - Validate input against allowed fields (no mass assignment)
-  - Implement role-based field visibility
-
-- [ ] **API4: Unrestricted Resource Consumption**
-  - Enforce pagination (max 100 items per page)
-  - Implement rate limiting (Redis-based)
-  - Set request timeouts and size limits
-
-- [ ] **API5: Broken Function Level Authorization**
-  - Validate roles/permissions on every endpoint
-  - Deny by default, allow explicitly
-  - Use middleware for consistent checks
-
-- [ ] **API6: Unrestricted Access to Sensitive Business Flows**
-  - Implement CAPTCHA for critical flows
-  - Detect and block automated abuse
-  - Monitor for unusual patterns
-
-- [ ] **API7: Server Side Request Forgery (SSRF)**
-  - Validate and whitelist URLs
-  - Block private IP ranges
-  - Use network segmentation
-
-- [ ] **API8: Security Misconfiguration**
-  - Disable debug mode in production
-  - Remove unnecessary endpoints
-  - Use security headers (HSTS, CSP, etc.)
-
-- [ ] **API9: Improper Inventory Management**
-  - Document all API versions
-  - Deprecate old versions gracefully
-  - Monitor for unauthorized endpoints
-
-- [ ] **API10: Unsafe Consumption of APIs**
-  - Validate external API responses
-  - Set timeouts for external calls
-  - Handle partial failures gracefully
-
-### Rate Limiting Implementation (Redis 7.2.x)
-
-**Token Bucket Algorithm**:
-```python
-import redis
-import time
+### Environment Variables
 
-def is_rate_limited(user_id: str, max_requests: int = 100, window: int = 60) -> bool:
-    """Token bucket rate limiting with Redis."""
-    r = redis.Redis(host='localhost', port=6379, db=0)
-    key = f"rate_limit:{user_id}"
+APP_ENV - Application environment (development, staging, production)
+DATABASE_URL - Primary database connection string
+MONGODB_URL - MongoDB connection string
+REDIS_URL - Redis connection string
+SECRET_KEY - JWT signing key
+CORS_ORIGINS - Comma-separated allowed origins
+LOG_LEVEL - Logging level (DEBUG, INFO, WARNING, ERROR)
 
-    current = r.get(key)
-    if current is None:
-        r.setex(key, window, 1)
-        return False
+---
 
-    current = int(current)
-    if current >= max_requests:
-        return True
+## Integration Patterns
 
-    r.incr(key)
-    return False
-```
+### Service Layer Pattern
 
-**Sliding Window (Accurate)**:
 ```python
-def sliding_window_rate_limit(user_id: str, max_requests: int = 100, window: int = 60) -> bool:
-    """Sliding window rate limiting with Redis sorted sets."""
-    r = redis.Redis(host='localhost', port=6379, db=0)
-    key = f"rate_limit:{user_id}"
-    now = time.time()
-
-    # Remove old entries
-    r.zremrangebyscore(key, 0, now - window)
-
-    # Count requests in window
-    count = r.zcard(key)
-    if count >= max_requests:
-        return True
-
-    # Add current request
-    r.zadd(key, {str(now): now})
-    r.expire(key, window)
-    return False
+from abc import ABC, abstractmethod
+from typing import Generic, TypeVar, List, Optional
+
+T = TypeVar('T')
+
+class BaseService(ABC, Generic[T]):
+    @abstractmethod
+    async def get(self, id: int) -> Optional[T]:
+        pass
+
+    @abstractmethod
+    async def get_all(self, skip: int = 0, limit: int = 100) -> List[T]:
+        pass
+
+    @abstractmethod
+    async def create(self, obj: T) -> T:
+        pass
+
+    @abstractmethod
+    async def update(self, id: int, obj: T) -> Optional[T]:
+        pass
+
+    @abstractmethod
+    async def delete(self, id: int) -> bool:
+        pass
+
+class UserService(BaseService[User]):
+    def __init__(self, db: AsyncSession, cache: Redis):
+        self.db = db
+        self.cache = cache
+
+    async def get(self, id: int) -> Optional[User]:
+        # Check cache first
+        cached = await self.cache.get(f"user:{id}")
+        if cached:
+            return User.parse_raw(cached)
+
+        # Query database
+        user = await self.db.get(User, id)
+        if user:
+            await self.cache.setex(f"user:{id}", 3600, user.json())
+        return user
 ```
 
-## Cost Optimization
-
-### Resource Right-Sizing
+### Repository Pattern
 
-**Kubernetes Resource Requests/Limits**:
-```yaml
-resources:
-  requests:
-    cpu: "100m"      # Minimum guaranteed
-    memory: "128Mi"
-  limits:
-    cpu: "500m"      # Maximum allowed
-    memory: "512Mi"
+```python
+from sqlalchemy import select, update, delete
+from sqlalchemy.ext.asyncio import AsyncSession
+
+class UserRepository:
+    def __init__(self, session: AsyncSession):
+        self.session = session
+
+    async def find_by_id(self, user_id: int) -> Optional[User]:
+        result = await self.session.execute(
+            select(User).where(User.id == user_id)
+        )
+        return result.scalar_one_or_none()
+
+    async def find_by_email(self, email: str) -> Optional[User]:
+        result = await self.session.execute(
+            select(User).where(User.email == email)
+        )
+        return result.scalar_one_or_none()
+
+    async def create(self, user_data: UserCreate) -> User:
+        user = User(**user_data.dict())
+        self.session.add(user)
+        await self.session.flush()
+        return user
+
+    async def update(self, user_id: int, data: UserUpdate) -> Optional[User]:
+        await self.session.execute(
+            update(User)
+            .where(User.id == user_id)
+            .values(**data.dict(exclude_unset=True))
+        )
+        return await self.find_by_id(user_id)
 ```
 
-**Guidelines**:
-- Set requests based on p50 usage
-- Set limits based on p99 usage
-- Enable Vertical Pod Autoscaler for recommendations
-
-### Auto-Scaling Strategies
+### Event-Driven Architecture
 
-**Horizontal Pod Autoscaler (HPA)**:
-```yaml
-apiVersion: autoscaling/v2
-kind: HorizontalPodAutoscaler
-metadata:
-  name: backend-hpa
-spec:
-  scaleTargetRef:
-    apiVersion: apps/v1
-    kind: Deployment
-    name: backend
-  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
+```python
+import asyncio
+from aio_pika import connect_robust, Message, ExchangeType
+
+class EventPublisher:
+    def __init__(self, amqp_url: str):
+        self.amqp_url = amqp_url
+        self.connection = None
+        self.channel = None
+        self.exchange = None
+
+    async def connect(self):
+        self.connection = await connect_robust(self.amqp_url)
+        self.channel = await self.connection.channel()
+        self.exchange = await self.channel.declare_exchange(
+            "events", ExchangeType.TOPIC, durable=True
+        )
+
+    async def publish(self, event_type: str, data: dict):
+        message = Message(
+            json.dumps(data).encode(),
+            content_type="application/json",
+            headers={"event_type": event_type}
+        )
+        await self.exchange.publish(message, routing_key=event_type)
+
+class EventSubscriber:
+    def __init__(self, amqp_url: str):
+        self.amqp_url = amqp_url
+        self.handlers = {}
+
+    def on(self, event_type: str):
+        def decorator(func):
+            self.handlers[event_type] = func
+            return func
+        return decorator
+
+    async def start(self):
+        connection = await connect_robust(self.amqp_url)
+        channel = await connection.channel()
+        exchange = await channel.declare_exchange(
+            "events", ExchangeType.TOPIC, durable=True
+        )
+        queue = await channel.declare_queue("", exclusive=True)
+
+        for event_type in self.handlers:
+            await queue.bind(exchange, routing_key=event_type)
+
+        async with queue.iterator() as queue_iter:
+            async for message in queue_iter:
+                async with message.process():
+                    event_type = message.headers.get("event_type")
+                    if event_type in self.handlers:
+                        data = json.loads(message.body)
+                        await self.handlers[event_type](data)
 ```
 
-**Cluster Autoscaler**:
-- Automatically adds/removes nodes based on pending pods
-- Works with cloud provider APIs (AWS, GCP, Azure)
-- Set min/max node count per node group
-
-### Caching Strategies for Cost Reduction
-
-**CDN for Static Assets**:
-- CloudFront, CloudFlare: ~$0.085/GB
-- Reduces origin server load by 80-90%
-- Set long TTLs (1 year) with versioned URLs
-
-**Redis Caching**:
-- Cache database queries (TTL: 5-60 minutes)
-- Session storage (reduce database connections)
-- Precomputed results (expensive calculations)
-
-**Database Connection Pooling**:
-- PgBouncer: Reduce database connections by 10x
-- Typical pool size: 10-20 connections per app instance
-- Significant cost savings on managed databases
-
-### Container Registry Comparison
-
-| Registry | Security Scanning | Geo-Replication | Cost | Integration | Use Case |
-|----------|------------------|------------------|------|-------------|----------|
-| **Docker Hub** | Free tier limited | No | Free/Paid | Universal | Public images |
-| **Amazon ECR** | Yes (Inspector) | Yes | Pay-per-GB | AWS native | AWS workloads |
-| **Google Artifact Registry** | Yes (Container Analysis) | Yes | Pay-per-GB | GCP native | GCP workloads |
-| **Azure ACR** | Yes (Defender) | Yes | Pay-per-GB | Azure native | Azure workloads |
-| **Harbor 2.10.x** | Yes (Trivy) | Yes | Self-hosted | Kubernetes | On-premises, multi-cloud |
-| **GitHub Container Registry** | Yes (Dependabot) | Global CDN | Free for public | GitHub Actions | CI/CD integration |
-
-**Recommendation**: Harbor 2.10.x for self-hosted multi-cloud, cloud-native registries for vendor lock-in scenarios.
-
-### API Gateway Comparison
-
-| Gateway | Protocol | Performance | Features | Complexity | Use Case |
-|---------|----------|-------------|----------|------------|----------|
-| **Kong 3.6.x** | HTTP, gRPC, WebSocket | Excellent | Plugins, mTLS, rate limiting | Medium | Enterprise APIs |
-| **Ambassador (Emissary-Ingress) 3.9.x** | HTTP, gRPC | Good | Kubernetes-native, Istio integration | Medium | Kubernetes microservices |
-| **Traefik 3.0.x** | HTTP, TCP, gRPC | Good | Auto-discovery, Let's Encrypt | Low | Docker/Kubernetes |
-| **NGINX Ingress Controller** | HTTP, TCP, UDP | Excellent | Battle-tested, low overhead | Low | General-purpose |
-| **AWS API Gateway** | HTTP, WebSocket | Good | Serverless, AWS Lambda | Low | AWS serverless |
-| **Envoy Proxy 1.29.x** | HTTP/1.1, HTTP/2, gRPC | Excellent | L7 proxy, xDS API | High | Service mesh (Istio) |
-
-**Recommendation**: Kong 3.6.x for feature-rich APIs, NGINX Ingress for simplicity, Envoy 1.29.x for service mesh integration.
-
-### CI/CD Platform Comparison
-
-| Platform | Cloud/Self-hosted | Kubernetes Support | Pipeline as Code | Cost | Use Case |
-|----------|-------------------|-------------------|------------------|------|----------|
-| **GitHub Actions** | Cloud | Yes (Kubernetes runners) | YAML | Free tier + paid | GitHub integration |
-| **GitLab CI/CD** | Both | Yes | YAML | Free tier + paid | GitLab ecosystem |
-| **Jenkins 2.440.x** | Self-hosted | Yes (Kubernetes plugin) | Groovy/Declarative | Free (self-hosted) | Enterprise, customization |
-| **ArgoCD 2.10.x** | Self-hosted | Yes (GitOps) | YAML (Git) | Free | Kubernetes GitOps |
-| **Tekton Pipelines 0.56.x** | Self-hosted | Yes (cloud-native) | YAML | Free | Kubernetes-native CI/CD |
-| **CircleCI** | Cloud | Yes | YAML | Free tier + paid | Fast feedback loops |
-
-**Recommendation**: ArgoCD 2.10.x for Kubernetes GitOps, GitHub Actions for GitHub-native workflows, Jenkins for complex enterprise pipelines.
-
-## References
-
-- Kubernetes. "Kubernetes Best Practices." https://kubernetes.io/docs/concepts/configuration/overview/ (2025-10-22)
-- Istio. "Performance and Scalability." https://istio.io/latest/docs/ops/deployment/performance-and-scalability/ (2025-10-22)
-- OpenTelemetry. "Getting Started." https://opentelemetry.io/docs/instrumentation/ (2025-10-22)
-- Prometheus. "Best Practices." https://prometheus.io/docs/practices/ (2025-10-22)
-- OWASP. "API Security Project." https://owasp.org/www-project-api-security/ (2025-10-22)
-- CNCF. "Cloud Native Landscape." https://landscape.cncf.io/ (2025-10-22)
-- Kafka. "Apache Kafka Documentation." https://kafka.apache.org/documentation/ (2025-10-22)
-- Harbor. "Harbor Documentation." https://goharbor.io/docs/ (2025-10-22)
-- ArgoCD. "ArgoCD Documentation." https://argo-cd.readthedocs.io/ (2025-10-22)
+---
+
+## Troubleshooting
+
+### Common Issues
+
+Issue: Connection pool exhausted
+Symptoms: Requests timeout, "too many connections" errors
+Solution:
+- Increase pool_size and max_overflow in database configuration
+- Check for connection leaks (ensure proper context manager usage)
+- Implement connection health checks with pool_pre_ping
+
+Issue: Slow database queries
+Symptoms: High response times, database CPU spikes
+Solution:
+- Use EXPLAIN ANALYZE to identify slow queries
+- Add appropriate indexes based on query patterns
+- Implement query result caching with Redis
+- Consider read replicas for read-heavy workloads
+
+Issue: Memory leaks in async operations
+Symptoms: Gradual memory increase, eventual OOM
+Solution:
+- Use async context managers properly
+- Implement proper cleanup in lifespan handlers
+- Monitor task cancellation and cleanup
+- Use weak references for caches where appropriate
+
+Issue: CORS errors in browser
+Symptoms: Cross-origin requests blocked
+Solution:
+- Verify allow_origins includes client domain
+- Check allow_credentials setting for cookie-based auth
+- Ensure preflight OPTIONS requests are handled
+- Add explicit headers for custom request headers
+
+Issue: JWT token expiration issues
+Symptoms: Users logged out unexpectedly
+Solution:
+- Implement refresh token rotation
+- Use sliding window expiration for active users
+- Add token refresh middleware
+- Handle token refresh in frontend interceptors
+
+### Performance Optimization
+
+Query Optimization:
+- Use select_related/joinedload for N+1 query prevention
+- Implement pagination with cursor-based approach for large datasets
+- Use database-level aggregations instead of application-level
+- Cache frequently accessed, rarely changed data
+
+Connection Management:
+- Tune pool sizes based on actual workload
+- Use connection poolers (PgBouncer) for high-concurrency
+- Implement circuit breakers for external service calls
+- Monitor connection metrics and adjust accordingly
+
+Async Best Practices:
+- Use asyncio.gather for concurrent operations
+- Implement proper timeout handling
+- Use semaphores to limit concurrent external calls
+- Profile async code with py-spy or similar tools
+
+---
+
+## External Resources
+
+### Frameworks
+- FastAPI: https://fastapi.tiangolo.com/
+- Django: https://www.djangoproject.com/
+- Flask: https://flask.palletsprojects.com/
+- Starlette: https://www.starlette.io/
+
+### Databases
+- SQLAlchemy: https://docs.sqlalchemy.org/
+- Motor (MongoDB): https://motor.readthedocs.io/
+- Redis-py: https://redis-py.readthedocs.io/
+- asyncpg: https://magicstack.github.io/asyncpg/
+
+### Message Queues
+- RabbitMQ: https://www.rabbitmq.com/documentation.html
+- Apache Kafka: https://kafka.apache.org/documentation/
+- aio-pika: https://aio-pika.readthedocs.io/
+
+### Security
+- OWASP API Security: https://owasp.org/www-project-api-security/
+- python-jose: https://python-jose.readthedocs.io/
+- Passlib: https://passlib.readthedocs.io/
+
+### Monitoring
+- Prometheus: https://prometheus.io/docs/
+- OpenTelemetry: https://opentelemetry.io/docs/
+- Grafana: https://grafana.com/docs/
+
+### Best Practices
+- 12 Factor App: https://12factor.net/
+- Microservices Patterns: https://microservices.io/patterns/
+- API Design Guidelines: https://github.com/microsoft/api-guidelines
+
+---
+
+Version: 1.0.0
+Last Updated: 2025-12-06