Communication Patterns
The MATIH Platform uses four communication protocols, each selected for specific interaction patterns. This section documents when and how each protocol is used across the service topology.
Protocol Overview
| Protocol | Pattern | Use Case | Latency |
|---|---|---|---|
| REST/HTTP | Synchronous request-response | Inter-service calls requiring immediate response | 1-100ms |
| Apache Kafka | Asynchronous event streaming | Fire-and-forget notifications, event sourcing | 10-500ms |
| Redis Pub/Sub | Real-time broadcast | Config propagation, AI streaming | Sub-millisecond |
| gRPC | High-performance typed RPC | Pipeline-to-Temporal, ML-to-Ray | 1-10ms |
REST/HTTP (Synchronous)
Used for all inter-service calls that require an immediate response:
| Convention | Details |
|---|---|
| Content type | application/json |
| Authentication | Authorization: Bearer <token> |
| Tenant context | X-Tenant-ID header |
| Tracing | X-Correlation-ID header |
| Retry | RetryableRestClient with exponential backoff |
| Circuit breaker | Resilience4j circuit breaker per downstream service |
Examples
| Caller | Target | Purpose |
|---|---|---|
| AI Service | Query Engine | Execute generated SQL |
| AI Service | Catalog Service | Fetch schema metadata |
| BI Service | Semantic Layer | Resolve metric queries |
| BI Service | Render Service | Generate chart images |
| API Gateway | IAM Service | Validate JWT tokens |
Apache Kafka (Asynchronous)
Used for event notifications that do not require an immediate response:
| Pattern | Description | Example |
|---|---|---|
| Event notification | Producer publishes, consumers react independently | Tenant provisioned event |
| Event-carried state | Event payload contains all data consumers need | Query completed with result metadata |
| Saga coordination | Events trigger sequential workflow steps | Multi-phase provisioning |
Redis Pub/Sub (Real-Time Broadcast)
Used for ephemeral notifications where latency matters more than durability:
| Channel | Publisher | Subscriber |
|---|---|---|
config:changes | Config Service | All services |
ai:stream:{sessionId} | AI Service | WebSocket bridge |
dashboard:refresh:{id} | BI Service | Frontend WebSocket |
gRPC (High-Performance)
Used for high-throughput internal communication:
| Caller | Target | Purpose |
|---|---|---|
| Pipeline Service | Temporal | Workflow orchestration |
| ML Service | Ray | Distributed compute dispatch |
Resilience Patterns
| Pattern | Implementation | Purpose |
|---|---|---|
| Retry | RetryableRestClient with exponential backoff | Handle transient failures |
| Circuit breaker | Resilience4j per downstream service | Prevent cascade failures |
| Timeout | Configurable per-call timeout | Prevent indefinite waiting |
| Bulkhead | Thread pool isolation per downstream | Limit resource consumption |
| Fallback | Cached response on circuit open | Graceful degradation |
Related Pages
- Service Registry -- Service discovery
- Dependency Map -- Service dependencies
- Event-Driven Architecture -- Kafka and Redis patterns