BMAD-METHOD/bmad-agent/tasks/generate-integration-documentation.md

# Generate Integration Documentation Task

## Purpose

To create comprehensive integration documentation that enables seamless communication between different technology platforms (React, TypeScript, Node.js, ASP.NET, Python). This documentation will serve as the definitive guide for implementing cross-platform integrations with proper security, performance, and reliability considerations.

## Inputs

- **Source Platform**: Technology stack initiating the integration
- **Target Platform**: Technology stack receiving the integration  
- **Communication Protocol**: REST, GraphQL, gRPC, WebSocket, Message Queue
- **Authentication Method**: JWT, OAuth, API Key, Certificate-based
- **Data Requirements**: Payload structure, validation rules, transformation needs
- **Performance Requirements**: Latency, throughput, scalability targets
- **Security Requirements**: Compliance standards, encryption needs

## Key Activities & Instructions

### 1. Integration Architecture Analysis

- Analyze the source and target platforms for compatibility
- Identify optimal communication protocols for the use case
- Determine authentication and authorization requirements
- Map data flow and transformation requirements
- Assess performance and scalability considerations

### 2. Protocol Selection & Design

- **REST API Integration:**
  - Design RESTful endpoints with proper HTTP methods
  - Define request/response schemas with validation
  - Implement proper error handling and status codes
  - Design pagination and filtering strategies

- **GraphQL Integration:**
  - Design GraphQL schema with proper types and resolvers
  - Implement subscription patterns for real-time data
  - Design federation strategies for distributed schemas
  - Optimize query performance and caching

- **gRPC Integration:**
  - Define Protocol Buffer schemas
  - Design service definitions with streaming support
  - Implement load balancing and service discovery
  - Configure health checking and monitoring

### 3. Authentication & Security Implementation

- **JWT Token Integration:**
\```typescript
interface JWTPayload {
  sub: string;
  iat: number;
  exp: number;
  aud: string[];
  scope: string[];
}

class CrossPlatformAuth {
  validateToken(token: string): Promise<JWTPayload>;
  refreshToken(refreshToken: string): Promise<string>;
  revokeToken(token: string): Promise<void>;
}
```

- **OAuth 2.0 Flow Implementation:**
```csharp
public interface IOAuthService
{
    Task<AuthorizationResult> AuthorizeAsync(string clientId, string[] scopes);
    Task<TokenResponse> ExchangeCodeAsync(string code, string clientId);
    Task<TokenResponse> RefreshTokenAsync(string refreshToken);
}
```

### 4. Data Transformation & Validation

- **Cross-Platform Data Models:**
```python
from pydantic import BaseModel
from typing import Optional, List
from datetime import datetime

class CrossPlatformEntity(BaseModel):
    id: str
    created_at: datetime
    updated_at: Optional[datetime]
    metadata: dict
    
    class Config:
        json_encoders = {
            datetime: lambda v: v.isoformat()
        }
```

- **Validation Patterns:**
\```typescript
import { z } from 'zod';

const CrossPlatformSchema = z.object({
  id: z.string().uuid(),
  createdAt: z.string().datetime(),
  updatedAt: z.string().datetime().optional(),
  metadata: z.record(z.unknown())
});

type CrossPlatformEntity = z.infer<typeof CrossPlatformSchema>;
```

### 5. Error Handling & Resilience

- **Standardized Error Responses:**
\```json
{
  "error": {
    "code": "INTEGRATION_ERROR",
    "message": "Human-readable error message",
    "details": {
      "platform": "source_platform",
      "timestamp": "2024-01-01T00:00:00Z",
      "trace_id": "uuid",
      "context": {}
    }
  }
}
```

- **Retry Logic Implementation:**
\```typescript
class IntegrationClient {
  async callWithRetry<T>(
    operation: () => Promise<T>,
    maxRetries: number = 3,
    backoffMs: number = 1000
  ): Promise<T> {
    // Exponential backoff retry implementation
  }
}
```

### 6. Performance Optimization

- **Caching Strategies:**
  - Implement appropriate caching layers (Redis, in-memory)
  - Design cache invalidation strategies
  - Configure cache TTL based on data volatility
  - Implement cache warming for critical data

- **Connection Pooling:**
```csharp
public class ConnectionPoolConfig
{
    public int MaxConnections { get; set; } = 100;
    public TimeSpan ConnectionTimeout { get; set; } = TimeSpan.FromSeconds(30);
    public TimeSpan IdleTimeout { get; set; } = TimeSpan.FromMinutes(5);
    public bool EnableHealthChecks { get; set; } = true;
}
```

### 7. Monitoring & Observability

- **Integration Metrics:**
\```typescript
interface IntegrationMetrics {
  requestCount: number;
  errorRate: number;
  averageLatency: number;
  p95Latency: number;
  p99Latency: number;
  activeConnections: number;
}
```

- **Distributed Tracing:**
```python
from opentelemetry import trace
from opentelemetry.exporter.jaeger.thrift import JaegerExporter

def setup_tracing(service_name: str):
    tracer = trace.get_tracer(__name__)
    jaeger_exporter = JaegerExporter(
        agent_host_name="localhost",
        agent_port=6831,
    )
    # Configure tracing
```

### 8. Testing Strategy Implementation

- **Integration Test Framework:**
\```typescript
describe('Cross-Platform Integration', () => {
  beforeAll(async () => {
    // Setup test environment
  });

  test('should handle successful integration', async () => {
    // Test successful integration scenario
  });

  test('should handle authentication failures', async () => {
    // Test authentication error scenarios
  });

  test('should handle network failures', async () => {
    // Test network error scenarios with retry logic
  });
});
```

### 9. Documentation Generation

Generate comprehensive documentation including:

- **Integration Overview**: Architecture diagrams and data flow
- **Implementation Guide**: Step-by-step implementation instructions
- **Code Examples**: Working examples for each platform
- **Configuration Guide**: Environment and deployment configuration
- **Troubleshooting Guide**: Common issues and solutions
- **Performance Guide**: Optimization recommendations
- **Security Guide**: Security implementation and best practices

## Output

A comprehensive integration documentation package containing:

1. **Integration Architecture Document** - High-level design and patterns
2. **Implementation Guide** - Detailed implementation instructions with code examples
3. **API Reference** - Complete API documentation with examples
4. **Configuration Templates** - Ready-to-use configuration files
5. **Testing Guide** - Integration testing strategies and examples
6. **Troubleshooting Guide** - Common issues and resolution steps
7. **Performance Optimization Guide** - Performance tuning recommendations
8. **Security Implementation Guide** - Security best practices and implementation

**Output file**: `docs/integrations/{source-platform}-to-{target-platform}-integration.md`

## Quality Validation

### Technical Validation
- All code examples are syntactically correct and tested
- Integration patterns follow security best practices
- Performance requirements are addressed with specific recommendations
- Error handling is comprehensive and user-friendly

### Documentation Validation
- Documentation is complete and covers all integration scenarios
- Examples are clear and include proper error handling
- Troubleshooting guide addresses common integration issues
- Configuration examples are accurate and tested

### Integration Validation
- Integration patterns are validated across all supported platform versions
- Authentication and authorization flows are tested end-to-end
- Performance benchmarks are established and documented
- Security implementation is validated against compliance requirements

---

*This task generates integration documentation that enables seamless cross-platform communication while maintaining security, performance, and reliability standards across the BMAD Method ecosystem.*