@vpxa/aikit 0.1.74 → 0.1.75

package/scaffold/_preview/skills/c4-architecture/references/advanced-patterns.md

@@ -1,552 +0,0 @@
-# Advanced C4 Architecture Patterns
-
-This guide covers advanced patterns for documenting complex architectures including microservices, event-driven systems, deployments, and API documentation.
-
-## Microservices Architecture
-
-### Single Team Ownership
-
-When one team owns all microservices, model them as **containers** within a single system:
-
-```mermaid
-C4Container
-  title E-commerce Platform - Single Team
-
-  Person(customer, "Customer", "Online shopper")
-
-  System_Ext(payment, "Stripe", "Payments")
-  System_Ext(shipping, "FedEx", "Shipping")
-
-  System_Boundary(platform, "E-commerce Platform") {
-    Container(gateway, "API Gateway", "Kong", "Routing, auth, rate limiting")
-
-    Container(orderSvc, "Order Service", "Node.js", "Order processing")
-    ContainerDb(orderDb, "Order DB", "PostgreSQL", "Orders")
-
-    Container(productSvc, "Product Service", "Go", "Product catalog")
-    ContainerDb(productDb, "Product DB", "MongoDB", "Products")
-
-    Container(userSvc, "User Service", "Java", "Authentication")
-    ContainerDb(userDb, "User DB", "PostgreSQL", "Users")
-    ContainerDb(cache, "Cache", "Redis", "Sessions")
-  }
-
-  Rel(customer, gateway, "API requests", "HTTPS")
-  Rel(gateway, orderSvc, "Routes", "HTTP")
-  Rel(gateway, productSvc, "Routes", "HTTP")
-  Rel(gateway, userSvc, "Routes", "HTTP")
-
-  Rel(orderSvc, orderDb, "Persists", "SQL")
-  Rel(productSvc, productDb, "Persists", "MongoDB")
-  Rel(userSvc, userDb, "Persists", "SQL")
-  Rel(userSvc, cache, "Caches", "Redis")
-
-  Rel(orderSvc, payment, "Charges", "REST")
-  Rel(orderSvc, shipping, "Ships", "REST")
-```
-
-### Multi-Team Ownership
-
-When separate teams own microservices, **promote each to a software system**:
-
-```mermaid
-C4Context
-  title E-commerce Platform - Multi-Team
-
-  Person(customer, "Customer", "Online shopper")
-  Person(admin, "Admin", "Store manager")
-
-  Enterprise_Boundary(company, "Acme Corp") {
-    System(orderSystem, "Order System", "Team Alpha - Order lifecycle")
-    System(productSystem, "Product System", "Team Beta - Catalog management")
-    System(userSystem, "User System", "Team Gamma - Identity & auth")
-    System(analyticsSystem, "Analytics System", "Team Delta - Business intelligence")
-  }
-
-  System_Ext(payment, "Stripe", "Payment processing")
-  System_Ext(warehouse, "Warehouse System", "Fulfillment partner")
-
-  Rel(customer, orderSystem, "Places orders")
-  Rel(customer, productSystem, "Browses products")
-  Rel(admin, productSystem, "Manages catalog")
-  Rel(admin, analyticsSystem, "Views reports")
-
-  Rel(orderSystem, userSystem, "Authenticates")
-  Rel(orderSystem, productSystem, "Checks inventory")
-  Rel(orderSystem, payment, "Processes payments")
-  Rel(orderSystem, warehouse, "Fulfills orders")
-  Rel(analyticsSystem, orderSystem, "Aggregates data")
-```
-
-Each team then creates their own Container diagram:
-
-```mermaid
-C4Container
-  title Order System - Team Alpha
-
-  System_Ext(productSystem, "Product System", "Inventory checks")
-  System_Ext(userSystem, "User System", "Authentication")
-  System_Ext(payment, "Stripe", "Payments")
-
-  Container_Boundary(orderSystem, "Order System") {
-    Container(orderApi, "Order API", "Spring Boot", "REST endpoints")
-    Container(orderWorker, "Order Worker", "Spring Boot", "Async processing")
-    ContainerDb(orderDb, "Order DB", "PostgreSQL", "Order data")
-    ContainerQueue(orderQueue, "Order Queue", "RabbitMQ", "Processing queue")
-  }
-
-  Rel(orderApi, orderDb, "Reads/writes", "JDBC")
-  Rel(orderApi, orderQueue, "Publishes", "AMQP")
-  Rel(orderWorker, orderQueue, "Consumes", "AMQP")
-  Rel(orderWorker, orderDb, "Updates", "JDBC")
-
-  Rel(orderApi, userSystem, "Validates tokens", "REST")
-  Rel(orderApi, productSystem, "Reserves stock", "REST")
-  Rel(orderWorker, payment, "Charges", "REST")
-```
-
-## Event-Driven Architecture
-
-### Showing Individual Topics
-
-Always model message topics/queues as separate containers:
-
-```mermaid
-C4Container
-  title Order Processing - Event-Driven
-
-  Container(orderSvc, "Order Service", "Java", "Creates orders")
-  Container(inventorySvc, "Inventory Service", "Go", "Manages stock")
-  Container(paymentSvc, "Payment Service", "Node.js", "Processes payments")
-  Container(shippingSvc, "Shipping Service", "Python", "Creates shipments")
-  Container(notificationSvc, "Notification Service", "Python", "Sends alerts")
-
-  ContainerQueue(orderCreated, "order.created", "Kafka", "New order events")
-  ContainerQueue(stockReserved, "inventory.reserved", "Kafka", "Stock reservation events")
-  ContainerQueue(paymentComplete, "payment.completed", "Kafka", "Payment events")
-  ContainerQueue(orderShipped, "order.shipped", "Kafka", "Shipment events")
-
-  Rel(orderSvc, orderCreated, "Publishes", "Avro")
-
-  Rel(inventorySvc, orderCreated, "Consumes", "Avro")
-  Rel(inventorySvc, stockReserved, "Publishes", "Avro")
-
-  Rel(paymentSvc, stockReserved, "Consumes", "Avro")
-  Rel(paymentSvc, paymentComplete, "Publishes", "Avro")
-
-  Rel(shippingSvc, paymentComplete, "Consumes", "Avro")
-  Rel(shippingSvc, orderShipped, "Publishes", "Avro")
-
-  Rel(notificationSvc, orderCreated, "Consumes", "Avro")
-  Rel(notificationSvc, paymentComplete, "Consumes", "Avro")
-  Rel(notificationSvc, orderShipped, "Consumes", "Avro")
-
-  Rel(orderSvc, paymentComplete, "Consumes", "Avro")
-  Rel(orderSvc, orderShipped, "Consumes", "Avro")
-
-  UpdateLayoutConfig($c4ShapeInRow="4")
-```
-
-### Event Flow with Dynamic Diagram
-
-Use Dynamic diagrams to show the sequence of events:
-
-```mermaid
-C4Dynamic
-  title Order Processing Flow
-
-  Container(orderSvc, "Order Service", "Java")
-  Container(inventorySvc, "Inventory Service", "Go")
-  Container(paymentSvc, "Payment Service", "Node.js")
-  Container(shippingSvc, "Shipping Service", "Python")
-
-  ContainerQueue(orderCreated, "order.created", "Kafka")
-  ContainerQueue(stockReserved, "inventory.reserved", "Kafka")
-  ContainerQueue(paymentComplete, "payment.completed", "Kafka")
-
-  Rel(orderSvc, orderCreated, "1. Publishes order", "Avro")
-  Rel(inventorySvc, orderCreated, "2. Consumes order", "Avro")
-  Rel(inventorySvc, stockReserved, "3. Publishes reservation", "Avro")
-  Rel(paymentSvc, stockReserved, "4. Consumes reservation", "Avro")
-  Rel(paymentSvc, paymentComplete, "5. Publishes payment", "Avro")
-  Rel(shippingSvc, paymentComplete, "6. Consumes payment", "Avro")
-```
-
-### CQRS Pattern
-
-```mermaid
-C4Container
-  title CQRS Architecture
-
-  Person(user, "User", "Application user")
-
-  Container_Boundary(app, "Application") {
-    Container(commandApi, "Command API", "Java", "Write operations")
-    Container(queryApi, "Query API", "Node.js", "Read operations")
-
-    ContainerDb(writeDb, "Write DB", "PostgreSQL", "Source of truth")
-    ContainerDb(readDb, "Read DB", "Elasticsearch", "Query-optimized")
-
-    ContainerQueue(events, "Domain Events", "Kafka", "State changes")
-    Container(projector, "Projector", "Java", "Updates read model")
-  }
-
-  Rel(user, commandApi, "Commands", "HTTPS")
-  Rel(user, queryApi, "Queries", "HTTPS")
-
-  Rel(commandApi, writeDb, "Writes", "JDBC")
-  Rel(commandApi, events, "Publishes", "Avro")
-
-  Rel(projector, events, "Consumes", "Avro")
-  Rel(projector, readDb, "Updates", "REST")
-
-  Rel(queryApi, readDb, "Queries", "REST")
-```
-
-## Deployment Patterns
-
-### AWS Production Deployment
-
-```mermaid
-C4Deployment
-  title Production - AWS us-east-1
-
-  Deployment_Node(route53, "Route 53", "DNS") {
-    Container(dns, "DNS", "AWS", "api.example.com")
-  }
-
-  Deployment_Node(cloudfront, "CloudFront", "CDN") {
-    Container(cdn, "CDN", "AWS", "Static asset caching")
-  }
-
-  Deployment_Node(vpc, "VPC", "10.0.0.0/16") {
-
-    Deployment_Node(public, "Public Subnets", "Multi-AZ") {
-      Deployment_Node(alb, "ALB", "Application LB") {
-        Container(lb, "Load Balancer", "AWS ALB", "TLS termination, routing")
-      }
-    }
-
-    Deployment_Node(private, "Private Subnets", "Multi-AZ") {
-
-      Deployment_Node(ecs, "ECS Cluster", "Fargate") {
-        Container(api1, "API", "Node.js", "Instance 1")
-        Container(api2, "API", "Node.js", "Instance 2")
-        Container(worker1, "Worker", "Python", "Instance 1")
-      }
-
-      Deployment_Node(rds, "RDS", "db.r5.xlarge") {
-        ContainerDb(primary, "Primary", "PostgreSQL 14", "Multi-AZ")
-      }
-
-      Deployment_Node(elasticache, "ElastiCache", "cache.r5.large") {
-        ContainerDb(redis, "Redis", "Redis 7", "Cluster mode")
-      }
-    }
-  }
-
-  Rel(dns, cdn, "Routes to", "HTTPS")
-  Rel(cdn, lb, "Forwards", "HTTPS")
-  Rel(lb, api1, "Routes", "HTTP")
-  Rel(lb, api2, "Routes", "HTTP")
-  Rel(api1, primary, "Queries", "JDBC")
-  Rel(api2, primary, "Queries", "JDBC")
-  Rel(api1, redis, "Caches", "Redis")
-  Rel(worker1, primary, "Processes", "JDBC")
-```
-
-### Kubernetes Deployment
-
-```mermaid
-C4Deployment
-  title Production - Kubernetes
-
-  Deployment_Node(ingress, "Ingress Controller", "nginx") {
-    Container(nginx, "Nginx", "nginx-ingress", "TLS, routing")
-  }
-
-  Deployment_Node(cluster, "Kubernetes Cluster", "EKS 1.28") {
-
-    Deployment_Node(nsApp, "app namespace", "Application") {
-
-      Deployment_Node(apiDeploy, "api-deployment", "3 replicas") {
-        Container(api, "API Pod", "Node.js 20", "REST API")
-      }
-
-      Deployment_Node(workerDeploy, "worker-deployment", "2 replicas") {
-        Container(worker, "Worker Pod", "Python 3.11", "Background jobs")
-      }
-    }
-
-    Deployment_Node(nsData, "data namespace", "Databases") {
-
-      Deployment_Node(pgStateful, "postgres-statefulset", "HA") {
-        ContainerDb(pg, "PostgreSQL", "PostgreSQL 15", "Primary + Replica")
-      }
-
-      Deployment_Node(redisStateful, "redis-statefulset", "Cluster") {
-        ContainerDb(redis, "Redis", "Redis 7", "3 node cluster")
-      }
-    }
-  }
-
-  Rel(nginx, api, "Routes /api/*", "HTTP")
-  Rel(api, pg, "Queries", "JDBC")
-  Rel(api, redis, "Caches", "Redis")
-  Rel(worker, pg, "Processes", "JDBC")
-```
-
-### Multi-Region Deployment
-
-```mermaid
-C4Deployment
-  title Multi-Region Active-Active
-
-  Deployment_Node(globalLB, "Global Load Balancer", "AWS Global Accelerator") {
-    Container(glb, "GLB", "AWS", "Geographic routing")
-  }
-
-  Deployment_Node(usEast, "US-East-1", "Primary Region") {
-    Deployment_Node(usEcs, "ECS Cluster", "Fargate") {
-      Container(usApi, "API", "Node.js", "US instances")
-    }
-    Deployment_Node(usRds, "RDS", "Multi-AZ") {
-      ContainerDb(usPrimary, "Primary DB", "PostgreSQL", "Write leader")
-    }
-  }
-
-  Deployment_Node(euWest, "EU-West-1", "Secondary Region") {
-    Deployment_Node(euEcs, "ECS Cluster", "Fargate") {
-      Container(euApi, "API", "Node.js", "EU instances")
-    }
-    Deployment_Node(euRds, "RDS", "Read Replica") {
-      ContainerDb(euReplica, "Replica DB", "PostgreSQL", "Read replica")
-    }
-  }
-
-  Rel(glb, usApi, "US traffic", "HTTPS")
-  Rel(glb, euApi, "EU traffic", "HTTPS")
-  Rel(usApi, usPrimary, "Reads/writes", "JDBC")
-  Rel(euApi, euReplica, "Reads", "JDBC")
-  Rel(euApi, usPrimary, "Writes", "JDBC")
-  Rel(usPrimary, euReplica, "Replicates", "Streaming")
-```
-
-## API Documentation Patterns
-
-### API Gateway Pattern
-
-```mermaid
-C4Container
-  title API Gateway Architecture
-
-  Person(mobile, "Mobile User", "iOS/Android app user")
-  Person(web, "Web User", "Browser user")
-  Person(partner, "Partner", "Third-party integration")
-
-  Container(mobileApp, "Mobile App", "React Native", "Native mobile client")
-  Container(webApp, "Web App", "React", "SPA client")
-
-  Container_Boundary(apiPlatform, "API Platform") {
-    Container(gateway, "API Gateway", "Kong", "Auth, rate limit, routing")
-    Container(bff, "BFF", "Node.js", "Backend for frontend")
-
-    Container(userApi, "User API", "Java", "User management")
-    Container(orderApi, "Order API", "Go", "Order processing")
-    Container(productApi, "Product API", "Python", "Product catalog")
-  }
-
-  System_Ext(auth0, "Auth0", "Identity provider")
-
-  Rel(mobile, mobileApp, "Uses")
-  Rel(web, webApp, "Uses")
-  Rel(partner, gateway, "API calls", "REST/HTTPS")
-
-  Rel(mobileApp, bff, "GraphQL", "HTTPS")
-  Rel(webApp, bff, "GraphQL", "HTTPS")
-
-  Rel(bff, gateway, "REST calls", "HTTP")
-  Rel(gateway, auth0, "Validates tokens", "HTTPS")
-
-  Rel(gateway, userApi, "Routes /users/*", "HTTP")
-  Rel(gateway, orderApi, "Routes /orders/*", "HTTP")
-  Rel(gateway, productApi, "Routes /products/*", "HTTP")
-```
-
-### API Component Detail
-
-```mermaid
-C4Component
-  title Order API - Component Diagram
-
-  Container(gateway, "API Gateway", "Kong")
-  ContainerDb(db, "Order DB", "PostgreSQL")
-  ContainerQueue(events, "Order Events", "Kafka")
-  System_Ext(payment, "Payment Service", "Stripe")
-
-  Container_Boundary(orderApi, "Order API") {
-    Component(controller, "Order Controller", "Spring MVC", "REST endpoints")
-    Component(validator, "Request Validator", "Bean Validation", "Input validation")
-    Component(service, "Order Service", "Spring Service", "Business logic")
-    Component(paymentClient, "Payment Client", "Feign", "Stripe integration")
-    Component(repository, "Order Repository", "Spring Data JPA", "Data access")
-    Component(publisher, "Event Publisher", "Spring Kafka", "Event publishing")
-  }
-
-  Rel(gateway, controller, "HTTP requests", "JSON")
-  Rel(controller, validator, "Validates")
-  Rel(controller, service, "Delegates")
-  Rel(service, paymentClient, "Charges")
-  Rel(service, repository, "Persists")
-  Rel(service, publisher, "Publishes events")
-
-  Rel(paymentClient, payment, "REST", "HTTPS")
-  Rel(repository, db, "JDBC", "SQL")
-  Rel(publisher, events, "Produces", "Avro")
-```
-
-## Supplementary Diagram Patterns
-
-### Authentication Flow (Dynamic)
-
-```mermaid
-C4Dynamic
-  title OAuth2 Authorization Code Flow
-
-  Container(spa, "SPA", "React", "Web application")
-  Container(api, "API", "Node.js", "Resource server")
-  System_Ext(auth0, "Auth0", "Authorization server")
-  ContainerDb(db, "User DB", "PostgreSQL", "User data")
-
-  Rel(spa, auth0, "1. Redirect to /authorize")
-  Rel(auth0, spa, "2. Redirect with auth code")
-  Rel(spa, api, "3. Exchange code for tokens", "HTTPS")
-  Rel(api, auth0, "4. POST /oauth/token", "HTTPS")
-  Rel(api, spa, "5. Return access + refresh tokens")
-  Rel(spa, api, "6. API request with access token", "HTTPS")
-  Rel(api, db, "7. Fetch user data", "SQL")
-```
-
-### Error Handling Flow
-
-```mermaid
-C4Dynamic
-  title Error Handling - Circuit Breaker
-
-  Container(api, "API", "Node.js")
-  Container(circuitBreaker, "Circuit Breaker", "Resilience4j")
-  System_Ext(payment, "Payment Service", "Stripe")
-  ContainerDb(fallback, "Fallback Cache", "Redis")
-
-  Rel(api, circuitBreaker, "1. Request payment")
-  Rel(circuitBreaker, payment, "2. Forward request", "HTTPS")
-  Rel(payment, circuitBreaker, "3a. Success response")
-  Rel(circuitBreaker, api, "4a. Return success")
-
-  Rel(payment, circuitBreaker, "3b. Timeout/Error")
-  Rel(circuitBreaker, fallback, "4b. Check cached response")
-  Rel(circuitBreaker, api, "5b. Return fallback or error")
-```
-
-## Architecture Decision Record Integration
-
-Link C4 diagrams to Architecture Decision Records (ADRs):
-
-### ADR Reference in Diagrams
-
-```mermaid
-C4Container
-  title System Architecture
-  %% See ADR-001 for API Gateway selection
-  %% See ADR-002 for database choice
-  %% See ADR-003 for event-driven approach
-
-  Container(gateway, "API Gateway", "Kong", "ADR-001: Selected for plugin ecosystem")
-  Container(api, "Order API", "Spring Boot", "Order processing")
-  ContainerDb(db, "Order DB", "PostgreSQL", "ADR-002: ACID compliance required")
-  ContainerQueue(events, "Events", "Kafka", "ADR-003: Event sourcing pattern")
-
-  Rel(gateway, api, "Routes", "HTTP")
-  Rel(api, db, "Persists", "JDBC")
-  Rel(api, events, "Publishes", "Avro")
-```
-
-### Directory Structure
-
-Organize C4 diagrams with ADRs:
-
-```
-docs/
-├── architecture/
-│   ├── c4-context.md
-│   ├── c4-containers.md
-│   ├── c4-components-order-api.md
-│   ├── c4-deployment-production.md
-│   └── c4-dynamic-auth-flow.md
-└── decisions/
-    ├── 001-api-gateway-selection.md
-    ├── 002-database-selection.md
-    ├── 003-event-driven-architecture.md
-    └── template.md
-```
-
-## System Landscape Diagram
-
-For enterprise-level views showing multiple systems:
-
-```mermaid
-C4Context
-  title Enterprise System Landscape
-
-  Person(customer, "Customer", "External customer")
-  Person(employee, "Employee", "Internal staff")
-  Person(partner, "Partner", "Business partner")
-
-  Enterprise_Boundary(enterprise, "Acme Corporation") {
-
-    Boundary(customerFacing, "Customer-Facing", "External") {
-      System(ecommerce, "E-commerce Platform", "Online store")
-      System(mobile, "Mobile App", "Customer mobile experience")
-      System(support, "Support Portal", "Customer service")
-    }
-
-    Boundary(internal, "Internal Systems", "Operations") {
-      System(erp, "ERP System", "SAP - Finance & operations")
-      System(crm, "CRM System", "Salesforce - Customer data")
-      System(analytics, "Analytics Platform", "Business intelligence")
-    }
-
-    Boundary(integration, "Integration Layer", "Middleware") {
-      System(esb, "Integration Hub", "MuleSoft - API management")
-      System(etl, "Data Pipeline", "Airflow - Data processing")
-    }
-  }
-
-  System_Ext(payment, "Payment Gateway", "Stripe")
-  System_Ext(shipping, "Shipping Provider", "FedEx")
-  System_Ext(warehouse, "Warehouse System", "3PL Partner")
-
-  Rel(customer, ecommerce, "Shops online")
-  Rel(customer, mobile, "Uses app")
-  Rel(customer, support, "Gets help")
-  Rel(employee, erp, "Manages operations")
-  Rel(employee, crm, "Manages customers")
-  Rel(partner, esb, "API integration")
-
-  Rel(ecommerce, esb, "API calls")
-  Rel(esb, erp, "Syncs orders")
-  Rel(esb, crm, "Syncs customers")
-  Rel(esb, payment, "Processes payments")
-  Rel(esb, shipping, "Creates shipments")
-  Rel(etl, analytics, "Feeds data")
-```
-
-## Best Practices Summary
-
-1. **Choose abstraction based on ownership**: Single team = containers, Multi-team = systems
-2. **Show individual message topics**: Not a single "Kafka" or "RabbitMQ" box
-3. **Use deployment diagrams for infrastructure**: Keep container diagrams logical
-4. **Create dynamic diagrams for complex flows**: Authentication, payment, error handling
-5. **Link to ADRs**: Document why decisions were made
-6. **Use system landscape for enterprise views**: Show all systems and their relationships
-7. **Keep diagrams focused**: One concern per diagram, split when complex