tpl-superclaude/.claude/commands/design/1-system-architecture/3-integration-architecture.md

allowed-tools, description

allowed-tools	description
Read Write Glob TodoWrite	Designs system integration architecture including communication protocols, data flow, and service integration patterns.

Integration Architecture

Context

• User Request: $ARGUMENTS
• Architecture Session: Identified by --name argument (architecture session name or index).
• Source Documents: Architecture framework and component design documents from the session directory.
• Integration Scope: Optional --scope argument to focus on specific integration areas.
• Design Directory: .taskmaster/docs/design/architecture/

Goal

To design comprehensive integration architecture that defines how system components communicate, share data, and coordinate operations, ensuring reliable, scalable, and maintainable inter-component and external system integration.

Process

1. Identify Source Architecture Session:

   • Use the --name argument to locate the correct architecture session directory (e.g., .taskmaster/docs/design/architecture/001-enterprise-expansion/).
   • Find the architecture framework document (architecture-framework_*.md) and component design document (component-design_*.md).

2. Extract Integration Requirements:

   • Component Dependencies: Component interaction patterns and dependencies
   • Data Flow Requirements: Data sharing and synchronization needs
   • External Integrations: Third-party services and system integrations
   • Communication Patterns: Synchronous vs asynchronous communication needs
   • Quality Attributes: Performance, reliability, and security requirements for integrations

3. Process Integration Scope (if specified):

   • If --scope argument is provided, focus on specific integration areas
   • Supported scopes: internal, external, data, messaging, api
   • Parse and validate scope parameters

4. Analyze Integration Patterns:

   • Communication Analysis: Identify optimal communication patterns for each interaction
   • Data Flow Analysis: Design data flow and transformation patterns
   • Transaction Analysis: Determine transaction boundaries and coordination patterns
   • Error Handling Analysis: Design error propagation and recovery patterns
   • Security Analysis: Define security requirements for each integration point

5. Design Integration Architecture:

   • Communication Protocols: Define protocols for component communication
   • API Design: Design REST APIs, GraphQL schemas, and RPC interfaces
   • Messaging Architecture: Design message queues, event streams, and pub/sub patterns
   • Data Integration: Design data synchronization, ETL, and data flow patterns
   • Service Integration: Design service discovery, load balancing, and circuit breaker patterns

6. Define Integration Contracts:

   • API Contracts: Define API specifications and data models
   • Message Contracts: Define message formats and event schemas
   • Data Contracts: Define data formats and transformation rules
   • Service Contracts: Define service level agreements and quality metrics

7. Generate Integration Architecture Document:

   • Create the integration architecture document named integration-architecture_[architecture_session_name].md.
   • Structure content according to the integration architecture template.
   • Include:
     • Integration Overview: High-level integration strategy and patterns
     • Communication Architecture: Communication protocols and patterns
     • Data Integration Architecture: Data flow and synchronization patterns
     • Service Integration Architecture: Service discovery and coordination patterns
     • Security Architecture: Security patterns and access control
     • Monitoring and Observability: Integration monitoring and troubleshooting

8. Create Integration Specifications:

   • Generate detailed API specifications and documentation
   • Create message schema definitions and event catalogs
   • Define data transformation and mapping specifications
   • Document integration testing and validation approaches

9. Update Architecture Session State:

   • Update the existing _session-state.json file in the architecture session directory.
   • Add integration architecture completion status and results.
   • Update completedSteps and nextAction fields.

10. Notify User with Integration Insights:

    • Inform the user that the integration architecture has been successfully generated.
    • Provide file paths and key integration highlights.
    • Suggest logical next steps based on integration architecture:
      • "Your integration architecture is complete. Consider generating a comprehensive architecture summary using /design/system-architecture/4-generate-architecture-summary --name=[session_name]"
      • "Review the integration patterns with your development teams to ensure implementation feasibility."
      • "Use the API specifications to begin contract-first development and testing."

Templates & Structures

Integration Architecture Template

# Integration Architecture: [Architecture Session Name]

**Created:** [Date]  
**Source:** Architecture Framework and Component Design: [Architecture Session Name]  
**Integration Scope:** [Full System / Internal / External / Data / Messaging / API]  
**Target Integrations:** [List of specific integrations if scoped]  
**Last Updated:** [Date]

---

## Integration Overview

### Integration Strategy
- **Integration Philosophy:** [Overall approach to system integration]
- **Communication Strategy:** [Synchronous vs asynchronous communication strategy]
- **Data Strategy:** [Data sharing and consistency approach]
- **Service Strategy:** [Service discovery and coordination approach]

### Integration Patterns
- **Primary Patterns:** [Main integration patterns used in the system]
- **Secondary Patterns:** [Supporting integration patterns]
- **Anti-Patterns:** [Patterns to avoid and why]
- **Pattern Selection Criteria:** [How to choose appropriate patterns]

### Integration Architecture Principles
- **Loose Coupling:** [Minimize dependencies between components]
- **High Cohesion:** [Keep related functionality together]
- **Fault Tolerance:** [Handle failures gracefully]
- **Scalability:** [Support system growth and load]
- **Security:** [Protect data and communications]

### Integration Landscape
- **Internal Integrations:** [Component-to-component communications]
- **External Integrations:** [Third-party service integrations]
- **Data Integrations:** [Database and data store integrations]
- **User Integrations:** [User interface and client integrations]

---

## Communication Architecture

### Synchronous Communication

#### HTTP/REST API Communication
##### Design Principles
- **RESTful Design:** [RESTful API design principles and conventions]
- **Resource Modeling:** [How resources are modeled and exposed]
- **HTTP Methods:** [Proper use of HTTP methods and status codes]
- **Content Negotiation:** [Support for multiple content types]

##### API Gateway Pattern
- **Gateway Responsibility:** [API gateway roles and responsibilities]
- **Routing:** [Request routing and load balancing]
- **Authentication:** [Centralized authentication and authorization]
- **Rate Limiting:** [Request throttling and quota management]
- **Monitoring:** [API usage monitoring and analytics]

##### API Specification
```yaml
# OpenAPI 3.0 Specification for Service Integration
openapi: 3.0.0
info:
  title: System Integration API
  version: 1.0.0
  description: API for system component integration

servers:
  - url: https://api.example.com/v1
    description: Production server
  - url: https://staging-api.example.com/v1
    description: Staging server

paths:
  /components/{componentId}/status:
    get:
      summary: Get component status
      parameters:
        - name: componentId
          in: path
          required: true
          schema:
            type: string
          description: Component identifier
      responses:
        '200':
          description: Component status retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComponentStatus'
        '404':
          description: Component not found
        '500':
          description: Internal server error

  /components/{componentId}/health:
    get:
      summary: Get component health
      parameters:
        - name: componentId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Component health retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthStatus'

components:
  schemas:
    ComponentStatus:
      type: object
      properties:
        componentId:
          type: string
        status:
          type: string
          enum: [running, stopped, error]
        timestamp:
          type: string
          format: date-time
        version:
          type: string
    
    HealthStatus:
      type: object
      properties:
        healthy:
          type: boolean
        checks:
          type: array
          items:
            $ref: '#/components/schemas/HealthCheck'
    
    HealthCheck:
      type: object
      properties:
        name:
          type: string
        status:
          type: string
          enum: [pass, fail, warn]
        details:
          type: string

  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  - BearerAuth: []

gRPC Communication

Service Definition

// Component Service Definition
syntax = "proto3";

package component.v1;

service ComponentService {
  rpc GetStatus(GetStatusRequest) returns (GetStatusResponse);
  rpc HealthCheck(HealthCheckRequest) returns (HealthCheckResponse);
  rpc ProcessCommand(ProcessCommandRequest) returns (ProcessCommandResponse);
}

message GetStatusRequest {
  string component_id = 1;
}

message GetStatusResponse {
  string component_id = 1;
  ComponentStatus status = 2;
  string version = 3;
  int64 timestamp = 4;
}

message HealthCheckRequest {
  string component_id = 1;
}

message HealthCheckResponse {
  bool healthy = 1;
  repeated HealthCheck checks = 2;
}

message ProcessCommandRequest {
  string component_id = 1;
  string command = 2;
  map<string, string> parameters = 3;
}

message ProcessCommandResponse {
  bool success = 1;
  string result = 2;
  string error_message = 3;
}

enum ComponentStatus {
  UNKNOWN = 0;
  RUNNING = 1;
  STOPPED = 2;
  ERROR = 3;
}

message HealthCheck {
  string name = 1;
  HealthStatus status = 2;
  string details = 3;
}

enum HealthStatus {
  PASS = 0;
  FAIL = 1;
  WARN = 2;
}

Asynchronous Communication

Message Queue Architecture

Message Broker Selection

• Technology Choice: [RabbitMQ/Apache Kafka/Amazon SQS selection criteria]
• Topology: [Message routing and queue topology]
• Durability: [Message persistence and reliability guarantees]
• Scalability: [Horizontal scaling and partitioning strategy]

Message Patterns

• Point-to-Point: [Direct message passing between components]
• Publish-Subscribe: [Event broadcasting to multiple subscribers]
• Request-Reply: [Asynchronous request-response patterns]
• Message Routing: [Content-based and topic-based routing]

Message Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "System Event Message",
  "type": "object",
  "properties": {
    "messageId": {
      "type": "string",
      "format": "uuid",
      "description": "Unique message identifier"
    },
    "eventType": {
      "type": "string",
      "description": "Type of event being communicated"
    },
    "source": {
      "type": "string",
      "description": "Source component that generated the event"
    },
    "timestamp": {
      "type": "string",
      "format": "date-time",
      "description": "When the event occurred"
    },
    "correlationId": {
      "type": "string",
      "description": "Correlation ID for tracking related events"
    },
    "payload": {
      "type": "object",
      "description": "Event-specific data payload"
    },
    "metadata": {
      "type": "object",
      "properties": {
        "version": {
          "type": "string",
          "description": "Message schema version"
        },
        "priority": {
          "type": "string",
          "enum": ["low", "normal", "high", "critical"]
        },
        "retryCount": {
          "type": "integer",
          "minimum": 0
        }
      }
    }
  },
  "required": ["messageId", "eventType", "source", "timestamp", "payload"]
}

Event Streaming Architecture

Event Store Design

• Event Schema: [Event structure and versioning strategy]
• Event Ordering: [Event ordering and sequence guarantees]
• Event Replay: [Event replay and reprocessing capabilities]
• Event Retention: [Event storage and retention policies]

Event Processing

• Stream Processing: [Real-time event stream processing]
• Event Sourcing: [Event-driven state reconstruction]
• CQRS Integration: [Command Query Responsibility Segregation]
• Event Projection: [Event-to-read-model projections]

---

Data Integration Architecture

Data Flow Patterns

Data Synchronization

Master Data Management

• Master Data Domains: [Identification of master data entities]
• Data Ownership: [Clear ownership and responsibility for data]
• Data Quality: [Data validation and quality assurance]
• Data Governance: [Data lifecycle and change management]

Data Consistency Patterns

• Strong Consistency: [ACID transactions and immediate consistency]
• Eventual Consistency: [BASE transactions and eventual consistency]
• Causal Consistency: [Causal ordering and dependencies]
• Session Consistency: [Per-session consistency guarantees]

Data Transformation

ETL/ELT Patterns

• Extract: [Data extraction from source systems]
• Transform: [Data transformation and enrichment]
• Load: [Data loading into target systems]
• Orchestration: [Data pipeline orchestration and scheduling]

Data Pipeline Architecture

# Data Pipeline Configuration
apiVersion: v1
kind: ConfigMap
metadata:
  name: data-pipeline-config
data:
  pipeline.yaml: |
    name: customer-data-pipeline
    description: Customer data synchronization pipeline
    
    sources:
      - name: customer-db
        type: postgresql
        connection: ${CUSTOMER_DB_CONNECTION}
        query: |
          SELECT customer_id, name, email, created_at, updated_at
          FROM customers
          WHERE updated_at > ${LAST_SYNC_TIME}
    
    transformations:
      - name: data-validation
        type: validation
        rules:
          - field: email
            rule: email_format
          - field: name
            rule: not_empty
      
      - name: data-enrichment
        type: enrichment
        enrichments:
          - field: customer_segment
            source: customer-segmentation-service
            key: customer_id
    
    destinations:
      - name: customer-warehouse
        type: bigquery
        table: analytics.customers
        mode: upsert
        key: customer_id
      
      - name: customer-cache
        type: redis
        key_pattern: customer:${customer_id}
        ttl: 3600
    
    schedule:
      type: cron
      expression: "0 */15 * * * *"
    
    monitoring:
      success_rate_threshold: 0.95
      latency_threshold: 300
      alert_channels:
        - email: data-team@company.com
        - slack: #data-alerts

Database Integration

Multi-Database Architecture

Database per Service

• Database Ownership: [Each service owns its database]
• Data Isolation: [Strong data boundaries between services]
• Technology Choice: [Service-specific database selection]
• Schema Evolution: [Independent schema evolution]

Shared Database Challenges

• Schema Coupling: [Managing shared schema changes]
• Performance Impact: [Handling concurrent access]
• Data Consistency: [Maintaining consistency across services]
• Migration Strategy: [Transitioning from shared to service databases]

Database Synchronization

Change Data Capture (CDC)

• CDC Technology: [Debezium/AWS DMS/Custom CDC selection]
• Change Events: [Database change event processing]
• Event Ordering: [Maintaining change order and consistency]
• Failure Recovery: [Handling CDC failures and recovery]

Database Replication

• Replication Strategy: [Master-slave/Master-master replication]
• Consistency Model: [Strong/Eventual consistency guarantees]
• Conflict Resolution: [Handling replication conflicts]
• Performance Impact: [Replication overhead and optimization]

---

Service Integration Architecture

Service Discovery

Service Registry Pattern

Registry Technology

• Registry Choice: [Consul/Eureka/Kubernetes DNS selection]
• Service Registration: [Automatic vs manual service registration]
• Health Checking: [Service health monitoring and reporting]
• Load Balancing: [Service discovery integration with load balancers]

Service Discovery Flow

graph LR
    A[Service Instance] -->|Register| B[Service Registry]
    C[Client Service] -->|Discover| B
    B -->|Return Endpoints| C
    C -->|Call Service| D[Target Service]
    D -->|Health Check| B

Circuit Breaker Pattern

Circuit Breaker Implementation

• Failure Threshold: [Failure rate threshold for circuit opening]
• Timeout Configuration: [Request timeout and circuit timeout]
• Fallback Strategy: [Fallback behavior when circuit is open]
• Recovery Strategy: [Circuit recovery and half-open state]

Circuit Breaker Configuration

# Circuit Breaker Configuration
circuitBreaker:
  services:
    - name: payment-service
      failureThreshold: 5
      timeoutMillis: 5000
      resetTimeoutMillis: 30000
      fallback:
        type: cached_response
        cache_ttl: 300
    
    - name: user-service
      failureThreshold: 3
      timeoutMillis: 3000
      resetTimeoutMillis: 60000
      fallback:
        type: default_response
        response: |
          {
            "error": "User service temporarily unavailable",
            "code": "SERVICE_UNAVAILABLE"
          }

Load Balancing

Load Balancing Strategies

Client-Side Load Balancing

• Load Balancer Libraries: [Client-side load balancing libraries]
• Load Balancing Algorithms: [Round-robin/Weighted/Least connections]
• Health Awareness: [Health-aware load balancing]
• Sticky Sessions: [Session affinity and stickiness]

Server-Side Load Balancing

• Load Balancer Technology: [HAProxy/NGINX/AWS ALB selection]
• Traffic Distribution: [Traffic routing and distribution rules]
• SSL Termination: [SSL/TLS termination and encryption]
• Geographic Routing: [Geographic traffic routing]

API Gateway Integration

Gateway Responsibilities

• Request Routing: [Route requests to appropriate services]
• Authentication: [Centralized authentication and token validation]
• Rate Limiting: [Request throttling and quota management]
• Request/Response Transformation: [Data transformation and enrichment]
• Monitoring: [Request monitoring and analytics]

Gateway Configuration

# API Gateway Configuration
apiVersion: networking.istio.io/v1beta1
kind: Gateway
metadata:
  name: system-gateway
spec:
  selector:
    istio: ingressgateway
  servers:
  - port:
      number: 443
      name: https
      protocol: HTTPS
    tls:
      mode: SIMPLE
      credentialName: system-tls-cert
    hosts:
    - api.example.com
    
---
apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: system-virtual-service
spec:
  hosts:
  - api.example.com
  gateways:
  - system-gateway
  http:
  - match:
    - uri:
        prefix: /api/v1/users
    route:
    - destination:
        host: user-service
        port:
          number: 8080
    fault:
      delay:
        percentage:
          value: 0.1
        fixedDelay: 5s
    retries:
      attempts: 3
      perTryTimeout: 2s
  
  - match:
    - uri:
        prefix: /api/v1/orders
    route:
    - destination:
        host: order-service
        port:
          number: 8080
    timeout: 10s

---

Security Architecture

Authentication and Authorization

Identity and Access Management

Authentication Flow

• Authentication Methods: [JWT/OAuth2/SAML authentication]
• Token Management: [Token generation, validation, and refresh]
• Multi-Factor Authentication: [MFA implementation and enforcement]
• Session Management: [Session creation, maintenance, and termination]

Authorization Patterns

• Role-Based Access Control (RBAC): [Role and permission management]
• Attribute-Based Access Control (ABAC): [Attribute-based permissions]
• Policy-Based Access Control: [Policy engine and rule evaluation]
• Resource-Based Access Control: [Resource-level permissions]

Security Communication

Transport Security

• TLS/SSL Configuration: [Transport layer security configuration]
• Certificate Management: [Certificate lifecycle and rotation]
• Mutual TLS (mTLS): [Service-to-service authentication]
• Certificate Pinning: [Certificate pinning for enhanced security]

Message Security

• Message Encryption: [End-to-end message encryption]
• Message Signing: [Message integrity and authenticity]
• Key Management: [Encryption key lifecycle and rotation]
• Secure Headers: [HTTP security headers and CORS]

Data Protection

Data Encryption

Encryption at Rest

• Database Encryption: [Database-level encryption]
• File System Encryption: [File system and storage encryption]
• Key Management Service: [Centralized key management]
• Encryption Standards: [Encryption algorithms and key sizes]

Encryption in Transit

• Network Encryption: [Network-level encryption protocols]
• Application Encryption: [Application-level encryption]
• API Encryption: [API payload encryption]
• Message Encryption: [Message queue encryption]

Data Privacy

Privacy Controls

• Data Minimization: [Collect and process only necessary data]
• Data Anonymization: [Data anonymization and pseudonymization]
• Consent Management: [User consent tracking and management]
• Data Retention: [Data retention and deletion policies]

Compliance Requirements

• GDPR Compliance: [European data protection regulation compliance]
• CCPA Compliance: [California consumer privacy act compliance]
• Industry Standards: [Industry-specific compliance requirements]
• Audit Trails: [Comprehensive audit logging and monitoring]

---

Monitoring and Observability

Integration Monitoring

Metrics Collection

System Metrics

• Performance Metrics: [Response time, throughput, error rates]
• Resource Metrics: [CPU, memory, disk, network utilization]
• Application Metrics: [Business-specific metrics and KPIs]
• Integration Metrics: [Service dependencies and communication metrics]

Monitoring Stack

# Monitoring Configuration
monitoring:
  prometheus:
    enabled: true
    retention: 15d
    storage: 100Gi
    
    targets:
      - job_name: 'system-services'
        static_configs:
          - targets: ['user-service:8080', 'order-service:8080']
        metrics_path: '/metrics'
        scrape_interval: 15s
      
      - job_name: 'api-gateway'
        static_configs:
          - targets: ['api-gateway:9090']
        metrics_path: '/actuator/prometheus'
        scrape_interval: 10s
  
  grafana:
    enabled: true
    dashboards:
      - name: 'System Overview'
        panels:
          - title: 'Request Rate'
            type: graph
            targets:
              - expr: 'rate(http_requests_total[5m])'
          - title: 'Error Rate'
            type: graph
            targets:
              - expr: 'rate(http_requests_total{status=~"5.."}[5m])'
          - title: 'Response Time'
            type: graph
            targets:
              - expr: 'histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m]))'
  
  alerting:
    rules:
      - alert: HighErrorRate
        expr: rate(http_requests_total{status=~"5.."}[5m]) > 0.1
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "High error rate detected"
          description: "Error rate is above 10% for 5 minutes"
      
      - alert: ServiceDown
        expr: up == 0
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: "Service is down"
          description: "Service {{ $labels.instance }} is down"

Distributed Tracing

Tracing Implementation

• Tracing Technology: [Jaeger/Zipkin/OpenTelemetry selection]
• Trace Sampling: [Sampling strategies and configuration]
• Span Correlation: [Request correlation across services]
• Trace Analysis: [Trace analysis and performance insights]

Tracing Configuration

# OpenTelemetry Configuration
apiVersion: v1
kind: ConfigMap
metadata:
  name: otel-config
data:
  config.yaml: |
    receivers:
      otlp:
        protocols:
          grpc:
            endpoint: 0.0.0.0:4317
          http:
            endpoint: 0.0.0.0:4318
    
    processors:
      batch:
        timeout: 1s
        send_batch_size: 1024
      
      resource:
        attributes:
          - key: service.name
            value: system-service
            action: upsert
    
    exporters:
      jaeger:
        endpoint: jaeger-collector:14250
        tls:
          insecure: true
      
      prometheus:
        endpoint: "0.0.0.0:8889"
    
    service:
      pipelines:
        traces:
          receivers: [otlp]
          processors: [resource, batch]
          exporters: [jaeger]
        
        metrics:
          receivers: [otlp]
          processors: [resource, batch]
          exporters: [prometheus]

Logging and Auditing

Centralized Logging

Log Aggregation

• Logging Technology: [ELK Stack/Fluentd/Splunk selection]
• Log Structure: [Structured logging and log format standards]
• Log Correlation: [Log correlation across services]
• Log Retention: [Log retention and archival policies]

Logging Configuration

# Logging Configuration
logging:
  level: INFO
  
  appenders:
    - name: console
      type: console
      layout:
        type: json
        fields:
          - timestamp
          - level
          - logger
          - message
          - mdc
          - exception
    
    - name: file
      type: file
      file: /var/log/application.log
      layout:
        type: json
        fields:
          - timestamp
          - level
          - logger
          - message
          - mdc
          - exception
    
    - name: elasticsearch
      type: elasticsearch
      hosts:
        - elasticsearch:9200
      index: application-logs
      layout:
        type: json
  
  loggers:
    - name: com.example.integration
      level: DEBUG
      appenders: [console, file, elasticsearch]
    
    - name: com.example.security
      level: INFO
      appenders: [console, file, elasticsearch]
  
  correlation:
    enabled: true
    header_names:
      - X-Correlation-ID
      - X-Request-ID

Audit Logging

Audit Requirements

• Audit Events: [Security, data access, and system events]
• Audit Data: [User, timestamp, action, and resource information]
• Audit Storage: [Secure audit log storage and retention]
• Audit Reporting: [Audit analysis and compliance reporting]

---

Performance and Scalability

Performance Optimization

Caching Strategies

Multi-Level Caching

• L1 Cache: [In-memory application caching]
• L2 Cache: [Distributed caching (Redis/Memcached)]
• L3 Cache: [Database query result caching]
• CDN Cache: [Content delivery network caching]

Cache Management

• Cache Invalidation: [Cache invalidation strategies and policies]
• Cache Warming: [Proactive cache population]
• Cache Monitoring: [Cache hit rates and performance monitoring]
• Cache Consistency: [Cache consistency and synchronization]

Database Performance

Query Optimization

• Index Strategy: [Database indexing and optimization]
• Query Patterns: [Efficient query design and execution]
• Connection Pooling: [Database connection management]
• Read Replicas: [Read scaling with database replicas]

Database Scaling

• Horizontal Scaling: [Database sharding and partitioning]
• Vertical Scaling: [Database resource scaling]
• Multi-Region: [Multi-region database deployment]
• Failover: [Database failover and disaster recovery]

Scalability Architecture

Horizontal Scaling

Auto-Scaling

• Scaling Triggers: [CPU, memory, and custom metric triggers]
• Scaling Policies: [Scale-up and scale-down policies]
• Load Testing: [Performance testing and capacity planning]
• Resource Limits: [Resource quotas and limits]

Container Orchestration

# Kubernetes Deployment with Auto-Scaling
apiVersion: apps/v1
kind: Deployment
metadata:
  name: user-service
spec:
  replicas: 3
  selector:
    matchLabels:
      app: user-service
  template:
    metadata:
      labels:
        app: user-service
    spec:
      containers:
      - name: user-service
        image: user-service:latest
        ports:
        - containerPort: 8080
        resources:
          requests:
            cpu: 100m
            memory: 128Mi
          limits:
            cpu: 500m
            memory: 512Mi
        livenessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /ready
            port: 8080
          initialDelaySeconds: 5
          periodSeconds: 5

---
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: user-service-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: user-service
  minReplicas: 3
  maxReplicas: 10
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 70
  - type: Resource
    resource:
      name: memory
      target:
        type: Utilization
        averageUtilization: 80

---

Disaster Recovery and Business Continuity

Backup and Recovery

Data Backup Strategy

Backup Types

• Full Backup: [Complete data backup procedures]
• Incremental Backup: [Incremental change backup]
• Differential Backup: [Differential change backup]
• Continuous Backup: [Real-time backup and replication]

Recovery Procedures

• Recovery Time Objective (RTO): [Maximum acceptable downtime]
• Recovery Point Objective (RPO): [Maximum acceptable data loss]
• Backup Testing: [Regular backup validation and testing]
• Recovery Automation: [Automated recovery procedures]

High Availability

Redundancy Patterns

• Active-Active: [Active-active deployment pattern]
• Active-Passive: [Active-passive deployment pattern]
• Multi-Region: [Multi-region deployment strategy]
• Failover: [Automated failover mechanisms]

Health Monitoring

• Health Checks: [Comprehensive health monitoring]
• Failure Detection: [Automated failure detection]
• Alert Systems: [Incident notification and escalation]
• Recovery Automation: [Automated recovery procedures]

---

Next Steps

Implementation Planning

1. Integration Development: [Plan integration implementation order]
2. API Development: [Implement API contracts and specifications]
3. Message Infrastructure: [Set up messaging and event infrastructure]
4. Security Implementation: [Implement security and authentication]

Testing and Validation

1. Integration Testing: [Test component integration patterns]
2. Performance Testing: [Validate performance requirements]
3. Security Testing: [Test security implementations]
4. Disaster Recovery Testing: [Test backup and recovery procedures]

Operations Preparation

1. Monitoring Setup: [Implement monitoring and observability]
2. Deployment Automation: [Set up CI/CD and deployment automation]
3. Documentation: [Create operational documentation]
4. Training: [Train teams on integration patterns and operations]

---

Appendices

A. Integration Patterns Catalog

[Comprehensive catalog of integration patterns with implementation guidance]

B. API Specifications

[Complete API specifications and documentation]

C. Message Schema Registry

[Message schema definitions and versioning]

D. Performance Benchmarks

[Performance testing results and benchmarks]

E. Security Assessment

[Security analysis and threat modeling results]

F. Operational Runbooks

[Operational procedures and troubleshooting guides]

### Updated Session State Structure
```json
{
  "index": 1,
  "name": "architecture-session-name",
  "type": "architecture",
  "status": "integration_architecture_complete",
  "created": "ISO datetime",
  "lastUpdated": "ISO datetime",
  "currentStep": "integration_architecture",
  "completedSteps": ["architecture_framework_creation", "domain_analysis", "layer_design", "component_design", "integration_architecture"],
  "nextAction": "Ready for architecture summary generation",
  "sourceType": "prd",
  "sourceName": "prd-session-name",
  "architectureScope": "system-wide",
  "architectureStyle": "layered",
  "architectureResults": {
    "domains": 3,
    "layers": 4,
    "components": 12,
    "componentSpecs": 12,
    "interfaces": 24,
    "integrationPatterns": 15,
    "apiSpecs": 8,
    "messageSchemas": 6,
    "patterns": 8,
    "qualityAttributes": 5,
    "decisions": 6,
    "createdDate": "ISO datetime",
    "componentDesignDate": "ISO datetime",
    "integrationArchitectureDate": "ISO datetime"
  }
}

Best Practices

✅ DO: Integration-First Design

• Design integration patterns before implementing individual components
• Use contract-first approach for all service interactions
• Plan for failure scenarios and implement resilience patterns
• Consider operational requirements from the design phase

Why: Integration-first design prevents integration problems and ensures system reliability and maintainability.

✅ DO: Observability by Design

• Build in monitoring and logging from the beginning
• Use distributed tracing for end-to-end visibility
• Implement comprehensive health checks for all services
• Plan for troubleshooting and debugging scenarios

Why: Observability by design enables effective monitoring, debugging, and maintenance of complex distributed systems.

✅ DO: Security by Design

• Implement security at every integration point
• Use defense in depth with multiple security layers
• Follow principle of least privilege for all access controls
• Plan for security incident response and recovery

Why: Security by design prevents security vulnerabilities and ensures compliance with security requirements.

❌ DON'T: Ignore Network Realities

• Don't assume network reliability - plan for network failures
• Don't ignore latency - consider network latency in design
• Don't forget about bandwidth - plan for data transfer costs
• Don't ignore security - secure all network communications

Why: Ignoring network realities leads to unreliable systems that fail under real-world conditions.

❌ DON'T: Create Tight Coupling

• Don't create direct dependencies between unrelated components
• Don't share databases across service boundaries
• Don't use shared libraries for business logic
• Don't ignore service boundaries when designing integrations

Why: Tight coupling reduces system flexibility, increases complexity, and makes systems harder to maintain and evolve.

Output

• Format: Comprehensive integration architecture with communication protocols and patterns
• Location: .taskmaster/docs/design/architecture/[index]-[architecture_session_name]/
• Primary Files:
  • integration-architecture_[architecture_session_name].md - Main integration architecture document
  • _session-state.json - Updated session state

Example Usage

• Design full integration architecture: /design/system-architecture/3-integration-architecture --name="enterprise-expansion"
• Design specific integration scope: /design/system-architecture/3-integration-architecture --name="enterprise-expansion" --scope="external"
• Design by architecture index: /design/system-architecture/3-integration-architecture --name="1" --scope="api"