Claude Coder Microservices Communication Rules

# Claude Coder Microservices Communication Rules

## Communication Patterns

### Synchronous (REST/gRPC)
- Use for: queries requiring immediate response, health checks, simple CRUD
- Timeout: set explicit timeout for every outbound call (default: 5s, max: 30s)
- Retries: max 3, with exponential backoff (1s, 2s, 4s) + jitter
- Circuit breaker: open after 5 consecutive failures, half-open after 30s

### Asynchronous (Events/Messages)
- Use for: commands that don't need immediate response, cross-service data sync
- Message format: CloudEvents specification
- Idempotency: every consumer must handle duplicate messages safely
- Dead letter queue: configure for all consumers (max 3 retries before DLQ)
- Ordering: only guarantee ordering within a partition key

## API Contract Rules
1. All APIs versioned (v1, v2) — never break backward compatibility
2. Use Protocol Buffers for gRPC, OpenAPI 3.1 for REST
3. Changes: additive only (new fields with defaults, new endpoints)
4. Breaking changes require: new version + migration period + deprecation notice
5. Consumer-driven contract testing with Pact or similar

## Data Consistency
- Prefer eventual consistency — only use distributed transactions when legally required
- Saga pattern for multi-service operations (choreography for simple, orchestration for complex)
- Compensating transactions for rollback (undo the business action, not the DB transaction)
- Outbox pattern for reliable event publishing (write event + business data in same DB transaction)

## Observability
- Distributed trace ID propagated in ALL requests (X-Trace-Id header)
- Structured logging with: trace_id, service_name, operation, duration_ms, status
- Metrics per endpoint: request_count, latency_histogram, error_rate
- SLOs defined per service: availability, latency p99, error budget