# ramantiw45/api-rate-limiter architecture

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

- Interactive diagram: https://gitdiagram.com/ramantiw45/api-rate-limiter
- Repository: https://github.com/ramantiw45/api-rate-limiter

## Overview

This is a reactive API rate-limiting gateway: clients send protected echo requests, API keys are validated and stripped, requests are bucketed by client identity in Redis, and surviving traffic is proxied under timeout/circuit-breaker protection. Logging/tracing and actuator security are additional product capabilities. Rate-limit route wiring, observability configuration, and Redis HA details are documented in the README but their implementation paths were not sampled; their links are therefore documented or left unverified.

Main entry points: [`src/main/java/com/api/ratelimiter/config/RateLimiterConfig.java`](https://github.com/ramantiw45/api-rate-limiter/blob/main/src/main/java/com/api/ratelimiter/config/RateLimiterConfig.java) (Token bucket limiter), [`src/main/java/com/api/ratelimiter/config/ResilienceConfig.java`](https://github.com/ramantiw45/api-rate-limiter/blob/main/src/main/java/com/api/ratelimiter/config/ResilienceConfig.java) (Circuit breaker and timeout), [`src/main/java/com/api/ratelimiter/filter/ApiKeyValidationFilter.java`](https://github.com/ramantiw45/api-rate-limiter/blob/main/src/main/java/com/api/ratelimiter/filter/ApiKeyValidationFilter.java) (API key filter), [`src/main/java/com/api/ratelimiter/ApiRateLimiterApplication.java`](https://github.com/ramantiw45/api-rate-limiter/blob/main/src/main/java/com/api/ratelimiter/ApiRateLimiterApplication.java) (Reactive gateway)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingress["Gateway ingress"]
  node_app["Reactive gateway"]
  node_access["Request tracing"]
end

subgraph group_protection["Traffic protection"]
  node_keyresolver["Client key resolution"]
  node_ratelimit["Token bucket limiter"]
  node_redis[("Redis rate state")]
  node_resilience["Circuit breaker and timeout"]
  node_cbprops["Breaker properties"]
  node_fallback["503 fallback"]
  node_rateerrors["Rate-limit error handling"]
end

subgraph group_identity["Identity security"]
  node_authfilter["API key filter"]
  node_validator["Key validator"]
  node_hasher["Key hashing<br/>[ApiKeyHasher.java]"]
  node_securityprops["Security properties"]
  node_actuatorsecurity["Actuator access control"]
end

subgraph group_operations["Operations and telemetry"]
  node_prometheus["Prometheus metrics"]
  node_grafana["Grafana dashboards"]
  node_zipkin["Zipkin tracing"]
  node_sentinel["Redis Sentinel HA"]
end

node_client(("API client"))
node_upstream["Echo upstream service"]

node_client -->|"sends requests"| node_app
node_app -.->|"enters filter"| node_access
node_access -->|"continues chain"| node_authfilter
node_authfilter -->|"validates key"| node_validator
node_validator -->|"hashes candidate"| node_hasher
node_validator -->|"loads digest settings"| node_securityprops
node_authfilter -->|"stores identity hash"| node_hasher
node_authfilter -.->|"passes validated identity"| node_keyresolver
node_keyresolver -->|"hashes fallback key"| node_hasher
node_keyresolver -.->|"provides client key"| node_ratelimit
node_ratelimit -.->|"checks token bucket"| node_redis
node_ratelimit -.->|"rejects exhausted bucket"| node_rateerrors
node_ratelimit -.->|"permits requests onward"| node_resilience
node_resilience -->|"loads breaker settings"| node_cbprops
node_resilience -.->|"proxies protected calls"| node_upstream
node_resilience -->|"dispatches on failure"| node_fallback
node_actuatorsecurity -->|"loads access settings"| node_securityprops
node_app -.->|"exposes metrics"| node_prometheus
node_prometheus -.->|"feeds dashboards"| node_grafana
node_access -.->|"propagates trace context"| node_zipkin
node_sentinel -.->|"manages failover"| node_redis

click node_app "https://github.com/ramantiw45/api-rate-limiter/blob/main/src/main/java/com/api/ratelimiter/ApiRateLimiterApplication.java"
click node_access "https://github.com/ramantiw45/api-rate-limiter/blob/main/src/main/java/com/api/ratelimiter/filter/GlobalLoggingFilter.java"
click node_authfilter "https://github.com/ramantiw45/api-rate-limiter/blob/main/src/main/java/com/api/ratelimiter/filter/ApiKeyValidationFilter.java"
click node_validator "https://github.com/ramantiw45/api-rate-limiter/blob/main/src/main/java/com/api/ratelimiter/security/ApiKeyValidator.java"
click node_hasher "https://github.com/ramantiw45/api-rate-limiter/blob/main/src/main/java/com/api/ratelimiter/security/ApiKeyHasher.java"
click node_securityprops "https://github.com/ramantiw45/api-rate-limiter/blob/main/src/main/java/com/api/ratelimiter/config/GatewaySecurityProperties.java"
click node_actuatorsecurity "https://github.com/ramantiw45/api-rate-limiter/blob/main/src/main/java/com/api/ratelimiter/config/SecurityConfig.java"
click node_keyresolver "https://github.com/ramantiw45/api-rate-limiter/blob/main/src/main/java/com/api/ratelimiter/config/KeyResolverConfig.java"
click node_ratelimit "https://github.com/ramantiw45/api-rate-limiter/blob/main/src/main/java/com/api/ratelimiter/config/RateLimiterConfig.java"
click node_resilience "https://github.com/ramantiw45/api-rate-limiter/blob/main/src/main/java/com/api/ratelimiter/config/ResilienceConfig.java"
click node_cbprops "https://github.com/ramantiw45/api-rate-limiter/blob/main/src/main/java/com/api/ratelimiter/config/CircuitBreakerProperties.java"
click node_fallback "https://github.com/ramantiw45/api-rate-limiter/blob/main/src/main/java/com/api/ratelimiter/controller/FallbackController.java"
click node_rateerrors "https://github.com/ramantiw45/api-rate-limiter/blob/main/src/main/java/com/api/ratelimiter/filter/RateLimitErrorFilter.java"
click node_grafana "https://github.com/ramantiw45/api-rate-limiter/blob/main/docker/grafana/dashboards/rate-limiter-dashboard.json"
click node_sentinel "https://github.com/ramantiw45/api-rate-limiter/blob/main/docker-compose.ha.yml"

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_access,node_client toneBlue
class node_keyresolver,node_ratelimit,node_redis,node_resilience,node_cbprops,node_fallback,node_rateerrors toneAmber
class node_authfilter,node_validator,node_hasher,node_securityprops,node_actuatorsecurity toneMint
class node_prometheus,node_grafana,node_zipkin,node_sentinel toneRose
class node_upstream toneIndigo
```

## Components

### Gateway ingress

- [Reactive gateway](https://github.com/ramantiw45/api-rate-limiter/blob/main/src/main/java/com/api/ratelimiter/ApiRateLimiterApplication.java): `src/main/java/com/api/ratelimiter/ApiRateLimiterApplication.java`
- [Request tracing](https://github.com/ramantiw45/api-rate-limiter/blob/main/src/main/java/com/api/ratelimiter/filter/GlobalLoggingFilter.java): `src/main/java/com/api/ratelimiter/filter/GlobalLoggingFilter.java`

### Traffic protection

- [Client key resolution](https://github.com/ramantiw45/api-rate-limiter/blob/main/src/main/java/com/api/ratelimiter/config/KeyResolverConfig.java): `src/main/java/com/api/ratelimiter/config/KeyResolverConfig.java`
- [Token bucket limiter](https://github.com/ramantiw45/api-rate-limiter/blob/main/src/main/java/com/api/ratelimiter/config/RateLimiterConfig.java): `src/main/java/com/api/ratelimiter/config/RateLimiterConfig.java`
- **Redis rate state**
- [Circuit breaker and timeout](https://github.com/ramantiw45/api-rate-limiter/blob/main/src/main/java/com/api/ratelimiter/config/ResilienceConfig.java): `src/main/java/com/api/ratelimiter/config/ResilienceConfig.java`
- [Breaker properties](https://github.com/ramantiw45/api-rate-limiter/blob/main/src/main/java/com/api/ratelimiter/config/CircuitBreakerProperties.java): `src/main/java/com/api/ratelimiter/config/CircuitBreakerProperties.java`
- [503 fallback](https://github.com/ramantiw45/api-rate-limiter/blob/main/src/main/java/com/api/ratelimiter/controller/FallbackController.java): `src/main/java/com/api/ratelimiter/controller/FallbackController.java`
- [Rate-limit error handling](https://github.com/ramantiw45/api-rate-limiter/blob/main/src/main/java/com/api/ratelimiter/filter/RateLimitErrorFilter.java): `src/main/java/com/api/ratelimiter/filter/RateLimitErrorFilter.java`

### Identity security

- [API key filter](https://github.com/ramantiw45/api-rate-limiter/blob/main/src/main/java/com/api/ratelimiter/filter/ApiKeyValidationFilter.java): `src/main/java/com/api/ratelimiter/filter/ApiKeyValidationFilter.java`
- [Key validator](https://github.com/ramantiw45/api-rate-limiter/blob/main/src/main/java/com/api/ratelimiter/security/ApiKeyValidator.java): `src/main/java/com/api/ratelimiter/security/ApiKeyValidator.java`
- [Key hashing](https://github.com/ramantiw45/api-rate-limiter/blob/main/src/main/java/com/api/ratelimiter/security/ApiKeyHasher.java): `src/main/java/com/api/ratelimiter/security/ApiKeyHasher.java`
- [Security properties](https://github.com/ramantiw45/api-rate-limiter/blob/main/src/main/java/com/api/ratelimiter/config/GatewaySecurityProperties.java): `src/main/java/com/api/ratelimiter/config/GatewaySecurityProperties.java`
- [Actuator access control](https://github.com/ramantiw45/api-rate-limiter/blob/main/src/main/java/com/api/ratelimiter/config/SecurityConfig.java): `src/main/java/com/api/ratelimiter/config/SecurityConfig.java`

### Operations and telemetry

- **Prometheus metrics**
- [Grafana dashboards](https://github.com/ramantiw45/api-rate-limiter/blob/main/docker/grafana/dashboards/rate-limiter-dashboard.json): `docker/grafana/dashboards/rate-limiter-dashboard.json`
- **Zipkin tracing**
- [Redis Sentinel HA](https://github.com/ramantiw45/api-rate-limiter/blob/main/docker-compose.ha.yml): `docker-compose.ha.yml`

### Other components

- **API client**
- **Echo upstream service**

## Connections

- API client → Reactive gateway: sends requests (evidence: `README.md`)
- Reactive gateway → Request tracing: enters filter
- Request tracing → API key filter: continues chain (evidence: `src/main/java/com/api/ratelimiter/filter/GlobalLoggingFilter.java`)
- API key filter → Key validator: validates key (evidence: `src/main/java/com/api/ratelimiter/filter/ApiKeyValidationFilter.java`)
- Key validator → Key hashing: hashes candidate (evidence: `src/main/java/com/api/ratelimiter/security/ApiKeyValidator.java`)
- Key validator → Security properties: loads digest settings (evidence: `src/main/java/com/api/ratelimiter/security/ApiKeyValidator.java`)
- API key filter → Key hashing: stores identity hash (evidence: `src/main/java/com/api/ratelimiter/filter/ApiKeyValidationFilter.java`)
- API key filter → Client key resolution: passes validated identity (evidence: `src/main/java/com/api/ratelimiter/config/KeyResolverConfig.java`)
- Client key resolution → Key hashing: hashes fallback key (evidence: `src/main/java/com/api/ratelimiter/config/KeyResolverConfig.java`)
- Client key resolution → Token bucket limiter: provides client key
- Token bucket limiter → Redis rate state: checks token bucket (evidence: `README.md`)
- Token bucket limiter → Rate-limit error handling: rejects exhausted bucket
- Token bucket limiter → Circuit breaker and timeout: permits requests onward (evidence: `README.md`)
- Circuit breaker and timeout → Breaker properties: loads breaker settings (evidence: `src/main/java/com/api/ratelimiter/config/ResilienceConfig.java`)
- Circuit breaker and timeout → Echo upstream service: proxies protected calls (evidence: `README.md`)
- Circuit breaker and timeout → 503 fallback: dispatches on failure (evidence: `src/main/java/com/api/ratelimiter/controller/FallbackController.java`)
- Actuator access control → Security properties: loads access settings (evidence: `src/main/java/com/api/ratelimiter/config/SecurityConfig.java`)
- Reactive gateway → Prometheus metrics: exposes metrics (evidence: `README.md`)
- Prometheus metrics → Grafana dashboards: feeds dashboards (evidence: `README.md`)
- Request tracing → Zipkin tracing: propagates trace context (evidence: `README.md`)
- Redis Sentinel HA → Redis rate state: manages failover (evidence: `README.md`)
