BMAD-METHOD/bmad-agent/templates/integration-documentation-template.md

# {Source Platform} to {Target Platform} Integration Guide

## Integration Overview

### Architecture Summary
- **Source Platform**: {Source Platform} ({Version})
- **Target Platform**: {Target Platform} ({Version})
- **Communication Protocol**: {Protocol}
- **Authentication Method**: {Authentication}
- **Data Format**: {Data Format}

### Integration Diagram
```mermaid
graph LR
    A[{Source Platform}] -->|{Protocol}| B[Authentication Layer]
    B --> C[Data Transformation]
    C --> D[{Target Platform}]
    D -->|Response| E[Response Processing]
    E --> A
```

## Prerequisites

### Source Platform Requirements
- {Source Platform} version {Version} or higher
- Required dependencies and packages
- Authentication credentials and configuration
- Network connectivity and firewall rules

### Target Platform Requirements
- {Target Platform} version {Version} or higher
- Required services and endpoints
- Database and storage requirements
- Monitoring and logging configuration

## Authentication & Security

### Authentication Implementation

#### JWT Token Authentication
```{source-language}
// JWT token validation and handling
interface AuthenticationConfig {
  issuer: string;
  audience: string;
  secretKey: string;
  expirationTime: number;
}

class AuthenticationService {
  validateToken(token: string): Promise<AuthPayload>;
  refreshToken(refreshToken: string): Promise<TokenResponse>;
  revokeToken(token: string): Promise<void>;
}
```

#### OAuth 2.0 Flow
```{target-language}
// OAuth 2.0 implementation
public class OAuthConfiguration
{
    public string ClientId { get; set; }
    public string ClientSecret { get; set; }
    public string AuthorizationEndpoint { get; set; }
    public string TokenEndpoint { get; set; }
    public string[] Scopes { get; set; }
}
```

### Security Best Practices
- Use HTTPS for all communications
- Implement proper token validation and expiration
- Apply rate limiting and throttling
- Log security events and monitor for anomalies
- Implement CORS policies appropriately

## Data Models & Transformation

### Shared Data Models
```{source-language}
// Common data structures
interface BaseEntity {
  id: string;
  createdAt: Date;
  updatedAt?: Date;
  version: number;
}

interface {EntityName} extends BaseEntity {
  // Entity-specific properties
  name: string;
  description?: string;
  metadata: Record<string, unknown>;
}
```

### Data Transformation Patterns
```{target-language}
// Data transformation logic
public class DataTransformer
{
    public {TargetType} Transform({SourceType} source)
    {
        return new {TargetType}
        {
            // Mapping logic
            Id = source.Id,
            Name = source.Name,
            CreatedAt = source.CreatedAt.ToUniversalTime()
        };
    }
}
```

## API Integration Patterns

### REST API Integration

#### Client Implementation
```{source-language}
class {ServiceName}Client {
  private baseUrl: string;
  private authToken: string;

  async get<T>(endpoint: string): Promise<T> {
    const response = await fetch(`${this.baseUrl}${endpoint}`, {
      headers: {
        'Authorization': `Bearer ${this.authToken}`,
        'Content-Type': 'application/json'
      }
    });

    if (!response.ok) {
      throw new IntegrationError(
        `HTTP ${response.status}: ${response.statusText}`,
        response.status,
        '{Source Platform}'
      );
    }

    return response.json();
  }

  async post<T>(endpoint: string, data: unknown): Promise<T> {
    // POST implementation with error handling
  }
}
```

#### Server Implementation
```{target-language}
[ApiController]
[Route("api/[controller]")]
public class {EntityName}Controller : ControllerBase
{
    private readonly I{ServiceName} _service;

    [HttpGet("{id}")]
    public async Task<ActionResult<{EntityName}>> GetById(string id)
    {
        try
        {
            var entity = await _service.GetByIdAsync(id);
            return Ok(entity);
        }
        catch (NotFoundException)
        {
            return NotFound();
        }
        catch (Exception ex)
        {
            return StatusCode(500, new { error = ex.Message });
        }
    }
}
```

### GraphQL Integration

#### Schema Definition
```graphql
type {EntityName} {
  id: ID!
  name: String!
  description: String
  createdAt: DateTime!
  updatedAt: DateTime
}

type Query {
  get{EntityName}(id: ID!): {EntityName}
  list{EntityName}s(filter: {EntityName}Filter): [{EntityName}!]!
}

type Mutation {
  create{EntityName}(input: Create{EntityName}Input!): {EntityName}!
  update{EntityName}(id: ID!, input: Update{EntityName}Input!): {EntityName}!
}
```

#### Client Implementation
```{source-language}
const GET_{ENTITY_NAME} = gql`
  query Get{EntityName}($id: ID!) {
    get{EntityName}(id: $id) {
      id
      name
      description
      createdAt
    }
  }
`;

class GraphQL{ServiceName}Client {
  async get{EntityName}(id: string): Promise<{EntityName}> {
    const { data } = await this.client.query({
      query: GET_{ENTITY_NAME},
      variables: { id }
    });
    return data.get{EntityName};
  }
}
```

## Error Handling & Resilience

### Error Response Format
\```json
{
  "error": {
    "code": "INTEGRATION_ERROR",
    "message": "Human-readable error description",
    "details": {
      "platform": "{source-platform}",
      "timestamp": "2024-01-01T00:00:00Z",
      "traceId": "uuid-trace-id",
      "context": {
        "endpoint": "/api/endpoint",
        "method": "POST",
        "statusCode": 400
      }
    }
  }
}
```

### Retry Logic Implementation
```{source-language}
class RetryPolicy {
  async executeWithRetry<T>(
    operation: () => Promise<T>,
    maxRetries: number = 3,
    baseDelayMs: number = 1000
  ): Promise<T> {
    let lastError: Error;
    
    for (let attempt = 0; attempt <= maxRetries; attempt++) {
      try {
        return await operation();
      } catch (error) {
        lastError = error as Error;
        
        if (attempt === maxRetries || !this.isRetryableError(error)) {
          throw error;
        }
        
        const delay = baseDelayMs * Math.pow(2, attempt);
        await this.sleep(delay);
      }
    }
    
    throw lastError!;
  }

  private isRetryableError(error: unknown): boolean {
    // Determine if error is retryable (network, timeout, 5xx, etc.)
    return error instanceof NetworkError || 
           error instanceof TimeoutError ||
           (error instanceof HttpError && error.status >= 500);
  }
}
```

## Performance Optimization

### Caching Strategy
```{source-language}
interface CacheConfig {
  ttl: number;
  maxSize: number;
  strategy: 'LRU' | 'LFU' | 'FIFO';
}

class IntegrationCache {
  private cache: Map<string, CacheEntry>;
  
  async get<T>(key: string): Promise<T | null> {
    const entry = this.cache.get(key);
    if (entry && !this.isExpired(entry)) {
      return entry.value;
    }
    return null;
  }
  
  async set<T>(key: string, value: T, ttl?: number): Promise<void> {
    // Cache implementation with TTL
  }
}
```

### Connection Pooling
```{target-language}
public class ConnectionPoolConfiguration
{
    public int MaxConnections { get; set; } = 100;
    public TimeSpan ConnectionTimeout { get; set; } = TimeSpan.FromSeconds(30);
    public TimeSpan IdleTimeout { get; set; } = TimeSpan.FromMinutes(5);
    public int MinConnections { get; set; } = 10;
    public bool EnableHealthChecks { get; set; } = true;
}

public class PooledHttpClient
{
    private readonly HttpClient _httpClient;
    private readonly ConnectionPoolConfiguration _config;
    
    public async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request)
    {
        // Pooled HTTP client implementation
    }
}
```

## Monitoring & Observability

### Metrics Collection
```{source-language}
interface IntegrationMetrics {
  requestCount: number;
  errorCount: number;
  averageLatency: number;
  p95Latency: number;
  p99Latency: number;
  activeConnections: number;
  cacheHitRate: number;
}

class MetricsCollector {
  recordRequest(endpoint: string, method: string, duration: number): void;
  recordError(endpoint: string, error: Error): void;
  recordCacheHit(key: string): void;
  recordCacheMiss(key: string): void;
}
```

### Distributed Tracing
```{target-language}
public class TracingMiddleware
{
    public async Task InvokeAsync(HttpContext context, RequestDelegate next)
    {
        using var activity = ActivitySource.StartActivity("integration-request");
        activity?.SetTag("integration.source", "{source-platform}");
        activity?.SetTag("integration.target", "{target-platform}");
        
        try
        {
            await next(context);
        }
        catch (Exception ex)
        {
            activity?.SetStatus(ActivityStatusCode.Error, ex.Message);
            throw;
        }
    }
}
```

## Testing Strategy

### Integration Tests
```{source-language}
describe('{Source Platform} to {Target Platform} Integration', () => {
  let client: {ServiceName}Client;
  let mockServer: MockServer;

  beforeAll(async () => {
    mockServer = new MockServer();
    await mockServer.start();
    client = new {ServiceName}Client(mockServer.url);
  });

  afterAll(async () => {
    await mockServer.stop();
  });

  test('should successfully retrieve entity', async () => {
    // Arrange
    const expectedEntity = { id: '123', name: 'Test Entity' };
    mockServer.get('/api/entities/123').reply(200, expectedEntity);

    // Act
    const result = await client.getEntity('123');

    // Assert
    expect(result).toEqual(expectedEntity);
  });

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

  test('should retry on transient failures', async () => {
    // Test retry logic
  });
});
```

### Performance Tests
```{source-language}
describe('Performance Tests', () => {
  test('should meet latency requirements', async () => {
    const startTime = Date.now();
    await client.getEntity('123');
    const duration = Date.now() - startTime;
    
    expect(duration).toBeLessThan(100); // 100ms requirement
  });

  test('should handle concurrent requests', async () => {
    const promises = Array.from({ length: 100 }, () => 
      client.getEntity('123')
    );
    
    const results = await Promise.all(promises);
    expect(results).toHaveLength(100);
  });
});
```

## Configuration

### Environment Configuration
\```yaml
# Integration Configuration
integration:
  {source-platform}:
    base_url: "${SOURCE_BASE_URL}"
    timeout: 30000
    retry_attempts: 3
    auth:
      type: "jwt"
      secret: "${JWT_SECRET}"
  
  {target-platform}:
    base_url: "${TARGET_BASE_URL}"
    connection_pool:
      max_connections: 100
      idle_timeout: 300
    monitoring:
      enabled: true
      metrics_endpoint: "/metrics"
```

### Development Environment Setup
\```bash
# Environment variables
export SOURCE_BASE_URL="http://localhost:3000"
export TARGET_BASE_URL="http://localhost:5000"
export JWT_SECRET="your-jwt-secret"
export DATABASE_URL="postgresql://user:pass@localhost:5432/db"

# Start services
docker-compose up -d
npm run start:dev
```

## Troubleshooting Guide

### Common Issues

#### Authentication Failures
**Symptoms**: 401 Unauthorized responses
**Causes**: 
- Expired or invalid JWT tokens
- Incorrect OAuth configuration
- Missing authentication headers

**Solutions**:
1. Verify token expiration and refresh if needed
2. Check OAuth client credentials and scopes
3. Ensure proper Authorization header format

#### Connection Timeouts
**Symptoms**: Request timeouts or connection refused errors
**Causes**:
- Network connectivity issues
- Service unavailability
- Incorrect endpoint URLs

**Solutions**:
1. Verify network connectivity between services
2. Check service health and availability
3. Validate endpoint URLs and ports

#### Data Transformation Errors
**Symptoms**: Serialization/deserialization failures
**Causes**:
- Schema mismatches between platforms
- Invalid data formats
- Missing required fields

**Solutions**:
1. Validate data schemas match between platforms
2. Implement proper data validation
3. Add error handling for missing fields

### Debugging Tools

#### Logging Configuration
```{source-language}
const logger = createLogger({
  level: 'debug',
  format: combine(
    timestamp(),
    errors({ stack: true }),
    json()
  ),
  transports: [
    new transports.Console(),
    new transports.File({ filename: 'integration.log' })
  ]
});
```

#### Health Check Endpoints
```{target-language}
[HttpGet("health")]
public async Task<IActionResult> HealthCheck()
{
    var health = new
    {
        status = "healthy",
        timestamp = DateTime.UtcNow,
        version = Assembly.GetExecutingAssembly().GetName().Version?.ToString(),
        dependencies = await CheckDependencies()
    };
    
    return Ok(health);
}
```

## Deployment Considerations

### Production Checklist
- [ ] SSL/TLS certificates configured
- [ ] Authentication and authorization tested
- [ ] Rate limiting and throttling configured
- [ ] Monitoring and alerting set up
- [ ] Error handling and logging implemented
- [ ] Performance benchmarks validated
- [ ] Security scan completed
- [ ] Backup and recovery procedures tested

### Scaling Considerations
- Implement horizontal scaling for high-traffic scenarios
- Configure load balancing across multiple instances
- Set up database connection pooling and optimization
- Implement caching strategies for frequently accessed data
- Monitor resource usage and set up auto-scaling policies

---

## Additional Resources

- [API Documentation]({api-docs-url})
- [Security Best Practices]({security-docs-url})
- [Performance Optimization Guide]({performance-docs-url})
- [Monitoring and Alerting Setup]({monitoring-docs-url})

---

*This integration guide provides comprehensive implementation guidance for seamless cross-platform communication while maintaining security, performance, and reliability standards.*