@nockdev/awf 6.2.0 → 6.2.2

package/.agent/skills/cross-cutting/microservices/META.yaml

@@ -0,0 +1,90 @@
+# =============================================================================
+# META.yaml — Microservices Patterns
+# =============================================================================
+# Tier 1: Always loaded (~100 tokens)
+# =============================================================================
+
+name: microservices
+version: "1.0.0"
+category: cross-cutting
+priority: 2
+
+description: |
+  Microservices architecture patterns: Saga, CQRS, Event Sourcing,
+  service mesh, inter-service communication, resilience, and deployment.
+
+# =============================================================================
+# TRIGGERS — When to activate this skill
+# =============================================================================
+
+triggers:
+  keywords:
+    - microservices
+    - microservice
+    - saga pattern
+    - cqrs
+    - event sourcing
+    - service mesh
+    - api gateway
+    - circuit breaker
+    - distributed system
+    - event-driven
+    - message queue
+    - kafka
+    - rabbitmq
+    - nats
+    - grpc
+    - service discovery
+    - sidecar proxy
+    - istio
+    - linkerd
+    - domain-driven design
+    - ddd
+    - bounded context
+
+  intents:
+    - "design microservices architecture"
+    - "implement saga pattern"
+    - "setup event sourcing"
+    - "configure service mesh"
+    - "implement circuit breaker"
+    - "setup message queue"
+    - "distributed tracing"
+
+  detect_patterns:
+    files:
+      ["docker-compose.yaml", "docker-compose.yml", "k8s/", "helm/", "proto/"]
+    content: ["@EventHandler", "@SagaStep", "proto3", "service mesh"]
+
+# =============================================================================
+# CAPABILITIES — What this skill provides
+# =============================================================================
+
+caps:
+  - saga_orchestration
+  - saga_choreography
+  - cqrs_implementation
+  - event_store_design
+  - service_mesh_config
+  - circuit_breaker_setup
+  - distributed_tracing
+  - api_gateway_patterns
+  - inter_service_communication
+  - deployment_strategies
+
+# =============================================================================
+# DATA FILES — Tier 2/3 resources
+# =============================================================================
+
+data_files:
+  - saga-patterns.yaml # Orchestration & Choreography
+  - cqrs-patterns.yaml # Command/Query separation
+  - event-sourcing.yaml # Event store, snapshots, replay
+  - service-mesh.yaml # Istio, Linkerd, sidecar
+  - communication.yaml # Sync vs Async patterns
+  - resilience.yaml # Circuit breaker, bulkhead, retry
+  - observability.yaml # Distributed tracing, correlation IDs
+  - deployment.yaml # Blue-green, canary, rolling
+
+
+# _DOMYH Awesome Code • Microservices Skill_

package/.agent/skills/cross-cutting/microservices/SKILL.md

@@ -0,0 +1,120 @@
+# 🏗️ Microservices Patterns
+
+> Architecture patterns for distributed systems
+> 📚 Saga • CQRS • Event Sourcing • Service Mesh • Resilience
+
+---
+
+## Quick Reference
+
+| Pattern             | When to Use                                  | Complexity |
+| ------------------- | -------------------------------------------- | ---------- |
+| **Saga**            | Multi-service transactions                   | High       |
+| **CQRS**            | Read/write asymmetry                         | Medium     |
+| **Event Sourcing**  | Audit trail, temporal queries                | High       |
+| **Service Mesh**    | Cross-cutting concerns (mTLS, observability) | High       |
+| **Circuit Breaker** | Prevent cascade failures                     | Low        |
+| **API Gateway**     | Single entry point, routing                  | Medium     |
+
+---
+
+## Saga Pattern
+
+### Orchestration vs Choreography
+
+| Aspect    | Orchestration           | Choreography             |
+| --------- | ----------------------- | ------------------------ |
+| Control   | Central orchestrator    | Event-driven, no central |
+| Coupling  | Services → orchestrator | Event chain              |
+| Debugging | Easier (single flow)    | Harder (distributed)     |
+| Best for  | Complex workflows       | Simple 2-3 service flows |
+
+### Compensating Transactions
+
+```
+Order → Payment → Inventory → Shipping
+  ↓ (if Shipping fails)
+  Refund ← Restock ← Cancel
+```
+
+---
+
+## CQRS
+
+```
+┌─────────────────────────────────────────────┐
+│  Command Side        │  Query Side          │
+│  ────────────        │  ──────────          │
+│  Write Model         │  Read Model          │
+│  Domain Events       │  Projections         │
+│  Event Store         │  Materialized Views  │
+│  Optimized for       │  Optimized for       │
+│  consistency         │  performance         │
+└─────────────────────────────────────────────┘
+```
+
+---
+
+## Communication Patterns
+
+| Type  | Protocol  | Use Case                         |
+| ----- | --------- | -------------------------------- |
+| Sync  | REST/HTTP | Simple request-response          |
+| Sync  | gRPC      | High-perf, typed contracts       |
+| Async | Kafka     | Event streaming, high throughput |
+| Async | RabbitMQ  | Task queues, routing             |
+| Async | NATS      | Lightweight pub/sub              |
+
+---
+
+## Resilience Patterns
+
+| Pattern             | Purpose                  | Library                      |
+| ------------------- | ------------------------ | ---------------------------- |
+| **Circuit Breaker** | Stop cascade failures    | Hystrix, Resilience4j, Polly |
+| **Bulkhead**        | Isolate failures         | Thread pools, semaphores     |
+| **Retry**           | Transient error recovery | Exponential backoff          |
+| **Timeout**         | Prevent hanging          | Per-service config           |
+| **Fallback**        | Graceful degradation     | Cache, default values        |
+
+---
+
+## Service Mesh
+
+| Feature        | Istio       | Linkerd  |
+| -------------- | ----------- | -------- |
+| mTLS           | ✅ Auto     | ✅ Auto  |
+| Traffic mgmt   | ✅ Advanced | ⚠️ Basic |
+| Observability  | ✅ Full     | ✅ Good  |
+| Complexity     | High        | Low      |
+| Resource usage | Heavy       | Light    |
+
+---
+
+## Deployment Strategies
+
+| Strategy        | Zero-Downtime | Rollback |   Risk   |
+| --------------- | :-----------: | :------: | :------: |
+| **Blue-Green**  |      ✅       | Instant  |   Low    |
+| **Canary**      |      ✅       | Gradual  | Very Low |
+| **Rolling**     |      ✅       |   Slow   |  Medium  |
+| **A/B Testing** |      ✅       | Instant  |   Low    |
+
+---
+
+## HSA Integration
+
+| Query                               | Data File             |
+| ----------------------------------- | --------------------- |
+| `saga orchestration compensation`   | `saga-patterns.yaml`  |
+| `cqrs event store projection`       | `cqrs-patterns.yaml`  |
+| `event sourcing snapshot replay`    | `event-sourcing.yaml` |
+| `istio linkerd sidecar`             | `service-mesh.yaml`   |
+| `grpc kafka rabbitmq nats`          | `communication.yaml`  |
+| `circuit breaker bulkhead retry`    | `resilience.yaml`     |
+| `distributed tracing opentelemetry` | `observability.yaml`  |
+| `blue-green canary rolling`         | `deployment.yaml`     |
+
+---
+
+_DOMYH Awesome Code • Microservices Patterns_

package/.agent/skills/cross-cutting/microservices/data/communication.yaml

@@ -0,0 +1,163 @@
+# =============================================================================
+# communication.yaml — Inter-Service Communication Patterns
+# =============================================================================
+
+version: "1.0.0"
+
+# =============================================================================
+# SYNCHRONOUS PATTERNS
+# =============================================================================
+
+synchronous:
+  rest:
+    description: "HTTP/JSON — simple, widely supported"
+    best_for: "Public APIs, simple CRUD, browser clients"
+    example: |
+      // Go — HTTP client with timeout and retry
+      client := &http.Client{
+          Timeout: 5 * time.Second,
+          Transport: &http.Transport{
+              MaxIdleConns:    100,
+              IdleConnTimeout: 90 * time.Second,
+          },
+      }
+
+  grpc:
+    description: "HTTP/2 + Protobuf — high performance, typed"
+    best_for: "Internal service-to-service, streaming, low latency"
+    proto_example: |
+      syntax = "proto3";
+      package order;
+
+      service OrderService {
+        rpc CreateOrder(CreateOrderRequest) returns (OrderResponse);
+        rpc GetOrder(GetOrderRequest) returns (OrderResponse);
+        rpc StreamOrders(StreamRequest) returns (stream OrderResponse);
+      }
+
+      message CreateOrderRequest {
+        string customer_id = 1;
+        repeated OrderItem items = 2;
+      }
+
+    go_example: |
+      // gRPC server
+      type orderServer struct {
+          pb.UnimplementedOrderServiceServer
+      }
+
+      func (s *orderServer) CreateOrder(ctx context.Context, req *pb.CreateOrderRequest) (*pb.OrderResponse, error) {
+          order, err := s.service.Create(ctx, req.CustomerId, req.Items)
+          if err != nil {
+              return nil, status.Error(codes.Internal, err.Error())
+          }
+          return toProto(order), nil
+      }
+
+  graphql:
+    description: "Query language — flexible, client-driven"
+    best_for: "Frontend-facing APIs, aggregation layer"
+    federation: |
+      # Gateway federates multiple service schemas
+      Service A: User { id, name, email }
+      Service B: Order { id, userId, total }
+      Gateway: User { id, name, email, orders: [Order] }
+
+# =============================================================================
+# ASYNCHRONOUS PATTERNS
+# =============================================================================
+
+asynchronous:
+  kafka:
+    description: "Distributed event streaming platform"
+    best_for: "High throughput, event sourcing, log aggregation"
+    patterns:
+      - name: "Event Streaming"
+        description: "Publish events to topics, consumers process"
+      - name: "Log Compaction"
+        description: "Keep latest value per key"
+      - name: "Consumer Groups"
+        description: "Parallel processing with partition assignment"
+
+    config_example: |
+      # Kafka producer config (Go)
+      config := kafka.ConfigMap{
+          "bootstrap.servers":  "localhost:9092",
+          "acks":               "all",
+          "retries":            3,
+          "enable.idempotence": true,
+      }
+
+  rabbitmq:
+    description: "Message broker with exchange routing"
+    best_for: "Task queues, routing, RPC over messages"
+    exchange_types:
+      - direct: "Route by exact routing key"
+      - topic: "Route by pattern matching (*.log.error)"
+      - fanout: "Broadcast to all bound queues"
+      - headers: "Route by message headers"
+
+  nats:
+    description: "Lightweight pub/sub messaging"
+    best_for: "IoT, edge computing, simple pub/sub"
+    features:
+      - "Core NATS: At-most-once delivery"
+      - "JetStream: At-least-once with persistence"
+      - "Key-Value: Distributed key-value store"
+
+# =============================================================================
+# API GATEWAY PATTERNS
+# =============================================================================
+
+api_gateway:
+  purpose: "Single entry point for all clients"
+  responsibilities:
+    - "Request routing"
+    - "Authentication/Authorization"
+    - "Rate limiting"
+    - "Load balancing"
+    - "Response caching"
+    - "Protocol translation"
+
+  implementations:
+    - name: Kong
+      type: "Open-source, plugin-based"
+    - name: "AWS API Gateway"
+      type: "Managed, serverless"
+    - name: Envoy
+      type: "L7 proxy, service mesh data plane"
+    - name: Traefik
+      type: "Cloud-native, auto-discovery"
+
+  bff_pattern:
+    description: "Backend for Frontend — separate gateway per client type"
+    example: |
+      Mobile BFF  → /api/mobile/...  → Mobile-optimized responses
+      Web BFF     → /api/web/...     → Rich desktop responses
+      IoT BFF     → /api/iot/...     → Minimal payloads
+
+# =============================================================================
+# DECISION GUIDE
+# =============================================================================
+
+decision_guide:
+  sync_vs_async:
+    use_sync:
+      - "Client needs immediate response"
+      - "Simple request-response"
+      - "Strong consistency required"
+    use_async:
+      - "Fire-and-forget operations"
+      - "Long-running processes"
+      - "Decoupled services"
+      - "Event-driven architecture"
+
+  protocol_selection:
+    rest: "Public APIs, browser clients, simple CRUD"
+    grpc: "Internal high-performance, streaming, polyglot"
+    graphql: "Frontend aggregation, flexible queries"
+    kafka: "Event streaming, high throughput, replay"
+    rabbitmq: "Task queues, complex routing"
+    nats: "Lightweight pub/sub, edge"
+
+# _DOMYH Awesome Code • Communication Patterns_

package/.agent/skills/cross-cutting/microservices/data/cqrs-patterns.yaml

@@ -0,0 +1,199 @@
+# =============================================================================
+# cqrs-patterns.yaml — CQRS Implementation Patterns
+# =============================================================================
+
+version: "1.0.0"
+
+# =============================================================================
+# CORE CONCEPT
+# =============================================================================
+
+overview:
+  description: |
+    Command Query Responsibility Segregation separates read and write
+    models for optimized performance and scalability.
+
+  architecture: |
+    ┌─────────────────────────────────────────────────┐
+    │  Client                                         │
+    │  ├── Commands (Write) → Command Handler         │
+    │  │                       → Domain Model         │
+    │  │                       → Event Store          │
+    │  │                       → Domain Events        │
+    │  │                                ↓             │
+    │  │                       → Projections          │
+    │  │                                ↓             │
+    │  └── Queries (Read) ←── Read Model (Views)      │
+    └─────────────────────────────────────────────────┘
+
+# =============================================================================
+# COMMAND SIDE
+# =============================================================================
+
+command_side:
+  patterns:
+    command:
+      description: "Immutable intent to change state"
+      example: |
+        // Go
+        type CreateOrderCommand struct {
+            OrderID    string
+            CustomerID string
+            Items      []OrderItem
+            CreatedAt  time.Time
+        }
+
+        type CommandHandler interface {
+            Handle(ctx context.Context, cmd Command) error
+        }
+
+        type CreateOrderHandler struct {
+            repo  OrderRepository
+            bus   EventBus
+        }
+
+        func (h *CreateOrderHandler) Handle(ctx context.Context, cmd CreateOrderCommand) error {
+            order, err := domain.NewOrder(cmd.OrderID, cmd.CustomerID, cmd.Items)
+            if err != nil {
+                return err
+            }
+            if err := h.repo.Save(ctx, order); err != nil {
+                return err
+            }
+            return h.bus.Publish(ctx, order.DomainEvents()...)
+        }
+
+    command_bus:
+      description: "Routes commands to handlers"
+      example_typescript: |
+        interface Command {
+          readonly type: string;
+        }
+
+        type CommandHandler<T extends Command> = (cmd: T) => Promise<void>;
+
+        class CommandBus {
+          private handlers = new Map<string, CommandHandler<any>>();
+
+          register<T extends Command>(type: string, handler: CommandHandler<T>) {
+            this.handlers.set(type, handler);
+          }
+
+          async dispatch<T extends Command>(cmd: T): Promise<void> {
+            const handler = this.handlers.get(cmd.type);
+            if (!handler) throw new Error(`No handler for ${cmd.type}`);
+            await handler(cmd);
+          }
+        }
+
+# =============================================================================
+# QUERY SIDE
+# =============================================================================
+
+query_side:
+  patterns:
+    read_model:
+      description: "Denormalized views optimized for reads"
+      strategies:
+        - name: "Materialized View"
+          description: "Pre-computed query results"
+          storage: "Redis, Elasticsearch, read-replica DB"
+
+        - name: "Projection"
+          description: "Build read model from events"
+          storage: "Eventual consistency with event stream"
+
+    example: |
+      // Go — Query Handler
+      type GetOrderQuery struct {
+          OrderID string
+      }
+
+      type OrderView struct {
+          OrderID      string    `json:"order_id"`
+          CustomerName string    `json:"customer_name"`
+          Items        []string  `json:"items"`
+          Total        float64   `json:"total"`
+          Status       string    `json:"status"`
+          CreatedAt    time.Time `json:"created_at"`
+      }
+
+      type OrderQueryHandler struct {
+          readDB *sql.DB // Separate read database
+      }
+
+      func (h *OrderQueryHandler) Handle(ctx context.Context, q GetOrderQuery) (*OrderView, error) {
+          return h.readDB.QueryOrder(ctx, q.OrderID)
+      }
+
+# =============================================================================
+# PROJECTIONS
+# =============================================================================
+
+projections:
+  description: "Transform events into read models"
+
+  strategies:
+    - name: "Synchronous Projection"
+      consistency: "Strong"
+      latency: "Added to write path"
+      use_when: "Read model must be immediately consistent"
+
+    - name: "Asynchronous Projection"
+      consistency: "Eventual"
+      latency: "Minimal write impact"
+      use_when: "Eventual consistency acceptable"
+
+  example: |
+    // Projection: OrderEvents → OrderSummaryView
+    type OrderProjection struct {
+        viewStore ViewStore
+    }
+
+    func (p *OrderProjection) Handle(event DomainEvent) error {
+        switch e := event.(type) {
+        case OrderCreated:
+            return p.viewStore.Insert(OrderSummary{
+                ID:     e.OrderID,
+                Status: "created",
+                Total:  e.Total,
+            })
+        case OrderPaid:
+            return p.viewStore.Update(e.OrderID, map[string]any{
+                "status":  "paid",
+                "paid_at": e.PaidAt,
+            })
+        case OrderShipped:
+            return p.viewStore.Update(e.OrderID, map[string]any{
+                "status":      "shipped",
+                "tracking_no": e.TrackingNumber,
+            })
+        }
+        return nil
+    }
+
+# =============================================================================
+# DECISION GUIDE
+# =============================================================================
+
+decision_guide:
+  use_cqrs_when:
+    - "Read and write models have different shapes"
+    - "Read:write ratio is heavily skewed (10:1+)"
+    - "Need independent scaling of reads vs writes"
+    - "Complex domain with rich behavior"
+
+  avoid_cqrs_when:
+    - "Simple CRUD application"
+    - "Small team without distributed systems experience"
+    - "Strong consistency required everywhere"
+
+  common_mistakes:
+    - mistake: "Using CQRS for simple CRUD"
+      impact: "Unnecessary complexity"
+    - mistake: "Not handling eventual consistency"
+      impact: "Stale data shown to users"
+    - mistake: "Shared database for read/write"
+      impact: "Defeats the purpose of separation"
+
+# _DOMYH Awesome Code • CQRS Patterns_