# harshsoni8780/distributed-rate-limiter-service architecture

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

- Interactive diagram: https://gitdiagram.com/harshsoni8780/distributed-rate-limiter-service
- Repository: https://github.com/harshsoni8780/distributed-rate-limiter-service

## Overview

This is a Go rate-limiting API service. A client request enters the Gin server, passes through token-bucket middleware, and is evaluated against per-client state in Redis; the middleware either rejects it with HTTP 429 and rate-limit headers or lets the route proceed. The README also describes policy-driven caching and PostgreSQL, plus fixed-window and sliding-window strategies, but the sampled code does not show those capabilities wired into the request path. The React dashboard is documented, but its source is not present in the supplied tree.

Main entry points: [`cmd/server/main.go`](https://github.com/harshsoni8780/distributed-rate-limiter-service/blob/main/cmd/server/main.go) (Gin API server), [`internal/middleware/ratelimit.go`](https://github.com/harshsoni8780/distributed-rate-limiter-service/blob/main/internal/middleware/ratelimit.go) (Token-bucket middleware), [`internal/limiter/token_bucket.go`](https://github.com/harshsoni8780/distributed-rate-limiter-service/blob/main/internal/limiter/token_bucket.go) (Token bucket), [`internal/store/redis.go`](https://github.com/harshsoni8780/distributed-rate-limiter-service/blob/main/internal/store/redis.go) (Redis client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_request["Request handling"]
  node_server["Gin API server<br/>[main.go]"]
  node_middleware["Token-bucket middleware<br/>[ratelimit.go]"]
  node_route["API route<br/>[main.go]"]
end

subgraph group_algorithms["Rate-limit algorithms"]
  node_bucket["Token bucket<br/>[token_bucket.go]"]
end

subgraph group_state["State and policy"]
  node_redis_client["Redis client<br/>[redis.go]"]
  node_redis[("Redis store")]
  node_policy["Rate-limit policy<br/>[policy.go]"]
  node_postgres[("PostgreSQL store<br/>[postgres.go]")]
end

subgraph group_alternatives["Alternative strategies"]
  node_fixed["Fixed window<br/>[fixed_window.go]"]
  node_sliding["Sliding window log<br/>[sliding_window.go]"]
end

node_client(("API client"))

node_client -->|"sends requests"| node_server
node_server -->|"creates client"| node_redis_client
node_server -->|"configures bucket"| node_bucket
node_server -->|"registers middleware"| node_middleware
node_middleware -->|"checks allowance"| node_bucket
node_bucket -->|"runs Lua script"| node_redis
node_redis_client -->|"configures connection"| node_redis
node_middleware -->|"continues allowed requests"| node_route
node_server -->|"serves API"| node_client
node_policy -.->|"invalidates cache"| node_redis_client
node_policy -.->|"loads policy data"| node_postgres

click node_server "https://github.com/harshsoni8780/distributed-rate-limiter-service/blob/main/cmd/server/main.go"
click node_middleware "https://github.com/harshsoni8780/distributed-rate-limiter-service/blob/main/internal/middleware/ratelimit.go"
click node_route "https://github.com/harshsoni8780/distributed-rate-limiter-service/blob/main/cmd/server/main.go"
click node_bucket "https://github.com/harshsoni8780/distributed-rate-limiter-service/blob/main/internal/limiter/token_bucket.go"
click node_redis_client "https://github.com/harshsoni8780/distributed-rate-limiter-service/blob/main/internal/store/redis.go"
click node_policy "https://github.com/harshsoni8780/distributed-rate-limiter-service/blob/main/internal/policy/policy.go"
click node_postgres "https://github.com/harshsoni8780/distributed-rate-limiter-service/blob/main/internal/store/postgres.go"
click node_fixed "https://github.com/harshsoni8780/distributed-rate-limiter-service/blob/main/internal/limiter/fixed_window.go"
click node_sliding "https://github.com/harshsoni8780/distributed-rate-limiter-service/blob/main/internal/limiter/sliding_window.go"

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_server,node_middleware,node_route,node_client toneBlue
class node_bucket toneAmber
class node_redis_client,node_redis,node_policy,node_postgres toneMint
class node_fixed,node_sliding toneRose
```

## Components

### Request handling

- [Gin API server](https://github.com/harshsoni8780/distributed-rate-limiter-service/blob/main/cmd/server/main.go): `cmd/server/main.go`
- [Token-bucket middleware](https://github.com/harshsoni8780/distributed-rate-limiter-service/blob/main/internal/middleware/ratelimit.go): `internal/middleware/ratelimit.go`
- [API route](https://github.com/harshsoni8780/distributed-rate-limiter-service/blob/main/cmd/server/main.go): `cmd/server/main.go`

### Rate-limit algorithms

- [Token bucket](https://github.com/harshsoni8780/distributed-rate-limiter-service/blob/main/internal/limiter/token_bucket.go): `internal/limiter/token_bucket.go`

### State and policy

- [Redis client](https://github.com/harshsoni8780/distributed-rate-limiter-service/blob/main/internal/store/redis.go): `internal/store/redis.go`
- **Redis store**
- [Rate-limit policy](https://github.com/harshsoni8780/distributed-rate-limiter-service/blob/main/internal/policy/policy.go): `internal/policy/policy.go`
- [PostgreSQL store](https://github.com/harshsoni8780/distributed-rate-limiter-service/blob/main/internal/store/postgres.go): `internal/store/postgres.go`

### Alternative strategies

- [Fixed window](https://github.com/harshsoni8780/distributed-rate-limiter-service/blob/main/internal/limiter/fixed_window.go): `internal/limiter/fixed_window.go`
- [Sliding window log](https://github.com/harshsoni8780/distributed-rate-limiter-service/blob/main/internal/limiter/sliding_window.go): `internal/limiter/sliding_window.go`

### Other components

- **API client**

## Connections

- API client → Gin API server: sends requests (evidence: `Readme.md`)
- Gin API server → Redis client: creates client (evidence: `cmd/server/main.go`)
- Gin API server → Token bucket: configures bucket (evidence: `cmd/server/main.go`)
- Gin API server → Token-bucket middleware: registers middleware (evidence: `cmd/server/main.go`)
- Token-bucket middleware → Token bucket: checks allowance (evidence: `internal/middleware/ratelimit.go`)
- Token bucket → Redis store: runs Lua script (evidence: `internal/limiter/token_bucket.go`)
- Redis client → Redis store: configures connection (evidence: `internal/store/redis.go`)
- Token-bucket middleware → API route: continues allowed requests (evidence: `internal/middleware/ratelimit.go`)
- Gin API server → API client: serves API (evidence: `Readme.md`)
- Rate-limit policy → Redis client: invalidates cache
- Rate-limit policy → PostgreSQL store: loads policy data
