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:

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)
Event Bus (Primary for asynchronous communication):
- Distributed via Kafka
- Preferred for cross-service communication
- Event-driven architecture for loose coupling
Shared Infrastructure (For state):
- Redis for cache and distributed state
- PostgreSQL for persistent data
- Kafka for events

Service Client Pattern

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

2.3 KiB Raw Blame History