Chapter 8: Platform Services
The MATIH control plane includes eight platform services that provide cross-cutting functionality consumed by every other service in the system. These services handle dynamic configuration, notifications, audit logging, billing, observability, infrastructure orchestration, service discovery, and API gateway routing. Together, they form the operational backbone that keeps the platform running, observable, and auditable.
What You Will Learn
By the end of this chapter, you will understand:
- Config Service -- dynamic configuration management, feature flags, marketplace integrations, and event-driven configuration updates across the platform
- Notification Service -- multi-channel notification delivery through email, Slack, and webhooks with Kafka event consumption and template management
- Audit Service -- compliance-grade event logging, audit trail querying, retention policies, and regulatory reporting
- Billing Service -- platform-wide usage metering, invoice generation, cost attribution per tenant, and payment processor integration
- Observability API -- metrics, logs, and traces aggregation with Prometheus integration and Grafana dashboard management
- Infrastructure Service -- Terraform orchestration for cloud resource provisioning with async operation management
- Platform Registry -- service discovery, metadata registry, component catalog, and health aggregation across all services
- API Gateway -- Kong 3.5.0 configuration with custom Lua plugins for JWT validation, tenant context extraction, and per-tenant rate limiting
Chapter Structure
| Section | Description | Audience |
|---|---|---|
| Config Service | Dynamic configuration and feature flags | Backend engineers, platform operators |
| Notification Service | Multi-channel notifications | Backend engineers |
| Audit Service | Compliance logging and reporting | Security engineers, compliance officers |
| Billing Service | Platform-wide billing operations | Backend engineers, product managers |
| Observability API | Metrics, logs, and traces | SREs, platform engineers |
| Infrastructure Service | Terraform orchestration | Platform engineers, SREs |
| Platform Registry | Service discovery and metadata | Architects, platform engineers |
| API Gateway | Kong gateway configuration | Backend engineers, security engineers |
Services at a Glance
| Service | Port | Technology | Primary Function |
|---|---|---|---|
| Config Service | 8888 | Spring Boot 3.2, Java 21 | Dynamic configuration, feature flags |
| Notification Service | 8085 | Spring Boot 3.2, Java 21 | Email, Slack, webhook delivery |
| Audit Service | 8086 | Spring Boot 3.2, Java 21 | Compliance event logging |
| Billing Service | 8087 | Spring Boot 3.2, Java 21 | Usage metering, invoicing |
| Observability API | 8088 | Spring Boot 3.2, Java 21 | Metrics/logs/traces aggregation |
| Infrastructure Service | 8089 | Spring Boot 3.2, Java 21 | Terraform orchestration |
| Platform Registry | 8084 | Spring Boot 3.2, Java 21 | Service discovery |
| API Gateway | 8080 | Kong 3.5.0 (Lua/OpenResty) | Request routing, auth enforcement |
Service Interaction Map
The platform services interact with each other and with the core control plane services (IAM, Tenant) in a coordinated pattern:
API Gateway (8080)
|
+-------+-------+-------+-------+
| | | | |
v v v v v
IAM Tenant Config Billing Observability
(8081) (8082) (8888) (8087) (8088)
| | | | |
+---+---+---+---+---+---+---+---+
| | | |
v v v v
Notification Audit Infra Registry
(8085) (8086) (8089) (8084)Common Patterns
All platform services share these architectural patterns:
| Pattern | Description |
|---|---|
| JWT authentication | Every request carries a JWT token validated against the shared signing key |
| Tenant scoping | All data access is filtered by the tenant_id claim from the JWT |
| Event publishing | Services publish domain events to Kafka for asynchronous consumption |
| Health endpoints | All services expose /health and /health/ready for Kubernetes probes |
| Prometheus metrics | All services export metrics at /actuator/prometheus |
| Domain exceptions | Each service throws typed exceptions (GatewayException, BillingException, etc.) instead of generic RuntimeException for precise error classification |
| MDC structured logging | All services use a standardized log pattern with tenantId and correlationId MDC fields for cross-service correlation |
| Flyway migrations | Database schemas are managed through versioned SQL migrations |
| Spring profiles | Configuration varies by environment (dev, staging, production) |
Key Design Principles
Single responsibility. Each platform service owns a single cross-cutting concern. The Config Service manages configuration; it does not handle notifications. The Audit Service logs events; it does not process billing.
Loose coupling through events. Platform services communicate primarily through Kafka events rather than synchronous HTTP calls. The Notification Service consumes events from any service that needs to trigger notifications. The Audit Service consumes events from every service that generates audit-worthy actions.
Consistent API design. All platform services follow the same REST conventions: versioned paths (/api/v1/...), standard error responses, pagination via query parameters, and OpenAPI documentation.
Operational transparency. Every service exposes health, metrics, and readiness endpoints. The Platform Registry aggregates this information into a single operational view.
How This Chapter Connects
The platform services are consumed throughout the system. The API Gateway (API Gateway) is the entry point for all external traffic, validating tokens issued by the IAM service (Chapter 6). The Config Service provides feature flags that control behavior in the AI service (Chapter 12) and ML service (Chapter 13). The Audit Service captures events from the Tenant Service (Chapter 7) provisioning workflow. The Infrastructure Service orchestrates the Terraform deployments that create the Kubernetes resources documented in Chapter 17.
Prerequisites
To get the most from this chapter, you should be familiar with:
- Microservices communication patterns (synchronous HTTP, asynchronous events)
- Apache Kafka fundamentals (topics, consumers, consumer groups)
- Prometheus metrics and Grafana dashboards
- Terraform resource management concepts
- API gateway patterns (routing, rate limiting, authentication)
Begin with the Config Service to understand how configuration flows through the platform.