@nockdev/awf 6.2.0 → 6.2.1

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

@@ -0,0 +1,153 @@
+# =============================================================================
+# deployment.yaml — Microservices Deployment Strategies
+# =============================================================================
+
+version: "1.0.0"
+
+# =============================================================================
+# STRATEGIES
+# =============================================================================
+
+strategies:
+  blue_green:
+    description: "Two identical environments, instant switch"
+    flow: |
+      1. Blue (current) serves traffic
+      2. Deploy new version to Green
+      3. Test Green thoroughly
+      4. Switch load balancer: Blue → Green
+      5. Old Blue becomes standby
+    rollback: "Instant — switch back to Blue"
+    kubernetes: |
+      # Deploy green version
+      kubectl apply -f deployment-green.yaml
+      # Test green service
+      kubectl port-forward svc/my-app-green 8081:80
+      # Switch traffic (update service selector)
+      kubectl patch svc my-app -p '{"spec":{"selector":{"version":"green"}}}'
+    pros:
+      - "Zero downtime"
+      - "Instant rollback"
+      - "Full testing before switch"
+    cons:
+      - "2x infrastructure cost"
+      - "Database migrations need care"
+
+  canary:
+    description: "Gradual traffic shift to new version"
+    flow: |
+      1. Deploy canary (new version) alongside stable
+      2. Route 5% traffic to canary
+      3. Monitor error rates, latency
+      4. Gradually increase: 5% → 25% → 50% → 100%
+      5. Remove old version
+    rollback: "Route 100% back to stable"
+    kubernetes_istio: |
+      apiVersion: networking.istio.io/v1
+      kind: VirtualService
+      metadata:
+        name: my-app
+      spec:
+        hosts: [my-app]
+        http:
+          - route:
+              - destination:
+                  host: my-app
+                  subset: stable
+                weight: 95
+              - destination:
+                  host: my-app
+                  subset: canary
+                weight: 5
+    monitoring_criteria:
+      - "Error rate < 1%"
+      - "p99 latency < 500ms"
+      - "No increase in 5xx responses"
+
+  rolling:
+    description: "Replace instances one-by-one"
+    kubernetes: |
+      apiVersion: apps/v1
+      kind: Deployment
+      spec:
+        replicas: 4
+        strategy:
+          type: RollingUpdate
+          rollingUpdate:
+            maxSurge: 1        # Max extra pods during update
+            maxUnavailable: 0  # Zero downtime
+    pros:
+      - "No extra infrastructure"
+      - "Built into Kubernetes"
+    cons:
+      - "Slow rollback (re-deploy old version)"
+      - "Both versions run simultaneously"
+
+  feature_flags:
+    description: "Code-level control of feature visibility"
+    tools:
+      - name: LaunchDarkly
+        type: "SaaS"
+      - name: Unleash
+        type: "Open source"
+      - name: Flagsmith
+        type: "Open source"
+    example: |
+      // Feature flag check
+      if featureFlags.IsEnabled("new-checkout", user) {
+          return newCheckoutFlow(ctx, order)
+      }
+      return legacyCheckoutFlow(ctx, order)
+
+# =============================================================================
+# CI/CD FOR MICROSERVICES
+# =============================================================================
+
+ci_cd:
+  principles:
+    - "Independent deployability — each service has its own pipeline"
+    - "Automated testing at all levels (unit, integration, contract, E2E)"
+    - "Infrastructure as Code (Terraform, Pulumi)"
+    - "GitOps — desired state in Git, auto-sync to cluster"
+
+  pipeline_stages:
+    - name: "Build"
+      actions: ["Compile", "Lint", "Unit test"]
+    - name: "Integration Test"
+      actions: ["Contract tests", "Integration tests"]
+    - name: "Security Scan"
+      actions: ["SAST", "Container scan", "Dependency audit"]
+    - name: "Deploy Staging"
+      actions: ["Apply to staging namespace"]
+    - name: "Smoke Test"
+      actions: ["Health checks", "Critical path tests"]
+    - name: "Deploy Production"
+      actions: ["Canary → Full rollout"]
+    - name: "Post-Deploy"
+      actions: ["Monitor metrics", "Alert on anomalies"]
+
+  gitops_tools:
+    - name: ArgoCD
+      description: "Kubernetes-native GitOps"
+    - name: "Flux CD"
+      description: "CNCF project, lightweight"
+
+# =============================================================================
+# DECISION GUIDE
+# =============================================================================
+
+decision_guide:
+  strategy_selection:
+    - scenario: "Mission-critical, zero-tolerance for downtime"
+      strategy: "Blue-Green"
+
+    - scenario: "High traffic, need gradual validation"
+      strategy: "Canary"
+
+    - scenario: "Simple app, limited infrastructure budget"
+      strategy: "Rolling"
+
+    - scenario: "Business needs instant feature toggle"
+      strategy: "Feature Flags"
+
+# _DOMYH Awesome Code • Deployment Strategies_

package/.agent/skills/cross-cutting/microservices/data/event-sourcing.yaml

@@ -0,0 +1,231 @@
+# =============================================================================
+# event-sourcing.yaml — Event Sourcing Patterns
+# =============================================================================
+
+version: "1.0.0"
+
+# =============================================================================
+# CORE CONCEPT
+# =============================================================================
+
+overview:
+  description: |
+    Store state as a sequence of domain events. Current state is derived
+    by replaying events. Provides complete audit trail and temporal queries.
+
+  architecture: |
+    Command → Aggregate → Events → Event Store
+                                       ↓
+                              Projections → Read Models
+
+# =============================================================================
+# EVENT STORE
+# =============================================================================
+
+event_store:
+  schema:
+    fields:
+      - name: event_id
+        type: UUID
+        description: "Unique event identifier"
+      - name: aggregate_id
+        type: UUID
+        description: "ID of the aggregate that produced the event"
+      - name: aggregate_type
+        type: string
+        description: "Type of aggregate (e.g., 'Order', 'Account')"
+      - name: event_type
+        type: string
+        description: "Type of event (e.g., 'OrderCreated')"
+      - name: event_data
+        type: jsonb
+        description: "Serialized event payload"
+      - name: metadata
+        type: jsonb
+        description: "Correlation ID, causation ID, user ID"
+      - name: version
+        type: integer
+        description: "Aggregate version for optimistic concurrency"
+      - name: created_at
+        type: timestamp
+        description: "When the event occurred"
+
+  sql_create: |
+    CREATE TABLE events (
+        event_id       UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+        aggregate_id   UUID NOT NULL,
+        aggregate_type VARCHAR(100) NOT NULL,
+        event_type     VARCHAR(100) NOT NULL,
+        event_data     JSONB NOT NULL,
+        metadata       JSONB DEFAULT '{}',
+        version        INTEGER NOT NULL,
+        created_at     TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+
+        UNIQUE(aggregate_id, version)
+    );
+
+    CREATE INDEX idx_events_aggregate ON events(aggregate_id, version);
+    CREATE INDEX idx_events_type ON events(event_type);
+    CREATE INDEX idx_events_created ON events(created_at);
+
+  implementations:
+    - name: EventStoreDB
+      language: "Any"
+      description: "Purpose-built event store database"
+    - name: PostgreSQL + JSONB
+      language: "Any"
+      description: "Relational DB with JSON events"
+    - name: DynamoDB
+      language: "Any"
+      description: "AWS NoSQL with streams"
+    - name: Marten
+      language: "C#"
+      description: ".NET event sourcing on PostgreSQL"
+
+# =============================================================================
+# AGGREGATE PATTERN
+# =============================================================================
+
+aggregate:
+  example_go: |
+    type Order struct {
+        id      string
+        status  OrderStatus
+        items   []OrderItem
+        total   float64
+        version int
+        changes []DomainEvent // Uncommitted events
+    }
+
+    func NewOrderFromHistory(events []DomainEvent) *Order {
+        o := &Order{}
+        for _, e := range events {
+            o.apply(e)
+            o.version++
+        }
+        return o
+    }
+
+    func (o *Order) PlaceOrder(items []OrderItem) error {
+        if len(items) == 0 {
+            return ErrEmptyOrder
+        }
+        total := calculateTotal(items)
+        o.raise(OrderPlaced{
+            OrderID: o.id,
+            Items:   items,
+            Total:   total,
+        })
+        return nil
+    }
+
+    func (o *Order) raise(event DomainEvent) {
+        o.apply(event)
+        o.changes = append(o.changes, event)
+    }
+
+    func (o *Order) apply(event DomainEvent) {
+        switch e := event.(type) {
+        case OrderPlaced:
+            o.status = StatusPending
+            o.items = e.Items
+            o.total = e.Total
+        case OrderPaid:
+            o.status = StatusPaid
+        case OrderCancelled:
+            o.status = StatusCancelled
+        }
+    }
+
+# =============================================================================
+# SNAPSHOTS
+# =============================================================================
+
+snapshots:
+  purpose: |
+    Avoid replaying all events for long-lived aggregates. Periodically save
+    current state as a snapshot. Replay only events after the snapshot.
+
+  strategy:
+    frequency: "Every N events (e.g., every 100)"
+    schema:
+      - aggregate_id: UUID
+      - snapshot_data: JSONB
+      - version: INTEGER
+      - created_at: TIMESTAMP
+
+  loading_flow: |
+    1. Load latest snapshot (if exists)
+    2. Load events AFTER snapshot version
+    3. Apply events to snapshot state
+    4. → Current aggregate state
+
+  example: |
+    func (r *EventStoreRepo) Load(ctx context.Context, id string) (*Order, error) {
+        // 1. Try snapshot first
+        snapshot, err := r.loadSnapshot(ctx, id)
+        fromVersion := 0
+        var order *Order
+
+        if snapshot != nil {
+            order = snapshot.ToOrder()
+            fromVersion = snapshot.Version
+        }
+
+        // 2. Load events after snapshot
+        events, err := r.loadEvents(ctx, id, fromVersion)
+
+        // 3. Apply remaining events
+        for _, e := range events {
+            order.apply(e)
+        }
+        return order, nil
+    }
+
+# =============================================================================
+# EVENT VERSIONING
+# =============================================================================
+
+versioning:
+  strategies:
+    - name: "Upcasting"
+      description: "Transform old event format to new on read"
+      example: |
+        // v1: { amount: 100 }
+        // v2: { amount: 100, currency: "USD" }
+        func upcastV1ToV2(v1 OrderCreatedV1) OrderCreatedV2 {
+            return OrderCreatedV2{
+                Amount:   v1.Amount,
+                Currency: "USD", // Default for old events
+            }
+        }
+
+    - name: "Weak Schema"
+      description: "Use JSONB, ignore unknown fields"
+
+    - name: "New Event Type"
+      description: "Create new event type, keep old"
+      example: "OrderCreatedV2 alongside OrderCreated"
+
+# =============================================================================
+# ANTI-PATTERNS
+# =============================================================================
+
+anti_patterns:
+  - name: "Event as CRUD"
+    problem: "UserUpdated with all fields — not a domain event"
+    fix: "Use specific events: EmailChanged, AddressUpdated"
+
+  - name: "Too many events per aggregate"
+    problem: "Slow replay, memory issues"
+    fix: "Use snapshots every 100 events"
+
+  - name: "Mutable events"
+    problem: "Changing past events breaks audit trail"
+    fix: "Events are IMMUTABLE. Append corrective events instead"
+
+  - name: "Missing correlation IDs"
+    problem: "Cannot trace event chains"
+    fix: "Always include correlationId and causationId in metadata"
+
+# _DOMYH Awesome Code • Event Sourcing Patterns_

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

@@ -0,0 +1,152 @@
+# =============================================================================
+# observability.yaml — Distributed Observability Patterns
+# =============================================================================
+
+version: "1.0.0"
+
+# =============================================================================
+# THREE PILLARS
+# =============================================================================
+
+pillars:
+  logs:
+    description: "Structured, correlated log entries"
+    standards: ["JSON format", "correlation IDs", "log levels"]
+    tools: ["ELK Stack", "Grafana Loki", "Datadog Logs"]
+
+  metrics:
+    description: "Numerical measurements over time"
+    types:
+      - counter: "Only increases (requests_total)"
+      - gauge: "Goes up and down (active_connections)"
+      - histogram: "Distribution of values (request_duration)"
+      - summary: "Quantiles (p50, p95, p99)"
+    tools: ["Prometheus", "Grafana", "Datadog"]
+
+  traces:
+    description: "End-to-end request path across services"
+    concepts:
+      - trace: "Complete request journey"
+      - span: "Single operation within a trace"
+      - context: "Propagated metadata (trace_id, span_id)"
+    tools: ["Jaeger", "Zipkin", "Tempo", "Datadog APM"]
+
+# =============================================================================
+# OPENTELEMETRY
+# =============================================================================
+
+opentelemetry:
+  description: "Vendor-neutral observability framework"
+
+  components:
+    - SDK: "Instrumentation libraries per language"
+    - Collector: "Receives, processes, exports telemetry"
+    - Exporters: "Send to Jaeger, Prometheus, Datadog, etc."
+
+  go_setup: |
+    import (
+        "go.opentelemetry.io/otel"
+        "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"
+        "go.opentelemetry.io/otel/sdk/trace"
+    )
+
+    func initTracer() (*trace.TracerProvider, error) {
+        exporter, err := otlptracehttp.New(context.Background(),
+            otlptracehttp.WithEndpoint("localhost:4318"),
+            otlptracehttp.WithInsecure(),
+        )
+        if err != nil {
+            return nil, err
+        }
+        tp := trace.NewTracerProvider(
+            trace.WithBatcher(exporter),
+            trace.WithResource(resource.NewWithAttributes(
+                semconv.SchemaURL,
+                semconv.ServiceNameKey.String("order-service"),
+            )),
+        )
+        otel.SetTracerProvider(tp)
+        return tp, nil
+    }
+
+  span_example: |
+    func (s *OrderService) Create(ctx context.Context, req CreateOrderReq) (*Order, error) {
+        ctx, span := otel.Tracer("order-service").Start(ctx, "OrderService.Create")
+        defer span.End()
+
+        span.SetAttributes(
+            attribute.String("customer_id", req.CustomerID),
+            attribute.Int("item_count", len(req.Items)),
+        )
+
+        order, err := s.repo.Save(ctx, req)
+        if err != nil {
+            span.RecordError(err)
+            span.SetStatus(codes.Error, err.Error())
+            return nil, err
+        }
+
+        span.SetAttributes(attribute.String("order_id", order.ID))
+        return order, nil
+    }
+
+# =============================================================================
+# CORRELATION IDS
+# =============================================================================
+
+correlation_ids:
+  description: "Track requests across service boundaries"
+
+  headers:
+    - "X-Request-ID"
+    - "X-Correlation-ID"
+    - "traceparent (W3C standard)"
+
+  middleware_go: |
+    func CorrelationMiddleware(next http.Handler) http.Handler {
+        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+            correlationID := r.Header.Get("X-Correlation-ID")
+            if correlationID == "" {
+                correlationID = uuid.NewString()
+            }
+            ctx := context.WithValue(r.Context(), CorrelationKey, correlationID)
+            w.Header().Set("X-Correlation-ID", correlationID)
+            next.ServeHTTP(w, r.WithContext(ctx))
+        })
+    }
+
+# =============================================================================
+# HEALTH CHECKS
+# =============================================================================
+
+health_checks:
+  types:
+    - name: "Liveness"
+      path: "/healthz"
+      purpose: "Is the process alive?"
+      checks: ["Process running"]
+
+    - name: "Readiness"
+      path: "/readyz"
+      purpose: "Can the service handle traffic?"
+      checks: ["DB connected", "Cache connected", "Dependencies up"]
+
+    - name: "Startup"
+      path: "/startupz"
+      purpose: "Has the service finished initializing?"
+      checks: ["Migrations done", "Cache warmed"]
+
+  kubernetes: |
+    livenessProbe:
+      httpGet:
+        path: /healthz
+        port: 8080
+      initialDelaySeconds: 10
+      periodSeconds: 15
+    readinessProbe:
+      httpGet:
+        path: /readyz
+        port: 8080
+      periodSeconds: 5
+
+# _DOMYH Awesome Code • Observability Patterns_