# ADR-0030: Service Communication Strategy

## Status
Accepted

## Context
Services need to communicate with each other in a microservices architecture. All communication must go through well-defined interfaces that support network calls.

## Decision
Use a **service client-based communication strategy**:

1. **Service Client Interfaces** (Primary for synchronous calls):
   - Define interfaces in `pkg/services/` for all services
   - All implementations are network-based:
     - `internal/services/grpc/client/` - gRPC clients (primary)
     - `internal/services/http/client/` - HTTP clients (fallback)

2. **Event Bus** (Primary for asynchronous communication):
   - Distributed via Kafka
   - Preferred for cross-service communication
   - Event-driven architecture for loose coupling

3. **Shared Infrastructure** (For state):
   - Redis for cache and distributed state
   - PostgreSQL for persistent data
   - Kafka for events

## Service Client Pattern

```go
// Interface in pkg/services/
type IdentityServiceClient interface {
    GetUser(ctx context.Context, id string) (*User, error)
    CreateUser(ctx context.Context, user *User) (*User, error)
}

// gRPC implementation (primary)
type grpcIdentityClient struct {
    conn *grpc.ClientConn
    client pb.IdentityServiceClient
}

// HTTP implementation (fallback)
type httpIdentityClient struct {
    baseURL string
    httpClient *http.Client
}
```

## Development Mode
For local development, multiple services can run in the same process, but they still communicate via service clients (gRPC or HTTP) - no direct in-process calls. This ensures the architecture is consistent.

## Consequences

### Positive
- **Unified Interface**: Consistent interface across all services
- **Easy Testing**: Can mock service clients
- **Type Safety**: gRPC provides type-safe contracts
- **Clear Boundaries**: Service boundaries are explicit
- **Scalability**: Services can be scaled independently

### Negative
- **Network Overhead**: All calls go over network
- **Interface Evolution**: Changes require coordination
- **Versioning**: Need service versioning strategy
- **Development Complexity**: More setup required for local development

## Implementation
- All services use gRPC clients (primary)
- HTTP clients as fallback option
- Service registry for service discovery
- Circuit breakers and retries for resilience