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

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

// 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

// 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

// 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

// 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

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

[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

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

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

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

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

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

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

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

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

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

[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
• Security Best Practices
• Performance Optimization Guide
• Monitoring and Alerting Setup

---

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