# rohit8020/secure-auth-service architecture

> Architecture diagram of the GitHub repository rohit8020/secure-auth-service, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rohit8020/secure-auth-service
- Repository: https://github.com/rohit8020/secure-auth-service

## Overview

1. **Overall shape**
   This is a Spring Boot 3.5.9 microservices platform for an insurance domain. The system is split into four independently deployable services: an edge `api-gateway`, `auth-service`, `policy-service`, and `claims-service`. Each service has its own Spring Boot application, Dockerfile, and Kubernetes manifests.

2. **Edge and request entry**
   All public traffic is intended to enter through the `api-gateway` on port `8080`. The gateway routes requests to `/api/auth/**`, `/api/policies/**`, and `/api/claims/**`, so it acts as the single external boundary for the platform. It also enforces JWT-based access control and Redis-backed rate limiting.

3. **Identity and access management**
   `auth-service` is the identity provider for the platform. It handles registration, login, token refresh, current-user lookup, and admin user creation. It uses MySQL for user and refresh-token persistence, issues JWTs, and centralizes role-based access control for `POLICYHOLDER`, `AGENT`, and `ADMIN`.

4. **Policy domain**
   `policy-service` owns policy lifecycle logic: issue, renew, lapse, list, and fetch-by-id. It is backed by PostgreSQL and publishes policy domain events to Kafka. The service also exposes an internal controller, which suggests a separate path for service-to-service or projection-related access distinct from the public API.

5. **Claims domain**
   `claims-service` owns claim submission and claim decision workflows: submit, verify, approve, reject, and query claims. It uses Redis as its primary data store, which is unusual compared with the other services and is likely intentional for fast claim-state access or lightweight persistence. It also maintains policy projections locally so claim processing can be done without synchronous dependency on the policy database.

6. **Event-driven coupling**
   Kafka is the main integration mechanism between bounded contexts. The `policy-service` emits policy events, and the `claims-service` consumes policy-related events to keep its `PolicyProjection` model in sync. This means claims processing is designed to be resilient to policy-service availability after the initial event is published.

7. **Security boundary inside services**
   Each business service has its own Spring Security configuration, plus service-specific security helpers such as `AuthenticatedActor` and `SecurityUtils`. That indicates authorization is not only enforced at the gateway; individual services also validate roles and identity context for domain actions.

8. **Data ownership and storage**
   The persistence boundary is per-service: MySQL for auth, PostgreSQL for policies, and Redis for claims plus gateway rate limiting. There is no shared database. This strongly suggests a classic microservice “database-per-service” architecture with service-local entities, repositories, and exception handling.

9. **Shared service structure**
   The services follow a common layered layout: controllers, DTOs, entities, repositories, services, security, and exception handlers. That makes the codebase consistent and diagram-friendly: HTTP enters controllers, business logic sits in service classes, persistence is isolated in repositories, and errors are normalized by global exception handlers.

10. **Deployment topology**
   The repository supports both local containerized execution and Kubernetes deployment. `docker-compose.yml` and the `k8s/` manifests define the same topology: gateway, auth, policy, claims, plus shared infrastructure for MySQL, PostgreSQL, Redis, and Kafka. The ingress manifest indicates Kubernetes is meant to expose the gateway externally.

11. **Operational flow**
   A typical request flow is: client → gateway → target service → service-local store, with authentication/authorization checked via JWT and roles. For policy-to-claims synchronization, the flow is asynchronous: policy-service → Kafka → claims-service projection update. Rate limiting happens at the gateway before requests reach the domain services.

12. **Delivery and verification**
   The repo includes GitHub Actions CI/CD, Maven multi-module build files, service-level tests, and a smoke-test script for end-to-end validation against the Compose stack. That means the architecture is designed not just for runtime separation, but also for independently testable services with a shared build pipeline.

Main entry points: [`docker-compose.yml`](https://github.com/rohit8020/secure-auth-service/blob/main/docker-compose.yml) (Deployments), [`services/api-gateway`](https://github.com/rohit8020/secure-auth-service/tree/main/services/api-gateway) (API Gateway), [`services/auth-service`](https://github.com/rohit8020/secure-auth-service/tree/main/services/auth-service) (Auth Service), [`services/policy-service`](https://github.com/rohit8020/secure-auth-service/tree/main/services/policy-service) (Policy Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_platform["Platform"]
  node_gateway["API Gateway<br/>edge gateway"]
  node_auth_service["Auth Service<br/>identity service"]
  node_policy_service["Policy Service<br/>policy domain"]
  node_claims_service["Claims Service<br/>claims domain"]
  node_gateway_security["Gateway Security<br/>jwt + routing"]
  node_gateway_rate_limit["Rate Limiter<br/>redis filter"]
  node_auth_controller["Auth API<br/>rest controller"]
  node_admin_controller["Admin API<br/>rest controller"]
  node_jwt_util["JWT Utils<br/>token service<br/>[JwtUtil.java]"]
  node_policy_controller["Policy API<br/>rest controller"]
  node_internal_policy_controller["Internal API<br/>internal controller"]
  node_policy_events["Policy Events<br/>event publisher<br/>[PolicyEvent.java]"]
  node_claim_controller["Claim API<br/>rest controller"]
  node_policy_projection_client["Projection Sync<br/>event consumer"]
end

subgraph group_infra["Infrastructure"]
  node_auth_db[("MySQL<br/>auth datastore")]
  node_policy_db[("PostgreSQL<br/>policy datastore")]
  node_claims_store[("Redis<br/>claims datastore")]
  node_kafka_bus["Kafka<br/>event bus"]
end

subgraph group_delivery["Delivery"]
  node_compose_k8s["Deployments<br/>runtime manifests<br/>[docker-compose.yml]"]
  node_ci_cd["CI/CD<br/>pipeline<br/>[ci-cd.yaml]"]
  node_smoke_test["Smoke Test<br/>validation script<br/>[smoke-test.sh]"]
end

node_gateway -->|"secured by"| node_gateway_security
node_gateway -->|"limits"| node_gateway_rate_limit
node_gateway -->|"routes /api/auth"| node_auth_service
node_gateway -->|"routes /api/policies"| node_policy_service
node_gateway -->|"routes /api/claims"| node_claims_service
node_auth_service -->|"serves"| node_auth_controller
node_auth_service -->|"serves"| node_admin_controller
node_auth_service -->|"issues tokens"| node_jwt_util
node_auth_service -->|"persists users"| node_auth_db
node_policy_service -->|"serves"| node_policy_controller
node_policy_service -->|"serves"| node_internal_policy_controller
node_policy_service -->|"publishes"| node_policy_events
node_policy_service -->|"persists policies"| node_policy_db
node_claims_service -->|"serves"| node_claim_controller
node_claims_service -->|"consumes"| node_policy_projection_client
node_claims_service -->|"persists claims"| node_claims_store
node_policy_events -->|"emits via"| node_kafka_bus
node_kafka_bus -->|"delivers to"| node_policy_projection_client
node_compose_k8s -->|"deploys"| node_gateway
node_compose_k8s -->|"deploys"| node_auth_service
node_compose_k8s -->|"deploys"| node_policy_service
node_compose_k8s -->|"deploys"| node_claims_service
node_compose_k8s -->|"provisions"| node_auth_db
node_compose_k8s -->|"provisions"| node_policy_db
node_compose_k8s -->|"provisions"| node_claims_store
node_compose_k8s -->|"provisions"| node_kafka_bus
node_ci_cd -->|"builds"| node_gateway
node_ci_cd -->|"builds"| node_auth_service
node_ci_cd -->|"builds"| node_policy_service
node_ci_cd -->|"builds"| node_claims_service
node_smoke_test -->|"validates"| node_compose_k8s

click node_gateway "https://github.com/rohit8020/secure-auth-service/tree/main/services/api-gateway"
click node_auth_service "https://github.com/rohit8020/secure-auth-service/tree/main/services/auth-service"
click node_policy_service "https://github.com/rohit8020/secure-auth-service/tree/main/services/policy-service"
click node_claims_service "https://github.com/rohit8020/secure-auth-service/tree/main/services/claims-service"
click node_gateway_security "https://github.com/rohit8020/secure-auth-service/blob/main/services/api-gateway/src/main/java/com/rohit8020/apigateway/config/SecurityConfig.java"
click node_gateway_rate_limit "https://github.com/rohit8020/secure-auth-service/blob/main/services/api-gateway/src/main/java/com/rohit8020/apigateway/filter/RedisRateLimitFilter.java"
click node_auth_controller "https://github.com/rohit8020/secure-auth-service/blob/main/services/auth-service/src/main/java/com/rohit8020/authservice/controller/AuthController.java"
click node_admin_controller "https://github.com/rohit8020/secure-auth-service/blob/main/services/auth-service/src/main/java/com/rohit8020/authservice/controller/AdminUserController.java"
click node_jwt_util "https://github.com/rohit8020/secure-auth-service/blob/main/services/auth-service/src/main/java/com/rohit8020/authservice/security/JwtUtil.java"
click node_policy_controller "https://github.com/rohit8020/secure-auth-service/blob/main/services/policy-service/src/main/java/com/rohit8020/policyservice/controller/PolicyController.java"
click node_internal_policy_controller "https://github.com/rohit8020/secure-auth-service/blob/main/services/policy-service/src/main/java/com/rohit8020/policyservice/controller/InternalPolicyController.java"
click node_policy_events "https://github.com/rohit8020/secure-auth-service/blob/main/services/policy-service/src/main/java/com/rohit8020/policyservice/event/PolicyEvent.java"
click node_claim_controller "https://github.com/rohit8020/secure-auth-service/blob/main/services/claims-service/src/main/java/com/rohit8020/claimsservice/controller/ClaimController.java"
click node_policy_projection_client "https://github.com/rohit8020/secure-auth-service/blob/main/services/claims-service/src/main/java/com/rohit8020/claimsservice/service/PolicyProjectionClient.java"
click node_auth_db "https://github.com/rohit8020/secure-auth-service/tree/main/k8s/mysql"
click node_policy_db "https://github.com/rohit8020/secure-auth-service/tree/main/k8s/postgres"
click node_claims_store "https://github.com/rohit8020/secure-auth-service/tree/main/k8s/redis"
click node_kafka_bus "https://github.com/rohit8020/secure-auth-service/tree/main/k8s/kafka"
click node_compose_k8s "https://github.com/rohit8020/secure-auth-service/blob/main/docker-compose.yml"
click node_ci_cd "https://github.com/rohit8020/secure-auth-service/blob/main/.github/workflows/ci-cd.yaml"
click node_smoke_test "https://github.com/rohit8020/secure-auth-service/blob/main/scripts/smoke-test.sh"

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_gateway,node_auth_service,node_policy_service,node_claims_service,node_gateway_security,node_gateway_rate_limit,node_auth_controller,node_admin_controller,node_jwt_util,node_policy_controller,node_internal_policy_controller,node_policy_events,node_claim_controller,node_policy_projection_client toneBlue
class node_auth_db,node_policy_db,node_claims_store,node_kafka_bus toneAmber
class node_compose_k8s,node_ci_cd,node_smoke_test toneMint
```

## Components

### Platform

Top-level microservices platform and shared runtime boundaries.

- [API Gateway](https://github.com/rohit8020/secure-auth-service/tree/main/services/api-gateway): edge gateway · Single external entry point; routes public API traffic, enforces JWT access, and applies Redis-backed rate limiting. · `services/api-gateway`
- [Auth Service](https://github.com/rohit8020/secure-auth-service/tree/main/services/auth-service): identity service · Handles registration, login, token refresh, current-user lookup, and admin user creation. · `services/auth-service`
- [Policy Service](https://github.com/rohit8020/secure-auth-service/tree/main/services/policy-service): policy domain · Owns policy lifecycle operations and publishes policy events. · `services/policy-service`
- [Claims Service](https://github.com/rohit8020/secure-auth-service/tree/main/services/claims-service): claims domain · Owns claim submission and decision workflows and maintains local policy projections. · `services/claims-service`
- [Gateway Security](https://github.com/rohit8020/secure-auth-service/blob/main/services/api-gateway/src/main/java/com/rohit8020/apigateway/config/SecurityConfig.java): jwt + routing · Gateway security configuration and identity propagation filter chain. · `services/api-gateway/src/main/java/com/rohit8020/apigateway/config/SecurityConfig.java`
- [Rate Limiter](https://github.com/rohit8020/secure-auth-service/blob/main/services/api-gateway/src/main/java/com/rohit8020/apigateway/filter/RedisRateLimitFilter.java): redis filter · Redis-backed request throttling before requests reach business services. · `services/api-gateway/src/main/java/com/rohit8020/apigateway/filter/RedisRateLimitFilter.java`
- [Auth API](https://github.com/rohit8020/secure-auth-service/blob/main/services/auth-service/src/main/java/com/rohit8020/authservice/controller/AuthController.java): rest controller · Public auth endpoints for registration, login, refresh, and profile lookup. · `services/auth-service/src/main/java/com/rohit8020/authservice/controller/AuthController.java`
- [Admin API](https://github.com/rohit8020/secure-auth-service/blob/main/services/auth-service/src/main/java/com/rohit8020/authservice/controller/AdminUserController.java): rest controller · Admin-only user creation endpoints. · `services/auth-service/src/main/java/com/rohit8020/authservice/controller/AdminUserController.java`
- [JWT Utils](https://github.com/rohit8020/secure-auth-service/blob/main/services/auth-service/src/main/java/com/rohit8020/authservice/security/JwtUtil.java): token service · Issues and validates JWTs for platform authentication. · `services/auth-service/src/main/java/com/rohit8020/authservice/security/JwtUtil.java`
- [Policy API](https://github.com/rohit8020/secure-auth-service/blob/main/services/policy-service/src/main/java/com/rohit8020/policyservice/controller/PolicyController.java): rest controller · Public policy lifecycle endpoints for issue, renew, lapse, list, and fetch. · `services/policy-service/src/main/java/com/rohit8020/policyservice/controller/PolicyController.java`
- [Internal API](https://github.com/rohit8020/secure-auth-service/blob/main/services/policy-service/src/main/java/com/rohit8020/policyservice/controller/InternalPolicyController.java): internal controller · Non-public policy access path for service-to-service or projection-related use. · `services/policy-service/src/main/java/com/rohit8020/policyservice/controller/InternalPolicyController.java`
- [Policy Events](https://github.com/rohit8020/secure-auth-service/blob/main/services/policy-service/src/main/java/com/rohit8020/policyservice/event/PolicyEvent.java): event publisher · Publishes policy domain events for downstream consumers. · `services/policy-service/src/main/java/com/rohit8020/policyservice/event/PolicyEvent.java`
- [Claim API](https://github.com/rohit8020/secure-auth-service/blob/main/services/claims-service/src/main/java/com/rohit8020/claimsservice/controller/ClaimController.java): rest controller · Claim submission, verification, approval, rejection, and query endpoints. · `services/claims-service/src/main/java/com/rohit8020/claimsservice/controller/ClaimController.java`
- [Projection Sync](https://github.com/rohit8020/secure-auth-service/blob/main/services/claims-service/src/main/java/com/rohit8020/claimsservice/service/PolicyProjectionClient.java): event consumer · Consumes policy-related updates and keeps the local policy projection current. · `services/claims-service/src/main/java/com/rohit8020/claimsservice/service/PolicyProjectionClient.java`

### Infrastructure

Shared data stores, messaging, and deployment surfaces.

- [MySQL](https://github.com/rohit8020/secure-auth-service/tree/main/k8s/mysql): auth datastore · Persists auth users and refresh tokens. · `k8s/mysql`
- [PostgreSQL](https://github.com/rohit8020/secure-auth-service/tree/main/k8s/postgres): policy datastore · Persists policy records for the policy service. · `k8s/postgres`
- [Redis](https://github.com/rohit8020/secure-auth-service/tree/main/k8s/redis): claims datastore · Primary store for claim records and policy projections; also used by the gateway for rate limiting. · `k8s/redis`
- [Kafka](https://github.com/rohit8020/secure-auth-service/tree/main/k8s/kafka): event bus · Asynchronous integration backbone between policy and claims. · `k8s/kafka`

### Delivery

Build, container, and deployment tooling.

- [Deployments](https://github.com/rohit8020/secure-auth-service/blob/main/docker-compose.yml): runtime manifests · Docker Compose and Kubernetes manifests for the full platform topology. · `docker-compose.yml`
- [CI/CD](https://github.com/rohit8020/secure-auth-service/blob/main/.github/workflows/ci-cd.yaml): pipeline · GitHub Actions build and verification pipeline. · `.github/workflows/ci-cd.yaml`
- [Smoke Test](https://github.com/rohit8020/secure-auth-service/blob/main/scripts/smoke-test.sh): validation script · End-to-end verification against the containerized stack. · `scripts/smoke-test.sh`

## Connections

- API Gateway → Gateway Security: secured by · Gateway requests pass through JWT and routing security rules.
- API Gateway → Rate Limiter: limits · Public traffic is throttled before forwarding to services.
- API Gateway → Auth Service: routes /api/auth · Authentication traffic is forwarded to the auth service.
- API Gateway → Policy Service: routes /api/policies · Policy traffic is forwarded to the policy service.
- API Gateway → Claims Service: routes /api/claims · Claims traffic is forwarded to the claims service.
- Auth Service → Auth API: serves · Auth endpoints expose registration and token workflows.
- Auth Service → Admin API: serves · Admin endpoints create bootstrap and privileged users.
- Auth Service → JWT Utils: issues tokens · JWT creation and validation are centralized here.
- Auth Service → MySQL: persists users · Users and refresh tokens are stored in MySQL.
- Policy Service → Policy API: serves · Public policy lifecycle endpoints are exposed here.
- Policy Service → Internal API: serves · Internal access path supports service-to-service usage.
- Policy Service → Policy Events: publishes · Policy changes are emitted as domain events.
- Policy Service → PostgreSQL: persists policies · Policy state is stored in PostgreSQL.
- Claims Service → Claim API: serves · Claim workflow endpoints are exposed here.
- Claims Service → Projection Sync: consumes · Claims service keeps local policy views in sync asynchronously.
- Claims Service → Redis: persists claims · Claims and projections are stored in Redis.
- Policy Events → Kafka: emits via · Policy domain events flow through Kafka.
- Kafka → Projection Sync: delivers to · Claims service consumes policy updates from the bus.
- Deployments → API Gateway: deploys · Gateway is part of the composed and Kubernetes topology.
- Deployments → Auth Service: deploys · Auth service is part of the composed and Kubernetes topology.
- Deployments → Policy Service: deploys · Policy service is part of the composed and Kubernetes topology.
- Deployments → Claims Service: deploys · Claims service is part of the composed and Kubernetes topology.
- Deployments → MySQL: provisions · MySQL is provisioned for auth persistence.
- Deployments → PostgreSQL: provisions · PostgreSQL is provisioned for policy persistence.
- Deployments → Redis: provisions · Redis is provisioned for claims storage and gateway rate limiting.
- Deployments → Kafka: provisions · Kafka is provisioned for asynchronous integration.
- CI/CD → API Gateway: builds · Gateway is built and tested in the pipeline.
- CI/CD → Auth Service: builds · Auth service is built and tested in the pipeline.
- CI/CD → Policy Service: builds · Policy service is built and tested in the pipeline.
- CI/CD → Claims Service: builds · Claims service is built and tested in the pipeline.
- Smoke Test → Deployments: validates · Smoke tests exercise the local deployed topology.
