# rapter1990/insurance-campaign-microservices architecture

> Architecture diagram of the GitHub repository rapter1990/insurance-campaign-microservices, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rapter1990/insurance-campaign-microservices
- Repository: https://github.com/rapter1990/insurance-campaign-microservices

## Overview

#### Purpose and Runtime Topology
This Maven multi-module system is an insurance campaign-management platform built on Java 25 and Spring Boot 4. It exposes REST APIs for identity, campaign lifecycle, dashboards, and logs; uses independent service data stores; and runs either fully containerized or with infrastructure-only local Compose.
- Root orchestration: `pom.xml`, `docker-compose.yml`, `docker-compose-local.yml`
- Service entry points: `api-gateway/src/main/java/com/casestudy/insurancecampaign/gateway/ApiGatewayApplication.java`, `campaign-service/src/main/java/com/casestudy/insurancecampaign/campaign/CampaignServiceApplication.java`

#### Platform Control Plane and Edge
Discovery Server provides Eureka registration; Config Server centrally serves Spring configuration. API Gateway is the primary client entry point: routes requests to services, validates JWTs, applies Redis-backed rate limits, and aggregates/falls back OpenAPI documents.
- `discovery-server/src/main/java/com/casestudy/insurancecampaign/discovery/DiscoveryServerApplication.java`
- `config-server/src/main/java/com/casestudy/insurancecampaign/config/ConfigServerApplication.java`
- `api-gateway/src/main/java/com/casestudy/insurancecampaign/gateway/filter/GatewayJwtAuthenticationFilter.java`
- `api-gateway/src/main/java/com/casestudy/insurancecampaign/gateway/config/GatewayRateLimiterConfiguration.java`

#### Identity and Authorization Boundary
Auth Service owns users, roles, refresh tokens, password-reset tokens, and RSA access-token signing. It persists identity state in its PostgreSQL database through JPA/Liquibase. Other services and the gateway validate signatures with the shared public-key security module; campaign authorization is additionally enforced within Campaign Service, not trusted solely to the gateway.
- `auth-service/src/main/java/com/casestudy/insurancecampaign/auth/controller/AuthController.java`
- `auth-service/src/main/java/com/casestudy/insurancecampaign/auth/service/AuthService.java`
- `security/src/main/java/com/casestudy/insurancecampaign/security/ServiceSecurityConfiguration.java`
- `auth-service/src/main/resources/db/changelog/db.changelog-master.yml`

#### Campaign Lifecycle Core
Campaign Service is the system of record for campaigns and status history. Its service layer validates title/category/content rules, rejects duplicate category-title-description combinations, assigns initial status, enforces valid approval/deactivation transitions, persists state/history, and serves REST plus gRPC. It caches campaign status statistics in Redis and evicts cache entries on changes.
- `campaign-service/src/main/java/com/casestudy/insurancecampaign/campaign/service/CampaignService.java`
- `campaign-service/src/main/java/com/casestudy/insurancecampaign/campaign/entity/CampaignEntity.java`
- `campaign-service/src/main/java/com/casestudy/insurancecampaign/campaign/entity/CampaignStatusHistoryEntity.java`
- `campaign-service/src/main/java/com/casestudy/insurancecampaign/campaign/grpc/CampaignGrpcEndpoint.java`

#### Dashboard and Interservice Contracts
Dashboard Service is a read-oriented HTTP façade for campaign statistics and campaign history. It does not directly access the campaign database; it calls Campaign Service’s gRPC endpoint using generated protobuf contracts. Auth audit logging instead uses HTTP Exchange from Auth Service to Log Service and is deliberately non-blocking to authentication outcomes through Resilience4j circuit breaker, retry, and bulkhead controls.
- `dashboard-service/src/main/java/com/casestudy/insurancecampaign/dashboard/client/CampaignGrpcClient.java`
- `grpc-contract/src/main/proto/campaign.proto`
- `auth-service/src/main/java/com/casestudy/insurancecampaign/auth/client/LogServiceHttpClient.java`
- `auth-service/src/main/java/com/casestudy/insurancecampaign/auth/service/AuthAuditService.java`

#### Eventing and Log Persistence
Campaign changes and slow-request observations are emitted through Kafka; Log Service consumes slow-request events and sends failed processing to a DLQ. Log Service also receives auth audit HTTP calls. Both audit and slow-request records are stored in Elasticsearch, separating searchable operational/business logs from normal application file logs.
- `common/src/main/java/com/casestudy/insurancecampaign/common/event/CampaignStatusChangedEvent.java`
- `common/src/main/java/com/casestudy/insurancecampaign/common/web/SlowRequestLoggingFilter.java`
- `log-service/src/main/java/com/casestudy/insurancecampaign/log/service/SlowRequestLogConsumer.java`
- `log-service/src/main/java/com/casestudy/insurancecampaign/log/config/KafkaDlqConfiguration.java`

#### Shared Cross-Cutting and Observability
`common` standardizes API envelopes, exception mapping, Kafka JSON, virtual-thread setup, HTTP observations, and slow-request publication. Services export actuator metrics to Prometheus and traces through the OpenTelemetry Collector to Tempo; file logs flow via Promtail to Loki. Grafana provisions all three data sources and a campaign dashboard.
- `common/src/main/java/com/casestudy/insurancecampaign/common/exception/GlobalExceptionHandler.java`
- `observability/otel-collector/otel-collector.yml`
- `observability/prometheus/prometheus.yml`
- `observability/grafana/dashboards/campaign-logs-traces.json`

Main entry points: [`campaign-service/src/main/java/com/casestudy/insurancecampaign/campaign/service/CampaignService.java`](https://github.com/rapter1990/insurance-campaign-microservices/blob/main/campaign-service/src/main/java/com/casestudy/insurancecampaign/campaign/service/CampaignService.java) (Campaign Service), [`api-gateway/src/main/java/com/casestudy/insurancecampaign/gateway/filter/GatewayJwtAuthenticationFilter.java`](https://github.com/rapter1990/insurance-campaign-microservices/blob/main/api-gateway/src/main/java/com/casestudy/insurancecampaign/gateway/filter/GatewayJwtAuthenticationFilter.java) (API Gateway), [`auth-service/src/main/java/com/casestudy/insurancecampaign/auth/service/AuthService.java`](https://github.com/rapter1990/insurance-campaign-microservices/blob/main/auth-service/src/main/java/com/casestudy/insurancecampaign/auth/service/AuthService.java) (Auth Service), [`log-service/src/main/java/com/casestudy/insurancecampaign/log/service/SlowRequestLogConsumer.java`](https://github.com/rapter1990/insurance-campaign-microservices/blob/main/log-service/src/main/java/com/casestudy/insurancecampaign/log/service/SlowRequestLogConsumer.java) (Log Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_platform["Platform"]
  node_discovery{{"Discovery Server<br/>Spring service"}}
  node_config{{"Config Server<br/>Spring service"}}
  node_gateway{{"API Gateway<br/>edge service"}}
  node_security["Security Module<br/>shared library"]
  node_common["Common Module<br/>shared library"]
end

subgraph group_services["Business Services"]
  node_auth["Auth Service<br/>Spring service<br/>[AuthService.java]"]
  node_campaign["Campaign Service<br/>Spring service"]
  node_dashboard["Dashboard Service<br/>read API service"]
  node_log["Log Service<br/>event consumer"]
end

subgraph group_data["Data &amp; Eventing"]
  node_authdb[("Auth PostgreSQL<br/>identity database")]
  node_campaigndb[("Campaign PostgreSQL<br/>campaign database")]
  node_redis[("Redis<br/>cache and rate-limit store")]
  node_kafka["Kafka<br/>event broker"]
  node_dlq["Kafka DLQ<br/>dead-letter queue"]
  node_elasticsearch[("Elasticsearch<br/>log datastore")]
end

subgraph group_observability["Observability"]
  node_otel["OpenTelemetry Collector<br/>trace collector<br/>[otel-collector.yml]"]
  node_prometheus["Prometheus<br/>metrics store<br/>[prometheus.yml]"]
  node_loki[("Loki<br/>log store")]
  node_grafana["Grafana<br/>observability UI"]
end

node_gateway -->|"routes identity API"| node_auth
node_gateway -->|"routes campaign API"| node_campaign
node_gateway -->|"routes dashboard API"| node_dashboard
node_gateway -->|"rate-limit counters"| node_redis
node_security -.->|"JWT validation"| node_gateway
node_security -.->|"JWT validation"| node_campaign
node_auth -->|"users and tokens"| node_authdb
node_campaign -->|"campaigns and history"| node_campaigndb
node_campaign -->|"status-statistics cache"| node_redis
node_dashboard -->|"gRPC statistics and history"| node_campaign
node_auth -->|"non-blocking audit HTTP"| node_log
node_campaign -->|"campaign status changes"| node_kafka
node_common -.->|"publishes slow requests"| node_kafka
node_kafka -->|"slow-request events"| node_log
node_log -->|"failed consumption"| node_dlq
node_log -->|"audit and slow-request records"| node_elasticsearch
node_auth -.->|"registers"| node_discovery
node_campaign -.->|"registers"| node_discovery
node_dashboard -.->|"registers"| node_discovery
node_gateway -.->|"discovers services"| node_discovery
node_config -.->|"serves configuration"| node_auth
node_config -.->|"serves configuration"| node_campaign
node_config -.->|"serves configuration"| node_gateway
node_campaign -.->|"exports traces"| node_otel
node_otel -->|"Tempo traces"| node_grafana
node_prometheus -->|"metrics"| node_grafana
node_loki -->|"logs"| node_grafana

click node_discovery "https://github.com/rapter1990/insurance-campaign-microservices/blob/main/discovery-server/src/main/java/com/casestudy/insurancecampaign/discovery/DiscoveryServerApplication.java"
click node_config "https://github.com/rapter1990/insurance-campaign-microservices/blob/main/config-server/src/main/java/com/casestudy/insurancecampaign/config/ConfigServerApplication.java"
click node_gateway "https://github.com/rapter1990/insurance-campaign-microservices/blob/main/api-gateway/src/main/java/com/casestudy/insurancecampaign/gateway/filter/GatewayJwtAuthenticationFilter.java"
click node_security "https://github.com/rapter1990/insurance-campaign-microservices/blob/main/security/src/main/java/com/casestudy/insurancecampaign/security/ServiceSecurityConfiguration.java"
click node_common "https://github.com/rapter1990/insurance-campaign-microservices/blob/main/common/src/main/java/com/casestudy/insurancecampaign/common/web/SlowRequestLoggingFilter.java"
click node_auth "https://github.com/rapter1990/insurance-campaign-microservices/blob/main/auth-service/src/main/java/com/casestudy/insurancecampaign/auth/service/AuthService.java"
click node_campaign "https://github.com/rapter1990/insurance-campaign-microservices/blob/main/campaign-service/src/main/java/com/casestudy/insurancecampaign/campaign/service/CampaignService.java"
click node_dashboard "https://github.com/rapter1990/insurance-campaign-microservices/blob/main/dashboard-service/src/main/java/com/casestudy/insurancecampaign/dashboard/client/CampaignGrpcClient.java"
click node_log "https://github.com/rapter1990/insurance-campaign-microservices/blob/main/log-service/src/main/java/com/casestudy/insurancecampaign/log/service/SlowRequestLogConsumer.java"
click node_authdb "https://github.com/rapter1990/insurance-campaign-microservices/blob/main/auth-service/src/main/resources/db/changelog/db.changelog-master.yml"
click node_campaigndb "https://github.com/rapter1990/insurance-campaign-microservices/blob/main/campaign-service/src/main/java/com/casestudy/insurancecampaign/campaign/entity/CampaignEntity.java"
click node_redis "https://github.com/rapter1990/insurance-campaign-microservices/blob/main/api-gateway/src/main/java/com/casestudy/insurancecampaign/gateway/config/GatewayRateLimiterConfiguration.java"
click node_dlq "https://github.com/rapter1990/insurance-campaign-microservices/blob/main/log-service/src/main/java/com/casestudy/insurancecampaign/log/config/KafkaDlqConfiguration.java"
click node_otel "https://github.com/rapter1990/insurance-campaign-microservices/blob/main/observability/otel-collector/otel-collector.yml"
click node_prometheus "https://github.com/rapter1990/insurance-campaign-microservices/blob/main/observability/prometheus/prometheus.yml"
click node_grafana "https://github.com/rapter1990/insurance-campaign-microservices/blob/main/observability/grafana/dashboards/campaign-logs-traces.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_discovery,node_config,node_gateway,node_security,node_common toneBlue
class node_auth,node_campaign,node_dashboard,node_log toneAmber
class node_authdb,node_campaigndb,node_redis,node_kafka,node_dlq,node_elasticsearch toneMint
class node_otel,node_prometheus,node_loki,node_grafana toneRose
```

## Components

### Platform

- [Discovery Server](https://github.com/rapter1990/insurance-campaign-microservices/blob/main/discovery-server/src/main/java/com/casestudy/insurancecampaign/discovery/DiscoveryServerApplication.java): Spring service · Eureka service registration. · `discovery-server/src/main/java/com/casestudy/insurancecampaign/discovery/DiscoveryServerApplication.java`
- [Config Server](https://github.com/rapter1990/insurance-campaign-microservices/blob/main/config-server/src/main/java/com/casestudy/insurancecampaign/config/ConfigServerApplication.java): Spring service · Central Spring configuration. · `config-server/src/main/java/com/casestudy/insurancecampaign/config/ConfigServerApplication.java`
- [API Gateway](https://github.com/rapter1990/insurance-campaign-microservices/blob/main/api-gateway/src/main/java/com/casestudy/insurancecampaign/gateway/filter/GatewayJwtAuthenticationFilter.java): edge service · JWT-protected routing and Redis rate limiting. · `api-gateway/src/main/java/com/casestudy/insurancecampaign/gateway/filter/GatewayJwtAuthenticationFilter.java`
- [Security Module](https://github.com/rapter1990/insurance-campaign-microservices/blob/main/security/src/main/java/com/casestudy/insurancecampaign/security/ServiceSecurityConfiguration.java): shared library · Shared public-key JWT validation. · `security/src/main/java/com/casestudy/insurancecampaign/security/ServiceSecurityConfiguration.java`
- [Common Module](https://github.com/rapter1990/insurance-campaign-microservices/blob/main/common/src/main/java/com/casestudy/insurancecampaign/common/web/SlowRequestLoggingFilter.java): shared library · Shared web, events, Kafka, and observability conventions. · `common/src/main/java/com/casestudy/insurancecampaign/common/web/SlowRequestLoggingFilter.java`

### Business Services

- [Auth Service](https://github.com/rapter1990/insurance-campaign-microservices/blob/main/auth-service/src/main/java/com/casestudy/insurancecampaign/auth/service/AuthService.java): Spring service · Identity, roles, tokens, and RSA token signing. · `auth-service/src/main/java/com/casestudy/insurancecampaign/auth/service/AuthService.java`
- [Campaign Service](https://github.com/rapter1990/insurance-campaign-microservices/blob/main/campaign-service/src/main/java/com/casestudy/insurancecampaign/campaign/service/CampaignService.java): Spring service · Campaign lifecycle system of record; serves REST and gRPC. · `campaign-service/src/main/java/com/casestudy/insurancecampaign/campaign/service/CampaignService.java`
- [Dashboard Service](https://github.com/rapter1990/insurance-campaign-microservices/blob/main/dashboard-service/src/main/java/com/casestudy/insurancecampaign/dashboard/client/CampaignGrpcClient.java): read API service · Read-only campaign statistics and history façade. · `dashboard-service/src/main/java/com/casestudy/insurancecampaign/dashboard/client/CampaignGrpcClient.java`
- [Log Service](https://github.com/rapter1990/insurance-campaign-microservices/blob/main/log-service/src/main/java/com/casestudy/insurancecampaign/log/service/SlowRequestLogConsumer.java): event consumer · Persists auth-audit and slow-request logs. · `log-service/src/main/java/com/casestudy/insurancecampaign/log/service/SlowRequestLogConsumer.java`

### Data & Eventing

- [Auth PostgreSQL](https://github.com/rapter1990/insurance-campaign-microservices/blob/main/auth-service/src/main/resources/db/changelog/db.changelog-master.yml): identity database · `auth-service/src/main/resources/db/changelog/db.changelog-master.yml`
- [Campaign PostgreSQL](https://github.com/rapter1990/insurance-campaign-microservices/blob/main/campaign-service/src/main/java/com/casestudy/insurancecampaign/campaign/entity/CampaignEntity.java): campaign database · Campaign and status-history persistence. · `campaign-service/src/main/java/com/casestudy/insurancecampaign/campaign/entity/CampaignEntity.java`
- [Redis](https://github.com/rapter1990/insurance-campaign-microservices/blob/main/api-gateway/src/main/java/com/casestudy/insurancecampaign/gateway/config/GatewayRateLimiterConfiguration.java): cache and rate-limit store · `api-gateway/src/main/java/com/casestudy/insurancecampaign/gateway/config/GatewayRateLimiterConfiguration.java`
- **Kafka**: event broker · Carries campaign-change and slow-request events.
- [Kafka DLQ](https://github.com/rapter1990/insurance-campaign-microservices/blob/main/log-service/src/main/java/com/casestudy/insurancecampaign/log/config/KafkaDlqConfiguration.java): dead-letter queue · Failed slow-request processing. · `log-service/src/main/java/com/casestudy/insurancecampaign/log/config/KafkaDlqConfiguration.java`
- **Elasticsearch**: log datastore · Searchable audit and operational logs.

### Observability

- [OpenTelemetry Collector](https://github.com/rapter1990/insurance-campaign-microservices/blob/main/observability/otel-collector/otel-collector.yml): trace collector · Forwards service traces to Tempo. · `observability/otel-collector/otel-collector.yml`
- [Prometheus](https://github.com/rapter1990/insurance-campaign-microservices/blob/main/observability/prometheus/prometheus.yml): metrics store · Scrapes actuator metrics. · `observability/prometheus/prometheus.yml`
- **Loki**: log store · Receives file logs through Promtail.
- [Grafana](https://github.com/rapter1990/insurance-campaign-microservices/blob/main/observability/grafana/dashboards/campaign-logs-traces.json): observability UI · Campaign logs, metrics, and traces dashboard. · `observability/grafana/dashboards/campaign-logs-traces.json`

## Connections

- API Gateway → Auth Service: routes identity API
- API Gateway → Campaign Service: routes campaign API
- API Gateway → Dashboard Service: routes dashboard API
- API Gateway → Redis: rate-limit counters
- Security Module → API Gateway: JWT validation
- Security Module → Campaign Service: JWT validation
- Auth Service → Auth PostgreSQL: users and tokens
- Campaign Service → Campaign PostgreSQL: campaigns and history
- Campaign Service → Redis: status-statistics cache
- Dashboard Service → Campaign Service: gRPC statistics and history · Uses generated protobuf contracts.
- Auth Service → Log Service: non-blocking audit HTTP · Circuit breaker, retry, and bulkhead isolate authentication.
- Campaign Service → Kafka: campaign status changes
- Common Module → Kafka: publishes slow requests
- Kafka → Log Service: slow-request events
- Log Service → Kafka DLQ: failed consumption
- Log Service → Elasticsearch: audit and slow-request records
- Auth Service → Discovery Server: registers
- Campaign Service → Discovery Server: registers
- Dashboard Service → Discovery Server: registers
- API Gateway → Discovery Server: discovers services
- Config Server → Auth Service: serves configuration
- Config Server → Campaign Service: serves configuration
- Config Server → API Gateway: serves configuration
- Campaign Service → OpenTelemetry Collector: exports traces
- OpenTelemetry Collector → Grafana: Tempo traces
- Prometheus → Grafana: metrics
- Loki → Grafana: logs