# nandinideshmukh/rate-limiter architecture

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

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

## Overview

RateLimitX is an HTTP rate-limiting service. Requests to `/api/` are identified by API key or client IP, assigned a policy, checked by its configured Redis-backed algorithm, and either rejected with rate-limit headers or passed to the API handler. The service also serves an embedded page, health endpoints, and Prometheus metrics. The source excerpts show all five Redis-backed algorithms and some Lua scripts; other script and deployment wiring is not inspected, so those relationships are omitted.

Main entry points: [`cmd/server/main.go`](https://github.com/nandinideshmukh/rate-limiter/blob/main/cmd/server/main.go) (HTTP server), [`internal/middleware/ratelimit.go`](https://github.com/nandinideshmukh/rate-limiter/blob/main/internal/middleware/ratelimit.go) (Rate-limit middleware), [`internal/storage/fixed_window.go`](https://github.com/nandinideshmukh/rate-limiter/blob/main/internal/storage/fixed_window.go) (Redis fixed window), [`internal/storage/sliding_window_counter.go`](https://github.com/nandinideshmukh/rate-limiter/blob/main/internal/storage/sliding_window_counter.go) (Redis sliding counter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["HTTP service"]
  node_server["HTTP server<br/>[main.go]"]
  node_api["API handler<br/>[main.go]"]
  node_web["Embedded page<br/>[assets.go]"]
end

subgraph group_policy["Policy and enforcement"]
  node_policy_manager["Policy manager<br/>[manager.go]"]
  node_ratelimit_middleware["Rate-limit middleware<br/>[ratelimit.go]"]
end

subgraph group_algorithms["Limiter algorithms"]
  node_fixed_memory["Fixed window logic<br/>[fixed_window.go]"]
  node_sliding_counter_memory["Sliding counter logic"]
  node_sliding_log_memory["Sliding log logic"]
  node_token_memory["Token bucket logic<br/>[token_bucket.go]"]
  node_leaky_memory["Leaky bucket logic<br/>[leaky_bucket.go]"]
  node_fixed_redis["Redis fixed window<br/>[fixed_window.go]"]
  node_sliding_counter_redis["Redis sliding counter"]
  node_sliding_log_redis["Redis sliding log"]
  node_token_redis["Redis token bucket<br/>[token_bucket.go]"]
  node_leaky_redis["Redis leaky bucket<br/>[leaky_bucket.go]"]
end

subgraph group_operations["Metrics and health"]
  node_metrics["Request metrics<br/>[metrics.go]"]
  node_prometheus["Prometheus endpoint"]
end

node_client(("HTTP client"))
node_redis[("Redis")]
node_prometheus_service["Prometheus service"]
node_grafana_service["Grafana service"]

node_client -->|"sends requests"| node_server
node_server -->|"routes /api"| node_ratelimit_middleware
node_server -->|"serves page"| node_web
node_server -->|"serves metrics"| node_prometheus
node_server -->|"checks health"| node_prometheus_service
node_server -->|"checks health"| node_grafana_service
node_server -->|"configures policies"| node_policy_manager
node_server -->|"constructs backend"| node_fixed_redis
node_server -->|"constructs backend"| node_sliding_counter_redis
node_server -->|"constructs backend"| node_sliding_log_redis
node_server -->|"constructs backend"| node_token_redis
node_server -->|"constructs backend"| node_leaky_redis
node_ratelimit_middleware -->|"selects policy"| node_policy_manager
node_ratelimit_middleware -->|"checks limit"| node_fixed_redis
node_ratelimit_middleware -->|"checks limit"| node_sliding_counter_redis
node_ratelimit_middleware -->|"checks limit"| node_sliding_log_redis
node_ratelimit_middleware -->|"checks limit"| node_token_redis
node_ratelimit_middleware -->|"checks limit"| node_leaky_redis
node_ratelimit_middleware -->|"allows request"| node_api
node_ratelimit_middleware -->|"records outcomes"| node_metrics
node_prometheus -->|"exposes metrics"| node_metrics
node_fixed_redis -->|"runs script"| node_redis
node_sliding_counter_redis -->|"runs script"| node_redis
node_leaky_redis -->|"runs script"| node_redis

click node_server "https://github.com/nandinideshmukh/rate-limiter/blob/main/cmd/server/main.go"
click node_api "https://github.com/nandinideshmukh/rate-limiter/blob/main/cmd/server/main.go"
click node_web "https://github.com/nandinideshmukh/rate-limiter/blob/main/web/assets.go"
click node_policy_manager "https://github.com/nandinideshmukh/rate-limiter/blob/main/internal/policy/manager.go"
click node_ratelimit_middleware "https://github.com/nandinideshmukh/rate-limiter/blob/main/internal/middleware/ratelimit.go"
click node_fixed_memory "https://github.com/nandinideshmukh/rate-limiter/blob/main/internal/limiter/fixed_window.go"
click node_sliding_counter_memory "https://github.com/nandinideshmukh/rate-limiter/blob/main/internal/limiter/sliding_window_counter.go"
click node_sliding_log_memory "https://github.com/nandinideshmukh/rate-limiter/blob/main/internal/limiter/sliding_window_log.go"
click node_token_memory "https://github.com/nandinideshmukh/rate-limiter/blob/main/internal/limiter/token_bucket.go"
click node_leaky_memory "https://github.com/nandinideshmukh/rate-limiter/blob/main/internal/limiter/leaky_bucket.go"
click node_fixed_redis "https://github.com/nandinideshmukh/rate-limiter/blob/main/internal/storage/fixed_window.go"
click node_sliding_counter_redis "https://github.com/nandinideshmukh/rate-limiter/blob/main/internal/storage/sliding_window_counter.go"
click node_sliding_log_redis "https://github.com/nandinideshmukh/rate-limiter/blob/main/internal/storage/sliding_window_log.go"
click node_token_redis "https://github.com/nandinideshmukh/rate-limiter/blob/main/internal/storage/token_bucket.go"
click node_leaky_redis "https://github.com/nandinideshmukh/rate-limiter/blob/main/internal/storage/leaky_bucket.go"
click node_metrics "https://github.com/nandinideshmukh/rate-limiter/blob/main/internal/metrics/metrics.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_api,node_web,node_client toneBlue
class node_policy_manager,node_ratelimit_middleware,node_redis toneAmber
class node_fixed_memory,node_sliding_counter_memory,node_sliding_log_memory,node_token_memory,node_leaky_memory,node_fixed_redis,node_sliding_counter_redis,node_sliding_log_redis,node_token_redis,node_leaky_redis toneMint
class node_metrics,node_prometheus toneRose
class node_prometheus_service,node_grafana_service toneIndigo
```

## Components

### HTTP service

- [HTTP server](https://github.com/nandinideshmukh/rate-limiter/blob/main/cmd/server/main.go): `cmd/server/main.go`
- [API handler](https://github.com/nandinideshmukh/rate-limiter/blob/main/cmd/server/main.go): `cmd/server/main.go`
- [Embedded page](https://github.com/nandinideshmukh/rate-limiter/blob/main/web/assets.go): `web/assets.go`

### Policy and enforcement

- [Policy manager](https://github.com/nandinideshmukh/rate-limiter/blob/main/internal/policy/manager.go): `internal/policy/manager.go`
- [Rate-limit middleware](https://github.com/nandinideshmukh/rate-limiter/blob/main/internal/middleware/ratelimit.go): `internal/middleware/ratelimit.go`

### Limiter algorithms

- [Fixed window logic](https://github.com/nandinideshmukh/rate-limiter/blob/main/internal/limiter/fixed_window.go): `internal/limiter/fixed_window.go`
- [Sliding counter logic](https://github.com/nandinideshmukh/rate-limiter/blob/main/internal/limiter/sliding_window_counter.go): `internal/limiter/sliding_window_counter.go`
- [Sliding log logic](https://github.com/nandinideshmukh/rate-limiter/blob/main/internal/limiter/sliding_window_log.go): `internal/limiter/sliding_window_log.go`
- [Token bucket logic](https://github.com/nandinideshmukh/rate-limiter/blob/main/internal/limiter/token_bucket.go): `internal/limiter/token_bucket.go`
- [Leaky bucket logic](https://github.com/nandinideshmukh/rate-limiter/blob/main/internal/limiter/leaky_bucket.go): `internal/limiter/leaky_bucket.go`
- [Redis fixed window](https://github.com/nandinideshmukh/rate-limiter/blob/main/internal/storage/fixed_window.go): `internal/storage/fixed_window.go`
- [Redis sliding counter](https://github.com/nandinideshmukh/rate-limiter/blob/main/internal/storage/sliding_window_counter.go): `internal/storage/sliding_window_counter.go`
- [Redis sliding log](https://github.com/nandinideshmukh/rate-limiter/blob/main/internal/storage/sliding_window_log.go): `internal/storage/sliding_window_log.go`
- [Redis token bucket](https://github.com/nandinideshmukh/rate-limiter/blob/main/internal/storage/token_bucket.go): `internal/storage/token_bucket.go`
- [Redis leaky bucket](https://github.com/nandinideshmukh/rate-limiter/blob/main/internal/storage/leaky_bucket.go): `internal/storage/leaky_bucket.go`

### Metrics and health

- [Request metrics](https://github.com/nandinideshmukh/rate-limiter/blob/main/internal/metrics/metrics.go): `internal/metrics/metrics.go`
- **Prometheus endpoint**

### Other components

- **HTTP client**
- **Redis**
- **Prometheus service**
- **Grafana service**

## Connections

- HTTP client → HTTP server: sends requests (evidence: `cmd/server/main.go`)
- HTTP server → Rate-limit middleware: routes /api (evidence: `cmd/server/main.go`)
- HTTP server → Embedded page: serves page (evidence: `cmd/server/main.go`)
- HTTP server → Prometheus endpoint: serves metrics (evidence: `cmd/server/main.go`)
- HTTP server → Prometheus service: checks health (evidence: `cmd/server/main.go`)
- HTTP server → Grafana service: checks health (evidence: `cmd/server/main.go`)
- HTTP server → Policy manager: configures policies (evidence: `cmd/server/main.go`)
- HTTP server → Redis fixed window: constructs backend (evidence: `cmd/server/main.go`)
- HTTP server → Redis sliding counter: constructs backend (evidence: `cmd/server/main.go`)
- HTTP server → Redis sliding log: constructs backend (evidence: `cmd/server/main.go`)
- HTTP server → Redis token bucket: constructs backend (evidence: `cmd/server/main.go`)
- HTTP server → Redis leaky bucket: constructs backend (evidence: `cmd/server/main.go`)
- Rate-limit middleware → Policy manager: selects policy (evidence: `internal/middleware/ratelimit.go`)
- Rate-limit middleware → Redis fixed window: checks limit (evidence: `internal/middleware/ratelimit.go`)
- Rate-limit middleware → Redis sliding counter: checks limit (evidence: `internal/middleware/ratelimit.go`)
- Rate-limit middleware → Redis sliding log: checks limit (evidence: `internal/middleware/ratelimit.go`)
- Rate-limit middleware → Redis token bucket: checks limit (evidence: `internal/middleware/ratelimit.go`)
- Rate-limit middleware → Redis leaky bucket: checks limit (evidence: `internal/middleware/ratelimit.go`)
- Rate-limit middleware → API handler: allows request (evidence: `internal/middleware/ratelimit.go`)
- Rate-limit middleware → Request metrics: records outcomes (evidence: `internal/middleware/ratelimit.go`)
- Prometheus endpoint → Request metrics: exposes metrics
- Redis fixed window → Redis: runs script (evidence: `internal/storage/fixed_window.go`)
- Redis sliding counter → Redis: runs script (evidence: `internal/storage/sliding_window_counter.go`)
- Redis leaky bucket → Redis: runs script (evidence: `internal/storage/leaky_bucket.go`)