javi-forge 1.2.0 → 1.4.0

package/ai-config/skills/backend/api-gateway/SKILL.md

@@ -1,254 +0,0 @@
----
-name: api-gateway
-description: >
-  API Gateway concepts. Routing, rate limiting, authentication, load balancing.
-  Trigger: API Gateway, routing, load balancing, reverse proxy, edge service
-tools:
-  - Read
-  - Write
-  - Edit
-  - Grep
-metadata:
-  author: apigen-team
-  version: "1.0"
-  tags: [gateway, routing, microservices, edge]
-  scope: ["**/gateway/**"]
----
-
-# API Gateway Concepts
-
-## What is an API Gateway?
-
-```
-Single entry point for all client requests
-
-         ┌─────────────────┐
-         │    Clients      │
-         │ (Web, Mobile)   │
-         └────────┬────────┘
-                  │
-         ┌────────▼────────┐
-         │   API Gateway   │
-         │  (routing,      │
-         │   auth, rate    │
-         │   limiting)     │
-         └────────┬────────┘
-                  │
-    ┌─────────────┼─────────────┐
-    │             │             │
-┌───▼───┐    ┌───▼───┐    ┌───▼───┐
-│User   │    │Order  │    │Product│
-│Service│    │Service│    │Service│
-└───────┘    └───────┘    └───────┘
-```
-
-## Core Responsibilities
-
-### Routing
-```
-Route requests to appropriate backend services:
-
-/api/users/*     → User Service
-/api/orders/*    → Order Service
-/api/products/*  → Product Service
-
-Path rewriting:
-/api/users/123   → /users/123 (strip prefix)
-```
-
-### Authentication/Authorization
-```
-Centralized auth at edge:
-1. Validate JWT token
-2. Extract user context
-3. Forward user info to services
-4. Return 401/403 if invalid
-
-Benefits:
-- Services don't need auth logic
-- Consistent auth across services
-- Token validation cached
-```
-
-### Rate Limiting
-```
-Protect services from overload:
-
-Per client:
-  Anonymous: 60 req/min
-  Authenticated: 1000 req/min
-  Premium: 10000 req/min
-
-Per endpoint:
-  /api/search: 30 req/min
-  /api/login: 5 req/min
-```
-
-### Load Balancing
-```
-Distribute traffic across instances:
-
-Strategies:
-- Round Robin
-- Least Connections
-- Weighted
-- IP Hash (sticky sessions)
-
-Health checks:
-- Remove unhealthy instances
-- Automatic failover
-```
-
-## Additional Features
-
-### Request/Response Transformation
-```
-Transform requests:
-- Add headers (correlation ID, auth)
-- Modify body
-- Change content type
-
-Transform responses:
-- Remove internal headers
-- Standardize error format
-- Add CORS headers
-```
-
-### Caching
-```
-Cache responses at edge:
-
-Benefits:
-- Reduce backend load
-- Faster response times
-- Resilience (serve cached on failure)
-
-Strategies:
-- Cache by URL + headers
-- Cache invalidation
-- Vary by user/tenant
-```
-
-### Circuit Breaking
-```
-Prevent cascade failures:
-
-States:
-- Closed: Normal operation
-- Open: Fail fast (service down)
-- Half-Open: Test recovery
-
-Configuration:
-- Failure threshold
-- Timeout
-- Recovery window
-```
-
-### Logging & Monitoring
-```
-Centralized observability:
-
-Metrics:
-- Request rate
-- Error rate
-- Latency (P50, P95, P99)
-- Active connections
-
-Logging:
-- Access logs
-- Request/response bodies (debug)
-- Correlation IDs
-
-Tracing:
-- Distributed trace propagation
-- Span timing
-```
-
-## Gateway Patterns
-
-### Backend for Frontend (BFF)
-```
-Separate gateways per client type:
-
-Web BFF Gateway    → Web-specific routes
-Mobile BFF Gateway → Mobile-optimized APIs
-Partner Gateway    → B2B API contracts
-```
-
-### API Composition
-```
-Aggregate multiple services:
-
-GET /api/dashboard
-  → GET /users/me
-  → GET /orders/recent
-  → GET /notifications/unread
-  → Combined response
-```
-
-### Canary Releases
-```
-Route % of traffic to new version:
-
-v1 (stable): 95%
-v2 (canary): 5%
-
-Progressive rollout:
-Day 1: 5%
-Day 2: 25%
-Day 3: 50%
-Day 4: 100%
-```
-
-## Gateway Solutions
-
-```
-| Solution | Type | Best For |
-|----------|------|----------|
-| Kong | Open source | Feature-rich, plugins |
-| AWS API Gateway | Managed | AWS ecosystem |
-| Apigee | Enterprise | API management |
-| NGINX | OSS | Performance |
-| Spring Cloud Gateway | Framework | Java/Spring |
-| Envoy | Proxy | Service mesh |
-| Traefik | Cloud-native | Kubernetes |
-```
-
-## Security Considerations
-
-```
-✅ TLS termination at gateway
-✅ Request validation (size, content-type)
-✅ SQL injection / XSS prevention
-✅ DDoS protection
-✅ IP allowlisting/blocklisting
-✅ Bot detection
-✅ API key rotation
-✅ Secrets management
-```
-
-## Best Practices
-
-```
-Performance:
-✅ Connection pooling
-✅ Async I/O
-✅ Response streaming
-✅ Compression
-
-Reliability:
-✅ Health checks
-✅ Graceful degradation
-✅ Retry with backoff
-✅ Timeout configuration
-
-Operations:
-✅ Blue-green deployment
-✅ Configuration as code
-✅ Centralized logging
-✅ Alerting on error spikes
-```
-
-## Related Skills
-
-- `gateway-spring`: Spring Cloud Gateway implementation

package/ai-config/skills/backend/bff-concepts/SKILL.md

@@ -1,239 +0,0 @@
----
-name: bff-concepts
-description: >
-  Backend for Frontend pattern. Client-specific APIs, response tailoring, aggregation.
-  Trigger: BFF, backend for frontend, aggregation, client-specific, mobile API
-tools:
-  - Read
-  - Write
-  - Edit
-  - Grep
-metadata:
-  author: apigen-team
-  version: "1.0"
-  tags: [bff, architecture, api-design, microservices]
-  scope: ["**/bff/**"]
----
-
-# Backend for Frontend (BFF) Pattern
-
-## Core Concept
-
-```
-Traditional API:
-┌─────────────────────────────────────────┐
-│         Single Generic API              │
-│  (serves Web, Mobile, TV, Partners)     │
-└─────────────────────────────────────────┘
-         ↓         ↓         ↓
-      [Web]    [Mobile]    [TV]
-   (over-fetching + under-fetching)
-
-BFF Pattern:
-┌───────────┐ ┌───────────┐ ┌───────────┐
-│  Web BFF  │ │Mobile BFF │ │  TV BFF   │
-└─────┬─────┘ └─────┬─────┘ └─────┬─────┘
-      ↓             ↓             ↓
-┌─────────────────────────────────────────┐
-│         Backend Microservices           │
-└─────────────────────────────────────────┘
-```
-
-## Client Types
-
-### Web BFF
-```
-Characteristics:
-- Full data payloads (fast connections)
-- Rich interaction capabilities
-- SEO requirements (SSR data)
-- Complex filtering/sorting UI
-
-Typical operations:
-- Large paginated lists
-- Real-time updates (WebSocket)
-- Complex search queries
-- File uploads
-```
-
-### Mobile BFF
-```
-Characteristics:
-- Bandwidth optimization
-- Battery conservation
-- Offline support (sync)
-- Push notifications
-
-Optimizations:
-- Compressed responses
-- Delta sync (only changes)
-- Image CDN URLs (different sizes)
-- Aggressive caching headers
-```
-
-### IoT / Embedded BFF
-```
-Characteristics:
-- Minimal payloads
-- Low memory footprint
-- Binary protocols (gRPC/MQTT)
-- Intermittent connectivity
-
-Patterns:
-- Batch operations
-- Store-and-forward
-- Heartbeat polling
-```
-
-## Response Tailoring
-
-### Field Selection
-```json
-// Web: Full response
-{
-  "user": {
-    "id": "123",
-    "name": "John Doe",
-    "email": "john@example.com",
-    "avatar": "https://...",
-    "bio": "...",
-    "preferences": {...},
-    "stats": {...}
-  }
-}
-
-// Mobile: Tailored response
-{
-  "user": {
-    "id": "123",
-    "name": "John Doe",
-    "avatar_thumb": "https://.../48x48"
-  }
-}
-```
-
-### Aggregation Strategies
-```
-Sequential:
-1. Get user profile
-2. Get user's orders
-3. Get recommendations
-4. Combine and return
-
-Parallel:
-1. Fork: [profile, orders, recommendations]
-2. Join: Combine results
-3. Return aggregated response
-
-Conditional:
-1. Get user profile
-2. IF premium user THEN get recommendations
-3. Return appropriate response
-```
-
-## Rate Limiting per Client
-
-```
-Web clients:
-- 1000 req/min (authenticated)
-- 100 req/min (anonymous)
-
-Mobile clients:
-- 500 req/min (aggressive caching expected)
-
-Partner APIs:
-- Per-contract limits
-- Separate quotas per partner
-```
-
-## Query Composition
-
-### GraphQL-like Behavior
-```
-Request:
-GET /bff/dashboard?include=profile,notifications,orders
-
-Response:
-{
-  "profile": {...},
-  "notifications": [...],
-  "orders": [...]
-}
-
-Backend calls:
-- GET /users/me → profile
-- GET /notifications?limit=5 → notifications
-- GET /orders?status=pending → orders
-```
-
-### Partial Failure Handling
-```json
-{
-  "profile": {...},
-  "notifications": {
-    "_error": "Service temporarily unavailable",
-    "_fallback": []
-  },
-  "orders": [...]
-}
-```
-
-## Caching Strategies
-
-```
-Per-client-type:
-- Web: 5 min cache, ETags
-- Mobile: 30 min cache, stale-while-revalidate
-- IoT: 1 hour cache
-
-Per-resource:
-- User profile: 5 min
-- Product catalog: 1 hour
-- Recommendations: 15 min
-```
-
-## Implementation Patterns
-
-### Request/Response DTOs
-```
-// Client-specific DTOs
-WebUserResponse:
-  - All fields
-  - Nested objects
-  - Full links
-
-MobileUserResponse:
-  - Essential fields only
-  - IDs instead of nested objects
-  - Thumbnail URLs
-```
-
-### Service Orchestration
-```
-BFF Controller:
-1. Parse client context (User-Agent, Accept)
-2. Determine required data
-3. Call services (parallel when possible)
-4. Apply transformations
-5. Return tailored response
-```
-
-## Anti-patterns to Avoid
-
-```
-❌ Business logic in BFF
-   → BFF should only orchestrate and transform
-
-❌ Direct database access
-   → Always go through services
-
-❌ Shared BFF for different clients
-   → Each client type needs its own BFF
-
-❌ Duplicating validation
-   → Let backend services handle validation
-```
-
-## Related Skills
-
-- `bff-spring`: Spring Boot BFF implementation