A microservices reference implementation for monitoring household electricity usage. The system accepts energy readings from smart devices, processes them asynchronously, stores time-series metrics, raises alerts when usage spikes, and exposes a unified API through an API Gateway with resilience, security, and observability built in.
Built with Spring Boot 4 and Java 21, services are independently deployable modules using synchronous HTTP (client → gateway → service) and asynchronous Kafka messaging where loose coupling matters.
Flow: Clients hit the API Gateway → domain services (user, device, ingestion, insight). Ingestion publishes to Kafka → usage consumes, writes to InfluxDB, and may publish alerts → alert consumes and sends email via Mailpit in local dev.
| Area | Approach |
|---|---|
| API Gateway | Spring Cloud Gateway (Server MVC); single public HTTP facade, route aggregation, OpenAPI aggregation |
| Service communication | REST between gateway and backends; Kafka for ingestion → usage → alerts |
| Resilience | Circuit breakers (Resilience4j) on gateway routes with fallbacks |
| Security | OAuth2 Resource Server on the gateway; Keycloak for identity |
| Observability | Spring Boot Actuator, Micrometer, Prometheus scrape targets, Grafana dashboards |
| Configuration | Per-service application.properties (no separate Config Server) |
| Service | Port | Responsibility | Key technologies |
|---|---|---|---|
| api-gateway | 9000 |
Routing, circuit breaking, JWT validation, aggregated API docs | Spring Cloud Gateway (WebMVC), Resilience4j, OAuth2, springdoc |
| user-service | 8080 |
User accounts and related persistence | JPA, MySQL, Flyway, Actuator/Prometheus |
| device-service | 8081 |
Device registry / metadata | JPA, MySQL, Actuator/Prometheus |
| ingestion-service | 8082 |
Accept energy readings over HTTP, publish to Kafka | Kafka producer, Actuator/Prometheus |
| usage-service | 8083 |
Consume usage events, time-series storage, threshold logic | Kafka consumer/producer, InfluxDB Java client |
| alert-service | 8084 |
Consume alert events, notify users via email | Kafka consumer, JPA, Mail, MySQL |
| insight-service | 8085 |
LLM-backed usage insights via Spring AI + Ollama | Spring AI, Ollama |
| Layer | Technology |
|---|---|
| Language | Java 21 |
| Framework | Spring Boot 4.1 |
| Spring Cloud | 2025.1.2 — Gateway (Server WebMVC), Circuit Breaker (Resilience4j) |
| Messaging | Apache Kafka (KRaft) |
| Databases | MySQL 8 (relational), InfluxDB 2 (time-series) |
| Security | Keycloak (OAuth2 / JWKS) |
| Observability | Micrometer, Prometheus, Grafana |
| AI | Spring AI + Ollama |
| API docs | springdoc-openapi (aggregated at gateway) |
| Containerization | Docker & Docker Compose |
| Build | Maven (per-service mvnw wrapper) |
- Each Spring Boot app exposes
/actuator/prometheus(Micrometer + Actuator). - Prometheus (
docker/prometheus/prometheus.yml) scrapes the gateway and all services on the host. - Grafana loads provisioning from
docker/grafana/provisioningwith Prometheus as the data source. - Circuit breaker state is surfaced through Actuator health on the gateway.