# kumaran-nk/adaptive-rate-limiter architecture

> Architecture diagram of the GitHub repository kumaran-nk/adaptive-rate-limiter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kumaran-nk/adaptive-rate-limiter
- Repository: https://github.com/kumaran-nk/adaptive-rate-limiter

## Overview

#### Purpose and Runtime
This is a Java 21/Spring Boot distributed rate-limiting service designed to keep enforcing limits during Redis degradation. The application entry point is `src/main/java/com/ratelimiter/adaptive_rate_limiter/AdaptiveRateLimiterApplication.java`; runtime configuration is in `src/main/resources/application.properties`.

#### HTTP Enforcement Boundary
Spring MVC receives requests through controllers, while a global interceptor applies rate-limit decisions before protected handler execution. Primary HTTP-facing components are:
- `src/main/java/com/ratelimiter/adaptive_rate_limiter/interceptor/RateLimitInterceptor.java`
- `src/main/java/com/ratelimiter/adaptive_rate_limiter/controller/RateLimitTestController.java`
- `src/main/java/com/ratelimiter/adaptive_rate_limiter/config/WebMvcConfig.java`

Rejections and Redis-related failures are translated at the API boundary by `src/main/java/com/ratelimiter/adaptive_rate_limiter/exception/GlobalExceptionHandler.java` and `src/main/java/com/ratelimiter/adaptive_rate_limiter/exception/RedisExceptionHandler.java`.

#### Rate-Limit Orchestration
`src/main/java/com/ratelimiter/adaptive_rate_limiter/service/RateLimiterService.java` is the central decision coordinator. It selects a strategy based on the current health state and returns a `RateLimitDecision` model to the interceptor. The strategy abstraction and concrete policies are:
- `src/main/java/com/ratelimiter/adaptive_rate_limiter/service/strategy/RateLimitStrategy.java`
- `src/main/java/com/ratelimiter/adaptive_rate_limiter/service/strategy/SlidingWindowStrategy.java`
- `src/main/java/com/ratelimiter/adaptive_rate_limiter/service/strategy/TokenBucketStrategy.java`

#### Redis-Backed Consistent Path
In HEALTHY mode, sliding-window checks use Redis for distributed consistency. `src/main/java/com/ratelimiter/adaptive_rate_limiter/service/RedisRateCheckService.java` owns Redis checks, and `src/main/java/com/ratelimiter/adaptive_rate_limiter/redis/LuaScriptLoader.java` loads the atomic Lua implementation at `src/main/resources/lua/sliding_window.lua`. Redis connectivity and client setup are bounded by `src/main/java/com/ratelimiter/adaptive_rate_limiter/config/RedisConfig.java`.

#### Degradation and Local Fallback
When Redis cannot serve checks reliably, the service shifts from Redis-backed sliding windows to cached or local token-bucket limiting. The local state boundary is `src/main/java/com/ratelimiter/adaptive_rate_limiter/cache/LocalRateLimitCache.java`, configured through `src/main/java/com/ratelimiter/adaptive_rate_limiter/config/CacheConfig.java`. This deliberately trades distributed consistency for continued request protection.

#### Self-Healing State Machine
Health drives algorithm/data-source selection across HEALTHY, WARNING, DEGRADED, and RECOVERY states, represented by `src/main/java/com/ratelimiter/adaptive_rate_limiter/model/HealthState.java` and `src/main/java/com/ratelimiter/adaptive_rate_limiter/model/DegradationMode.java`. State transitions are governed by:
- `src/main/java/com/ratelimiter/adaptive_rate_limiter/service/state/StateMachine.java`
- `src/main/java/com/ratelimiter/adaptive_rate_limiter/service/health/RedisHealthProbe.java`
- `src/main/java/com/ratelimiter/adaptive_rate_limiter/service/health/CircuitBreakerMonitor.java`

Resilience4j configuration (`src/main/java/com/ratelimiter/adaptive_rate_limiter/config/Resilience4jConfig.java`) provides the circuit-breaker boundary around Redis failure behavior; recovery reintroduces Redis gradually.

#### Observability and Deployment
Micrometer metrics for limits and health state are emitted by `src/main/java/com/ratelimiter/adaptive_rate_limiter/metrics/RateLimiterMetrics.java` and `src/main/java/com/ratelimiter/adaptive_rate_limiter/metrics/HealthStateMetrics.java`, intended for Prometheus scraping via `monitoring/prometheus.yml`. The service is containerized by `Dockerfile` and deployed alongside Redis on Kubernetes through `k8s/deployment.yaml`, `k8s/redis-deployment.yaml`, and `k8s/hpa.yaml`. `src/main/java/com/ratelimiter/adaptive_rate_limiter/service/PodDiscoveryService.java` indicates cluster-aware pod discovery as an infrastructure integration.

Main entry points: [`src/main/java/com/ratelimiter/adaptive_rate_limiter/service/RateLimiterService.java`](https://github.com/kumaran-nk/adaptive-rate-limiter/blob/main/src/main/java/com/ratelimiter/adaptive_rate_limiter/service/RateLimiterService.java) (Decision coordinator), [`src/main/java/com/ratelimiter/adaptive_rate_limiter/interceptor/RateLimitInterceptor.java`](https://github.com/kumaran-nk/adaptive-rate-limiter/blob/main/src/main/java/com/ratelimiter/adaptive_rate_limiter/interceptor/RateLimitInterceptor.java) (Rate-limit interceptor), [`src/main/java/com/ratelimiter/adaptive_rate_limiter/service/state/StateMachine.java`](https://github.com/kumaran-nk/adaptive-rate-limiter/blob/main/src/main/java/com/ratelimiter/adaptive_rate_limiter/service/state/StateMachine.java) (Health state machine), [`src/main/java/com/ratelimiter/adaptive_rate_limiter/service/strategy/RateLimitStrategy.java`](https://github.com/kumaran-nk/adaptive-rate-limiter/blob/main/src/main/java/com/ratelimiter/adaptive_rate_limiter/service/strategy/RateLimitStrategy.java) (Rate-limit strategies)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_http["HTTP boundary"]
  node_app{{"Spring Boot app"}}
  node_mvc["MVC configuration<br/>web configuration<br/>[WebMvcConfig.java]"]
  node_interceptor["Rate-limit interceptor<br/>request gate"]
  node_controller["Test controller<br/>MVC controller"]
  node_exceptions["API exception translation<br/>exception handlers"]
end

subgraph group_limiting["Rate-limit core"]
  node_rate_service{{"Decision coordinator<br/>rate-limit service"}}
  node_strategies["Rate-limit strategies<br/>strategy policies"]
end

subgraph group_resilience["Resilience"]
  node_state_machine["Health state machine<br/>mode controller<br/>[StateMachine.java]"]
  node_health_probe["Redis health probe<br/>health monitor"]
  node_circuit["Circuit breaker monitor<br/>failure monitor"]
  node_resilience_config["Resilience4j config<br/>resilience configuration"]
end

subgraph group_storage["State and Redis"]
  node_redis_check["Redis rate checks<br/>distributed limiter"]
  node_lua["Sliding-window Lua<br/>atomic Redis script<br/>[sliding_window.lua]"]
  node_redis[("Redis<br/>external datastore")]
  node_local_cache["Local limit cache<br/>fallback state"]
end

subgraph group_operations["Operations"]
  node_metrics["Rate-limit metrics<br/>Micrometer metrics"]
  node_prometheus["Prometheus scrape config<br/>monitoring config<br/>[prometheus.yml]"]
  node_kubernetes["Kubernetes deployment<br/>cluster deployment<br/>[deployment.yaml]"]
  node_pod_discovery["Pod discovery<br/>cluster integration"]
end

node_app -->|"boots"| node_mvc
node_mvc -->|"registers"| node_interceptor
node_interceptor -->|"requests decision"| node_rate_service
node_interceptor -->|"permits request"| node_controller
node_exceptions -.->|"translates failures"| node_interceptor
node_rate_service -->|"selects policy"| node_strategies
node_rate_service -->|"reads mode"| node_state_machine
node_strategies -->|"healthy sliding window"| node_redis_check
node_strategies -->|"fallback token bucket"| node_local_cache
node_redis_check -->|"executes"| node_lua
node_lua -->|"runs atomically in"| node_redis
node_health_probe -->|"probes"| node_redis
node_circuit -.->|"monitors failures"| node_redis_check
node_health_probe -->|"reports health"| node_state_machine
node_circuit -->|"drives transitions"| node_state_machine
node_resilience_config -->|"configures"| node_circuit
node_rate_service -.->|"emits decisions"| node_metrics
node_state_machine -.->|"emits state"| node_metrics
node_prometheus -.->|"scrapes"| node_metrics
node_kubernetes -->|"deploys"| node_app
node_kubernetes -->|"deploys alongside"| node_redis
node_pod_discovery -.->|"discovers pods in"| node_kubernetes

click node_app "https://github.com/kumaran-nk/adaptive-rate-limiter/blob/main/src/main/java/com/ratelimiter/adaptive_rate_limiter/AdaptiveRateLimiterApplication.java"
click node_mvc "https://github.com/kumaran-nk/adaptive-rate-limiter/blob/main/src/main/java/com/ratelimiter/adaptive_rate_limiter/config/WebMvcConfig.java"
click node_interceptor "https://github.com/kumaran-nk/adaptive-rate-limiter/blob/main/src/main/java/com/ratelimiter/adaptive_rate_limiter/interceptor/RateLimitInterceptor.java"
click node_controller "https://github.com/kumaran-nk/adaptive-rate-limiter/blob/main/src/main/java/com/ratelimiter/adaptive_rate_limiter/controller/RateLimitTestController.java"
click node_exceptions "https://github.com/kumaran-nk/adaptive-rate-limiter/blob/main/src/main/java/com/ratelimiter/adaptive_rate_limiter/exception/GlobalExceptionHandler.java"
click node_rate_service "https://github.com/kumaran-nk/adaptive-rate-limiter/blob/main/src/main/java/com/ratelimiter/adaptive_rate_limiter/service/RateLimiterService.java"
click node_strategies "https://github.com/kumaran-nk/adaptive-rate-limiter/blob/main/src/main/java/com/ratelimiter/adaptive_rate_limiter/service/strategy/RateLimitStrategy.java"
click node_redis_check "https://github.com/kumaran-nk/adaptive-rate-limiter/blob/main/src/main/java/com/ratelimiter/adaptive_rate_limiter/service/RedisRateCheckService.java"
click node_lua "https://github.com/kumaran-nk/adaptive-rate-limiter/blob/main/src/main/resources/lua/sliding_window.lua"
click node_local_cache "https://github.com/kumaran-nk/adaptive-rate-limiter/blob/main/src/main/java/com/ratelimiter/adaptive_rate_limiter/cache/LocalRateLimitCache.java"
click node_state_machine "https://github.com/kumaran-nk/adaptive-rate-limiter/blob/main/src/main/java/com/ratelimiter/adaptive_rate_limiter/service/state/StateMachine.java"
click node_health_probe "https://github.com/kumaran-nk/adaptive-rate-limiter/blob/main/src/main/java/com/ratelimiter/adaptive_rate_limiter/service/health/RedisHealthProbe.java"
click node_circuit "https://github.com/kumaran-nk/adaptive-rate-limiter/blob/main/src/main/java/com/ratelimiter/adaptive_rate_limiter/service/health/CircuitBreakerMonitor.java"
click node_resilience_config "https://github.com/kumaran-nk/adaptive-rate-limiter/blob/main/src/main/java/com/ratelimiter/adaptive_rate_limiter/config/Resilience4jConfig.java"
click node_metrics "https://github.com/kumaran-nk/adaptive-rate-limiter/blob/main/src/main/java/com/ratelimiter/adaptive_rate_limiter/metrics/RateLimiterMetrics.java"
click node_prometheus "https://github.com/kumaran-nk/adaptive-rate-limiter/blob/main/monitoring/prometheus.yml"
click node_kubernetes "https://github.com/kumaran-nk/adaptive-rate-limiter/blob/main/k8s/deployment.yaml"
click node_pod_discovery "https://github.com/kumaran-nk/adaptive-rate-limiter/blob/main/src/main/java/com/ratelimiter/adaptive_rate_limiter/service/PodDiscoveryService.java"

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_app,node_mvc,node_interceptor,node_controller,node_exceptions toneBlue
class node_rate_service,node_strategies toneAmber
class node_state_machine,node_health_probe,node_circuit,node_resilience_config toneMint
class node_redis_check,node_lua,node_redis,node_local_cache toneRose
class node_metrics,node_prometheus,node_kubernetes,node_pod_discovery toneIndigo
```

## Components

### HTTP boundary

- [Spring Boot app](https://github.com/kumaran-nk/adaptive-rate-limiter/blob/main/src/main/java/com/ratelimiter/adaptive_rate_limiter/AdaptiveRateLimiterApplication.java): application · `src/main/java/com/ratelimiter/adaptive_rate_limiter/AdaptiveRateLimiterApplication.java`
- [MVC configuration](https://github.com/kumaran-nk/adaptive-rate-limiter/blob/main/src/main/java/com/ratelimiter/adaptive_rate_limiter/config/WebMvcConfig.java): web configuration · Registers the global enforcement interceptor. · `src/main/java/com/ratelimiter/adaptive_rate_limiter/config/WebMvcConfig.java`
- [Rate-limit interceptor](https://github.com/kumaran-nk/adaptive-rate-limiter/blob/main/src/main/java/com/ratelimiter/adaptive_rate_limiter/interceptor/RateLimitInterceptor.java): request gate · Applies decisions before protected handlers run. · `src/main/java/com/ratelimiter/adaptive_rate_limiter/interceptor/RateLimitInterceptor.java`
- [Test controller](https://github.com/kumaran-nk/adaptive-rate-limiter/blob/main/src/main/java/com/ratelimiter/adaptive_rate_limiter/controller/RateLimitTestController.java): MVC controller · `src/main/java/com/ratelimiter/adaptive_rate_limiter/controller/RateLimitTestController.java`
- [API exception translation](https://github.com/kumaran-nk/adaptive-rate-limiter/blob/main/src/main/java/com/ratelimiter/adaptive_rate_limiter/exception/GlobalExceptionHandler.java): exception handlers · Maps rejection and Redis failures to HTTP responses. · `src/main/java/com/ratelimiter/adaptive_rate_limiter/exception/GlobalExceptionHandler.java`

### Rate-limit core

- [Decision coordinator](https://github.com/kumaran-nk/adaptive-rate-limiter/blob/main/src/main/java/com/ratelimiter/adaptive_rate_limiter/service/RateLimiterService.java): rate-limit service · Selects policy from current health state and returns RateLimitDecision. · `src/main/java/com/ratelimiter/adaptive_rate_limiter/service/RateLimiterService.java`
- [Rate-limit strategies](https://github.com/kumaran-nk/adaptive-rate-limiter/blob/main/src/main/java/com/ratelimiter/adaptive_rate_limiter/service/strategy/RateLimitStrategy.java): strategy policies · Sliding-window and token-bucket policy abstraction. · `src/main/java/com/ratelimiter/adaptive_rate_limiter/service/strategy/RateLimitStrategy.java`

### Resilience

- [Health state machine](https://github.com/kumaran-nk/adaptive-rate-limiter/blob/main/src/main/java/com/ratelimiter/adaptive_rate_limiter/service/state/StateMachine.java): mode controller · Transitions HEALTHY, WARNING, DEGRADED, and RECOVERY modes. · `src/main/java/com/ratelimiter/adaptive_rate_limiter/service/state/StateMachine.java`
- [Redis health probe](https://github.com/kumaran-nk/adaptive-rate-limiter/blob/main/src/main/java/com/ratelimiter/adaptive_rate_limiter/service/health/RedisHealthProbe.java): health monitor · `src/main/java/com/ratelimiter/adaptive_rate_limiter/service/health/RedisHealthProbe.java`
- [Circuit breaker monitor](https://github.com/kumaran-nk/adaptive-rate-limiter/blob/main/src/main/java/com/ratelimiter/adaptive_rate_limiter/service/health/CircuitBreakerMonitor.java): failure monitor · `src/main/java/com/ratelimiter/adaptive_rate_limiter/service/health/CircuitBreakerMonitor.java`
- [Resilience4j config](https://github.com/kumaran-nk/adaptive-rate-limiter/blob/main/src/main/java/com/ratelimiter/adaptive_rate_limiter/config/Resilience4jConfig.java): resilience configuration · Bounds Redis failure behavior and gradual recovery. · `src/main/java/com/ratelimiter/adaptive_rate_limiter/config/Resilience4jConfig.java`

### State and Redis

- [Redis rate checks](https://github.com/kumaran-nk/adaptive-rate-limiter/blob/main/src/main/java/com/ratelimiter/adaptive_rate_limiter/service/RedisRateCheckService.java): distributed limiter · `src/main/java/com/ratelimiter/adaptive_rate_limiter/service/RedisRateCheckService.java`
- [Sliding-window Lua](https://github.com/kumaran-nk/adaptive-rate-limiter/blob/main/src/main/resources/lua/sliding_window.lua): atomic Redis script · `src/main/resources/lua/sliding_window.lua`
- **Redis**: external datastore · Distributed consistency store for healthy-mode checks.
- [Local limit cache](https://github.com/kumaran-nk/adaptive-rate-limiter/blob/main/src/main/java/com/ratelimiter/adaptive_rate_limiter/cache/LocalRateLimitCache.java): fallback state · Local token-bucket state during degradation. · `src/main/java/com/ratelimiter/adaptive_rate_limiter/cache/LocalRateLimitCache.java`

### Operations

- [Rate-limit metrics](https://github.com/kumaran-nk/adaptive-rate-limiter/blob/main/src/main/java/com/ratelimiter/adaptive_rate_limiter/metrics/RateLimiterMetrics.java): Micrometer metrics · Emits limit and health-state telemetry. · `src/main/java/com/ratelimiter/adaptive_rate_limiter/metrics/RateLimiterMetrics.java`
- [Prometheus scrape config](https://github.com/kumaran-nk/adaptive-rate-limiter/blob/main/monitoring/prometheus.yml): monitoring config · `monitoring/prometheus.yml`
- [Kubernetes deployment](https://github.com/kumaran-nk/adaptive-rate-limiter/blob/main/k8s/deployment.yaml): cluster deployment · Deploys service, Redis, and horizontal scaling. · `k8s/deployment.yaml`
- [Pod discovery](https://github.com/kumaran-nk/adaptive-rate-limiter/blob/main/src/main/java/com/ratelimiter/adaptive_rate_limiter/service/PodDiscoveryService.java): cluster integration · `src/main/java/com/ratelimiter/adaptive_rate_limiter/service/PodDiscoveryService.java`

## Connections

- Spring Boot app → MVC configuration: boots
- MVC configuration → Rate-limit interceptor: registers
- Rate-limit interceptor → Decision coordinator: requests decision
- Rate-limit interceptor → Test controller: permits request
- API exception translation → Rate-limit interceptor: translates failures
- Decision coordinator → Rate-limit strategies: selects policy
- Decision coordinator → Health state machine: reads mode
- Rate-limit strategies → Redis rate checks: healthy sliding window
- Rate-limit strategies → Local limit cache: fallback token bucket
- Redis rate checks → Sliding-window Lua: executes
- Sliding-window Lua → Redis: runs atomically in
- Redis health probe → Redis: probes
- Circuit breaker monitor → Redis rate checks: monitors failures
- Redis health probe → Health state machine: reports health
- Circuit breaker monitor → Health state machine: drives transitions
- Resilience4j config → Circuit breaker monitor: configures
- Decision coordinator → Rate-limit metrics: emits decisions
- Health state machine → Rate-limit metrics: emits state
- Prometheus scrape config → Rate-limit metrics: scrapes
- Kubernetes deployment → Spring Boot app: deploys
- Kubernetes deployment → Redis: deploys alongside
- Pod discovery → Kubernetes deployment: discovers pods in