gh-vukhanhtruong-claude-rock-plugins-architecture-design/skills/references/microservices.md

# Microservices Architecture Patterns

## Table of Contents
- Core Principles
- Service Design Patterns
- Communication Patterns
- Data Management
- Deployment Patterns
- Observability

## Core Principles

### Single Responsibility
Each service owns one business capability and does it well.

### Decentralized Data
Each service has its own database (database-per-service pattern).

### Independence
Services can be developed, deployed, and scaled independently.

### Resilience
Services must handle failures gracefully (circuit breakers, retries).

## Service Design Patterns

### Service Boundaries
Define services around business capabilities, not technical layers:
- ✅ User Service, Order Service, Payment Service
- ❌ Database Service, Email Service (too technical)

### Service Size
Guideline: A service should be maintainable by a small team (2-pizza team).

### API Design
- Use RESTful APIs for synchronous communication
- Use gRPC for high-performance internal communication
- Use message queues for asynchronous communication
- Version APIs (v1, v2) to support backward compatibility

## Communication Patterns

### Synchronous (Request-Response)

**REST APIs:**
```
Service A --HTTP--> Service B
          <-JSON---
```

**When to use:**
- Need immediate response
- Simple request-response flow
- External-facing APIs

**gRPC:**
```
Service A --Protocol Buffer--> Service B
          <--Binary Response---
```

**When to use:**
- Internal service communication
- Need high performance
- Strong typing required

### Asynchronous (Event-Driven)

**Message Queue:**
```
Service A --publish--> Queue --consume--> Service B
```

**When to use:**
- Don't need immediate response
- Decouple services
- Handle bursts of traffic
- Background processing

**Event Bus/Broker:**
```
Service A --emit event--> Event Bus --subscribe--> Service B, C, D
```

**When to use:**
- Multiple services need same event
- Event sourcing patterns
- Complex event processing

**Popular Tools:**
- Kafka: High-throughput, event streaming
- RabbitMQ: Traditional message broker
- AWS SQS/SNS: Cloud-native messaging
- NATS: Lightweight messaging

### API Gateway Pattern

Centralized entry point for all client requests.

**Responsibilities:**
- Request routing
- Authentication/Authorization
- Rate limiting
- Request/Response transformation
- Caching
- Load balancing

**Tools:**
- Kong
- AWS API Gateway
- Nginx
- Spring Cloud Gateway
- Traefik

### Service Mesh Pattern

Infrastructure layer for service-to-service communication.

**Features:**
- Traffic management
- Security (mTLS)
- Observability
- Circuit breaking
- Retry logic

**Tools:**
- Istio
- Linkerd
- Consul Connect

## Data Management

### Database Per Service

Each service owns its database. No shared databases.

**Benefits:**
- Service independence
- Technology flexibility
- Scalability

**Challenges:**
- Data consistency
- Joins across services
- Transactions

### Saga Pattern

Manage transactions across multiple services.

**Choreography:**
```
Order Service --creates order-->
    |--event--> Payment Service --processes payment-->
    |--event--> Inventory Service --reserves items-->
    |--event--> Shipping Service --ships order-->
```

Each service listens to events and publishes new events.

**Orchestration:**
```
Order Orchestrator
    |--call--> Payment Service
    |--call--> Inventory Service
    |--call--> Shipping Service
```

Central orchestrator coordinates the saga.

### CQRS (Command Query Responsibility Segregation)

Separate read and write models.

**Pattern:**
- Write: Command Model (normalized, transactional)
- Read: Query Model (denormalized, optimized for reads)
- Sync via events or batch processes

**When to use:**
- Complex domains
- Different read/write patterns
- Need to scale reads separately

### Event Sourcing

Store state changes as events rather than current state.

**Benefits:**
- Complete audit log
- Temporal queries
- Event replay for debugging
- Derive new models from events

**Challenges:**
- Complexity
- Event versioning
- Storage requirements

## Deployment Patterns

### Containerization

**Docker:**
```
Each service → Docker image → Container
```

**Benefits:**
- Consistency across environments
- Isolation
- Resource efficiency

### Container Orchestration

**Kubernetes:**
```
Cluster
├── Namespace: production
│   ├── Deployment: user-service
│   ├── Deployment: order-service
│   └── Deployment: payment-service
└── Namespace: staging
```

**Features:**
- Automated deployment
- Scaling
- Self-healing
- Service discovery
- Load balancing
- Rolling updates

### Service Discovery

**Pattern:**
Services register themselves and discover other services dynamically.

**Client-side:**
- Service queries registry
- Service makes direct call
- Tools: Eureka, Consul

**Server-side:**
- Load balancer queries registry
- Routes request to service
- Tools: Kubernetes, AWS ELB

### Configuration Management

**External Configuration:**
- Spring Cloud Config
- Consul
- etcd
- Kubernetes ConfigMaps/Secrets

**Pattern:**
- Store config separately from code
- Environment-specific configs
- Runtime configuration changes

## Observability

### Distributed Tracing

Track requests across multiple services.

**Tools:**
- Jaeger
- Zipkin
- AWS X-Ray
- Datadog APM

**Pattern:**
```
Request ID: abc123
User Service (10ms) --> Order Service (50ms) --> Payment Service (100ms)
Total: 160ms
```

### Centralized Logging

Aggregate logs from all services.

**Tools:**
- ELK Stack (Elasticsearch, Logstash, Kibana)
- Splunk
- CloudWatch Logs
- Datadog

**Pattern:**
- Structured logging (JSON)
- Correlation IDs
- Log levels
- Searchable aggregation

### Metrics and Monitoring

**Metrics to track:**
- Request rate
- Error rate
- Response time (latency)
- Resource usage (CPU, memory)

**Tools:**
- Prometheus + Grafana
- CloudWatch
- Datadog
- New Relic

### Health Checks

**Types:**
- Liveness: Is service alive?
- Readiness: Can service handle requests?
- Startup: Has service started?

**Implementation:**
```
/health/live    → 200 OK
/health/ready   → 200 OK (or 503 if not ready)
```

## Common Challenges

### Network Latency
**Solution:** Async communication, caching, service mesh

### Data Consistency
**Solution:** Eventual consistency, saga pattern, CQRS

### Testing
**Solution:** Contract testing, integration tests, chaos engineering

### Debugging
**Solution:** Distributed tracing, centralized logging, correlation IDs

### Security
**Solution:** API gateway, service mesh mTLS, OAuth2/JWT

### Service Proliferation
**Solution:** Clear service boundaries, API standards, governance

## Best Practices

1. **Start with a Monolith:** Don't start with microservices
2. **Define Clear Boundaries:** Use Domain-Driven Design
3. **Automate Everything:** CI/CD, testing, deployment
4. **Monitor from Day One:** Logging, metrics, tracing
5. **Design for Failure:** Circuit breakers, retries, timeouts
6. **Version APIs:** Support backward compatibility
7. **Document APIs:** OpenAPI/Swagger
8. **Use Async for Non-Critical Paths:** Message queues
9. **Implement Health Checks:** For orchestration
10. **Security at Every Layer:** Gateway, service mesh, code