# BFF (Backend for Frontend) Patterns

Reference documentation for the BFF service architecture, client adapters, error
handling, and rate limiting.

## Overview

The BFF (Backend for Frontend) service provides:

- **Request Routing**: Multi-region service discovery with retry logic
- **Response Aggregation**: Parallel/sequential multi-service requests
- **Response Shaping**: Client-specific payload optimization
- **Circuit Breaker**: Graceful degradation with mock fallbacks
- **Error Normalization**: Consistent error format with correlation IDs

## Service Request Routing

### Configuration

Service registry defines backend service configurations:

```typescript
interface ServiceConfig {
  url: string; // Primary service URL
  timeout?: number; // Request timeout (default: 30000ms)
  retries?: number; // Retry attempts (default: 0)
  retryDelayMs?: number; // Base retry delay (default: 150ms)
  regionalUrls?: Record<string, string>; // Region-specific URLs
  defaultRegionId?: string; // Default region
}
```

### Multi-Region Support

Requests are routed to the appropriate regional endpoint:

```typescript
// Region resolution priority:
// 1. x-region-id or x-preferred-region-id header
// 2. Service defaultRegionId
// 3. First active region
```

**Region Configuration**:

```typescript
interface Region {
  region_id: string;
  region_name: string;
  endpoint: string;
  availability_zones: string[];
  status: 'active' | 'degraded' | 'inactive';
}
```

### Request Flow

```
Client Request
    ↓
Check Circuit Breaker State
    ↓
Resolve Regional URL
    ↓
Add Headers (correlation, trace, span)
    ↓
Execute Request with Timeout
    ↓
    ├─ Success → Record Success → Return Response
    │
    └─ Failure → Retry with Backoff → Record Failure
                     ↓
                 Mock Fallback Response
```

### Tracing Headers

All requests include distributed tracing headers:

| Header              | Description                                     |
| ------------------- | ----------------------------------------------- |
| `x-correlation-id`  | Request correlation ID (inherited or generated) |
| `x-trace-id`        | Trace ID for distributed tracing                |
| `x-span-id`         | Current span ID (16 chars)                      |
| `x-parent-span-id`  | Parent span ID                                  |
| `x-service-name`    | Service name (`bff`)                            |
| `x-service-version` | Service version                                 |

## Response Aggregation

Combine multiple service requests in a single API call.

### Aggregation Endpoint

```http
POST /v1/aggregate
Content-Type: application/json
Authorization: Bearer <token>

{
  "strategy": "parallel",
  "requests": [
    {
      "id": "user_profile",
      "service": "auth",
      "path": "/v1/users/me",
      "method": "GET"
    },
    {
      "id": "content_feed",
      "service": "content",
      "path": "/v1/feed",
      "method": "GET"
    },
    {
      "id": "notifications",
      "service": "notification",
      "path": "/v1/notifications",
      "method": "GET",
      "headers": { "x-limit": "10" }
    }
  ]
}
```

### Aggregation Strategies

| Strategy     | Description                                 |
| ------------ | ------------------------------------------- |
| `parallel`   | Execute all requests concurrently (default) |
| `sequential` | Execute requests in order                   |

### Response Format

```json
{
  "results": [
    {
      "id": "user_profile",
      "success": true,
      "data": { "user_id": "...", "name": "..." },
      "latency": 45
    },
    {
      "id": "content_feed",
      "success": true,
      "data": { "items": [...] },
      "latency": 120
    },
    {
      "id": "notifications",
      "success": false,
      "error": "Service unavailable",
      "latency": 30000
    }
  ],
  "totalLatency": 120,
  "strategy": "parallel"
}
```

## Client-Specific Response Shaping

Optimize responses based on client type and capabilities.

### Client Types

| Client Type | Detection                           | Optimizations                                      |
| ----------- | ----------------------------------- | -------------------------------------------------- |
| `web`       | Default                             | Full payload                                       |
| `mobile`    | `mobile`, `android`, `iphone` in UA | Image optimization, lightweight items, 500KB limit |
| `tablet`    | `tablet`, `ipad` in UA              | Medium-res images                                  |
| `embedded`  | `embedded`, `iot` in UA             | Minimal essential fields only                      |

### Configuration

```typescript
interface ResponseShapingConfig {
  clientType?: 'web' | 'mobile' | 'tablet' | 'embedded';
  apiVersion?: string;
  features?: string[];
  maxPayloadSize?: number;
  compressionLevel?: 'low' | 'medium' | 'high';
  includeMetadata?: boolean;
}
```

### Mobile Optimizations

```typescript
// Image URLs transformed
img.url.replace('/original/', '/mobile/');
img.thumbnail = img.url.replace('/original/', '/thumb/');

// List items stripped of heavy content
const { full_content, raw_data, ...lightweight } = item;

// Numbers reduced to 2 decimal places
metrics[key] = Number(value.toFixed(2));
```

### Embedded/IoT Optimizations

Only critical fields are returned:

```typescript
const criticalFields = ['id', 'status', 'value', 'timestamp', 'error'];
```

### Payload Size Limits

When payload exceeds limit, fields are removed in priority order:

1. `raw_data`
2. `full_content`
3. `debug_info`
4. `metadata`
5. `internal_notes`
6. `related_items`

Then arrays are truncated to 50%.

### Response Metadata

When `includeMetadata: true`:

```json
{
  "data": "...",
  "_meta": {
    "client_type": "mobile",
    "api_version": "v1",
    "shaped": true,
    "timestamp": "2025-01-15T10:30:00.000Z"
  }
}
```

### Headers for Client Detection

| Header          | Description                   |
| --------------- | ----------------------------- |
| `User-Agent`    | Client type detection         |
| `X-API-Version` | API version (default: `v1`)   |
| `X-Features`    | Comma-separated feature flags |

### Enable Debug Metadata

```http
GET /v1/endpoint?debug=true
```

## Circuit Breaker Pattern

Graceful degradation when services fail.

### Circuit Breaker States

| State       | Description                                 |
| ----------- | ------------------------------------------- |
| `closed`    | Normal operation, requests pass through     |
| `open`      | Service failed, reject requests immediately |
| `half-open` | Testing recovery, limited requests          |

### State Transitions

```
CLOSED → OPEN (after 5 failures)
    ↓
OPEN (30 second cooldown)
    ↓
HALF-OPEN (test requests)
    ↓
    ├─ 3 successes → CLOSED
    │
    └─ Any failure → OPEN
```

### Configuration

```typescript
// Failure threshold to open circuit
const FAILURE_THRESHOLD = 5;

// Cooldown before half-open state
const COOLDOWN_MS = 30000;

// Successes needed to close circuit
const SUCCESS_THRESHOLD = 3;
```

### Mock Fallback Responses

When circuit is open, mock fallback responses are returned:

```json
{
  "status": 200,
  "body": { "mock": true, "data": [] },
  "fallback": true,
  "trace_id": "abc123",
  "error": "Circuit breaker is open for service auth"
}
```

### Circuit Breaker API

```http
GET /v1/admin/circuit-breakers
```

Returns state of all circuit breakers.

## Error Handling

Consistent error normalization with correlation tracking.

### Error Response Format

```json
{
  "error": "Authentication failed",
  "code": "auth.invalid_credentials",
  "category": "authentication",
  "severity": "error",
  "http_status": 401,
  "trace_id": "abc123-def456",
  "correlation_id": "xyz789",
  "service": "bff",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "retry_after": 60
}
```

### Error Headers

| Header             | Description                           |
| ------------------ | ------------------------------------- |
| `x-correlation-id` | Request correlation ID                |
| `x-error-category` | Error category                        |
| `x-error-severity` | Error severity level                  |
| `retry-after`      | Seconds until retry (for rate limits) |

### Error Categories

| Category              | HTTP Status | Description           |
| --------------------- | ----------- | --------------------- |
| `validation`          | 400         | Invalid request data  |
| `authentication`      | 401         | Auth failure          |
| `authorization`       | 403         | Permission denied     |
| `not_found`           | 404         | Resource not found    |
| `rate_limit`          | 429         | Too many requests     |
| `service_unavailable` | 503         | Backend service down  |
| `network_error`       | 502         | Network/timeout error |
| `internal`            | 500         | Internal error        |

### Error Management API

**Get Error Mappings**:

```http
GET /v1/admin/errors/mappings
```

**Test Error Normalization**:

```http
POST /v1/admin/errors/normalize
Content-Type: application/json

{
  "error": {
    "message": "Custom error",
    "code": "custom_error"
  },
  "context": {
    "service": "content"
  }
}
```

**Simulate Error Types**:

```http
POST /v1/admin/errors/test
Content-Type: application/json

{
  "error_type": "rate_limit",
  "simulate_service": "auth"
}
```

Available error types:

- `validation`
- `authentication`
- `rate_limit`
- `service_unavailable`
- `network_timeout`
- `internal`

## Rate Limiting

Rate limiting via circuit breaker pattern and graceful degradation.

### Implementation

Rate limiting is implemented through:

1. **Circuit Breaker**: Protects against cascading failures
2. **Timeout Enforcement**: Per-service configurable timeouts
3. **Retry Limiting**: Maximum retry attempts with exponential backoff

### Per-Service Limits

```typescript
const serviceConfig = {
  timeout: 30000, // 30 second timeout
  retries: 2, // 2 retry attempts
  retryDelayMs: 150, // Base delay (doubles each retry)
};
```

### Backoff Strategy

Exponential backoff with maximum cap:

```typescript
const backoff = retryDelayBase * Math.pow(2, attempt - 1);
const delay = Math.min(backoff, 2000); // Max 2 second delay
```

### Rate Limit Response

When rate limited by backend:

```json
{
  "error": "Rate limit exceeded",
  "code": "rate_limit_exceeded",
  "retry_after": 60,
  "trace_id": "abc123"
}
```

### Headers

| Header                  | Description                     |
| ----------------------- | ------------------------------- |
| `Retry-After`           | Seconds until rate limit resets |
| `X-RateLimit-Limit`     | Request limit                   |
| `X-RateLimit-Remaining` | Remaining requests              |
| `X-RateLimit-Reset`     | Reset timestamp                 |

## Multi-Region Configuration

### Register Region

```typescript
registerRegion({
  region_id: 'us-east-1',
  region_name: 'US East',
  endpoint: 'https://api-east.example.com',
  availability_zones: ['us-east-1a', 'us-east-1b'],
  status: 'active',
});
```

### Update Region Status

```typescript
updateRegionStatus('us-east-1', 'degraded');
```

### Set Region Priority

```typescript
setRegionPriority('us-east-1', 1); // Highest priority
setRegionPriority('us-west-2', 2);
```

### Get Configuration

```typescript
const config = getMultiRegionConfig();
// {
//   regions: [...],
//   active_regions_count: 2,
//   total_availability_zones: 6,
//   is_active_active: true,
//   priorities: [{ region_id: 'us-east-1', priority: 1 }, ...],
//   last_updated: "2025-01-15T10:30:00.000Z"
// }
```

### Active-Active Requirements

Active-active mode requires at least 2 active regions.

## Integration Example

```typescript
import { createServiceRequest } from './setup/create-service-request';
import { initializeCircuitBreakers } from './utils/circuit-breaker';

// Initialize
const serviceRegistry = {
  auth: { url: 'http://auth:8080', timeout: 5000, retries: 2 },
  content: { url: 'http://content:8080', timeout: 10000 },
  notification: { url: 'http://notification:8080' },
};

const circuitBreakers = initializeCircuitBreakers(serviceRegistry);

const makeRequest = createServiceRequest({
  serviceRegistry,
  circuitBreakers,
  recordCircuitBreakerSuccess,
  recordCircuitBreakerFailure,
  getMockFallbackResponse,
  delay: (ms) => new Promise((r) => setTimeout(r, ms)),
  randomUUID: () => crypto.randomUUID(),
});

// Make service request
const response = await makeRequest('auth', '/v1/users/me', 'GET', {
  Authorization: 'Bearer token',
});

if (response.fallback) {
  console.log('Using fallback response');
}
```

## Related Documentation

- [Error Codes](./error-codes.md) - Complete error code reference
- [API Versioning](./api-versioning.md) - Version management
- [Authentication](./authentication.md) - Auth patterns
