# poojanpanchal/distributed-rate-limiter-in-java architecture

> Architecture diagram of the GitHub repository poojanpanchal/distributed-rate-limiter-in-java, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/poojanpanchal/distributed-rate-limiter-in-java
- Repository: https://github.com/poojanpanchal/distributed-rate-limiter-in-java

## Overview

##### Project type and purpose
- This is an open-source, distributed rate-limiting library in Java.
- It implements the Token Bucket algorithm using Redis as the authoritative store of bucket state.
- Intended for integration into any Java service to enforce per-client or per-service rate limits across a cluster.

##### File structure
- Single Gradle subproject under `app/`.
- `src/main/java/org/example/TokenBucketRateLimiter.java` – core class.
- `src/test/java/org/example/TokenBucketRateLimiterIntegrationTest.java` – integration tests using TestContainers + Docker.
- Gradle wrappers and TOML versions under `gradle/`.
- Helper script `run-tests.sh` for Unix environments.

##### README for additional insights
- Key features: distributed, accurate, efficient, flexible, thread-safe.
- Uses Redis transactions for atomic access.
- Tests spin up a Redis container via TestContainers to validate behavior end-to-end.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        ClientApp["Client Application"]:::external
    end

    %% Load Balancer
    LoadBalancer["Load Balancer"]:::external

    %% Service Layer
    subgraph "Service Layer"
        direction TB
        subgraph "Java Service Instances"
            direction TB
            Service1["Java Service Instance"]:::service
            Service2["Java Service Instance"]:::service
            Service3["Java Service Instance"]:::service
        end
    end

    %% Token Bucket Rate Limiter Component
    subgraph "Rate Limiter Module"
        direction TB
        RateLimiter["TokenBucketRateLimiter"]:::service
        JedisPool["JedisPool (optional)"]:::service
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Redis["Redis Server"]:::store
    end

    %% Test Infrastructure
    subgraph "Test Infrastructure"
        direction TB
        TestInfra["Docker/TestContainers"]:::infra
    end

    %% Relationships
    ClientApp -->|"isAllowed(clientId)"| LoadBalancer
    LoadBalancer -->|"forwards request"| Service1
    LoadBalancer -->|"forwards request"| Service2
    LoadBalancer -->|"forwards request"| Service3

    Service1 -->|"calls isAllowed()"| RateLimiter
    Service2 -->|"calls isAllowed()"| RateLimiter
    Service3 -->|"calls isAllowed()"| RateLimiter

    RateLimiter -->|"MULTI/EXEC, GET, SET"| JedisPool
    JedisPool -->|"connection"| Redis
    RateLimiter -->|"direct Jedis"| Redis

    Redis -->|"token count, timestamp"| RateLimiter
    RateLimiter -->|"allowed/denied"| Service1
    RateLimiter -->|"allowed/denied"| Service2
    RateLimiter -->|"allowed/denied"| Service3

    TestInfra -->|"spins up Redis"| Redis
    TestInfra -->|"runs integration tests"| RateLimiter

    %% Click Events
    click RateLimiter "https://github.com/poojanpanchal/distributed-rate-limiter-in-java/blob/main/app/src/main/java/org/example/TokenBucketRateLimiter.java"
    click TestInfra "https://github.com/poojanpanchal/distributed-rate-limiter-in-java/blob/main/app/src/test/java/org/example/TokenBucketRateLimiterIntegrationTest.java"
    click BuildScript "https://github.com/poojanpanchal/distributed-rate-limiter-in-java/blob/main/app/build.gradle.kts"
    click VersionsCatalog "https://github.com/poojanpanchal/distributed-rate-limiter-in-java/blob/main/gradle/libs.versions.toml"
    click GradleProps "https://github.com/poojanpanchal/distributed-rate-limiter-in-java/blob/main/gradle.properties"
    click Settings "https://github.com/poojanpanchal/distributed-rate-limiter-in-java/blob/main/settings.gradle.kts"
    click GradleWrapperJar "https://github.com/poojanpanchal/distributed-rate-limiter-in-java/blob/main/gradle/wrapper/gradle-wrapper.jar"
    click GradleWrapperProps "https://github.com/poojanpanchal/distributed-rate-limiter-in-java/blob/main/gradle/wrapper/gradle-wrapper.properties"
    click RunTests "https://github.com/poojanpanchal/distributed-rate-limiter-in-java/blob/main/run-tests.sh"

    %% Alias for click mapping nodes
    BuildScript["Gradle Build Script"]:::service
    VersionsCatalog["Dependency Versions Catalog"]:::infra
    GradleProps["Gradle Properties"]:::infra
    Settings["Settings (multi-module)"]:::infra
    GradleWrapperJar["Gradle Wrapper JAR"]:::infra
    GradleWrapperProps["Gradle Wrapper Properties"]:::infra
    RunTests["run-tests.sh"]:::infra

    %% Styles
    classDef service fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef store fill:#90EE90,stroke:#000,stroke-width:1px
    classDef external fill:#FFA500,stroke:#000,stroke-width:1px
    classDef infra fill:#D3D3D3,stroke:#000,stroke-width:1px
```
