# aknexad/limiter-rs architecture

> Architecture diagram of the GitHub repository aknexad/limiter-rs, 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/aknexad/limiter-rs
- Repository: https://github.com/aknexad/limiter-rs

## Overview

limiter-rs is a Rust rate-limiting library whose principal workflow is to turn a service and caller identity into a storage key, check that key’s token-bucket state, allow or deny the requested token consumption, and persist updated state when allowed. The API supports synchronous in-memory and asynchronous Redis-backed checks. The graph includes the documented configuration capability and the storage abstraction as an internal layer. Some storage and configuration relationships are documented rather than demonstrated by sampled runtime calls, so unsupported links are omitted.

Main entry points: [`crates/limiter_core/src/limiter_helper.rs`](https://github.com/aknexad/limiter-rs/blob/main/crates/limiter_core/src/limiter_helper.rs) (Request handling), [`crates/limiter_core/src/limiter.rs`](https://github.com/aknexad/limiter-rs/blob/main/crates/limiter_core/src/limiter.rs) (Rate limiter API), [`crates/limiter_storage/src/store.rs`](https://github.com/aknexad/limiter-rs/blob/main/crates/limiter_storage/src/store.rs) (Storage interfaces), [`crates/limiter_core/src/models/key.rs`](https://github.com/aknexad/limiter-rs/blob/main/crates/limiter_core/src/models/key.rs) (Key generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Request API"]
  node_rate_limiter["Rate limiter API<br/>[limiter.rs]"]
  node_request_helper["Request handling<br/>[limiter_helper.rs]"]
  node_check_input["Check input<br/>[types.rs]"]
end

subgraph group_domain["Limiter Domain"]
  node_key["Key generation<br/>[key.rs]"]
  node_token_bucket["Token bucket<br/>[token_bucket.rs]"]
  node_bucket_state["Bucket state<br/>[bucket_state.rs]"]
  node_time["Time utilities<br/>[time.rs]"]
end

subgraph group_storage["Storage Layer"]
  node_storage_traits["Storage interfaces<br/>[store.rs]"]
  node_memory_store[("Memory store<br/>[memory_store.rs]")]
  node_redis_storage[("Redis storage<br/>[redis_storage.rs]")]
end

subgraph group_config["Configuration"]
  node_policy["Policy configuration<br/>[policy.rs]"]
end

node_caller(("Library caller"))
node_redis_service[("Redis server")]

node_caller -->|"builds key"| node_key
node_caller -->|"checks rate"| node_rate_limiter
node_key -->|"provides key"| node_rate_limiter
node_rate_limiter -->|"dispatches check"| node_request_helper
node_rate_limiter -->|"reads bucket"| node_storage_traits
node_request_helper -->|"calculates tokens"| node_token_bucket
node_request_helper -->|"writes state"| node_storage_traits
node_request_helper -->|"timestamps state"| node_time
node_request_helper -->|"updates state"| node_bucket_state
node_rate_limiter -->|"builds input"| node_check_input
node_token_bucket -->|"gets timestamp"| node_time
node_storage_traits -->|"implements interface"| node_memory_store
node_storage_traits -->|"implements interface"| node_redis_storage
node_storage_traits -->|"sends commands"| node_redis_service
node_redis_storage -->|"opens connection"| node_redis_service

click node_key "https://github.com/aknexad/limiter-rs/blob/main/crates/limiter_core/src/models/key.rs"
click node_rate_limiter "https://github.com/aknexad/limiter-rs/blob/main/crates/limiter_core/src/limiter.rs"
click node_request_helper "https://github.com/aknexad/limiter-rs/blob/main/crates/limiter_core/src/limiter_helper.rs"
click node_token_bucket "https://github.com/aknexad/limiter-rs/blob/main/crates/limiter_core/src/algorithms/token_bucket.rs"
click node_bucket_state "https://github.com/aknexad/limiter-rs/blob/main/crates/limiter_core/src/models/bucket_state.rs"
click node_time "https://github.com/aknexad/limiter-rs/blob/main/crates/limiter_core/src/utils/time.rs"
click node_check_input "https://github.com/aknexad/limiter-rs/blob/main/crates/limiter_core/src/types.rs"
click node_storage_traits "https://github.com/aknexad/limiter-rs/blob/main/crates/limiter_storage/src/store.rs"
click node_memory_store "https://github.com/aknexad/limiter-rs/blob/main/crates/limiter_storage/src/memory/memory_store.rs"
click node_redis_storage "https://github.com/aknexad/limiter-rs/blob/main/crates/limiter_storage/src/redis/redis_storage.rs"
click node_policy "https://github.com/aknexad/limiter-rs/blob/main/crates/limiter_core/src/policy.rs"

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_rate_limiter,node_request_helper,node_check_input toneBlue
class node_key,node_token_bucket,node_bucket_state,node_time,node_redis_service toneAmber
class node_storage_traits,node_memory_store,node_redis_storage toneMint
class node_policy toneRose
class node_caller toneIndigo
```

## Components

### Request API

- [Rate limiter API](https://github.com/aknexad/limiter-rs/blob/main/crates/limiter_core/src/limiter.rs): `crates/limiter_core/src/limiter.rs`
- [Request handling](https://github.com/aknexad/limiter-rs/blob/main/crates/limiter_core/src/limiter_helper.rs): `crates/limiter_core/src/limiter_helper.rs`
- [Check input](https://github.com/aknexad/limiter-rs/blob/main/crates/limiter_core/src/types.rs): `crates/limiter_core/src/types.rs`

### Limiter Domain

- [Key generation](https://github.com/aknexad/limiter-rs/blob/main/crates/limiter_core/src/models/key.rs): `crates/limiter_core/src/models/key.rs`
- [Token bucket](https://github.com/aknexad/limiter-rs/blob/main/crates/limiter_core/src/algorithms/token_bucket.rs): `crates/limiter_core/src/algorithms/token_bucket.rs`
- [Bucket state](https://github.com/aknexad/limiter-rs/blob/main/crates/limiter_core/src/models/bucket_state.rs): `crates/limiter_core/src/models/bucket_state.rs`
- [Time utilities](https://github.com/aknexad/limiter-rs/blob/main/crates/limiter_core/src/utils/time.rs): `crates/limiter_core/src/utils/time.rs`

### Storage Layer

- [Storage interfaces](https://github.com/aknexad/limiter-rs/blob/main/crates/limiter_storage/src/store.rs): `crates/limiter_storage/src/store.rs`
- [Memory store](https://github.com/aknexad/limiter-rs/blob/main/crates/limiter_storage/src/memory/memory_store.rs): `crates/limiter_storage/src/memory/memory_store.rs`
- [Redis storage](https://github.com/aknexad/limiter-rs/blob/main/crates/limiter_storage/src/redis/redis_storage.rs): `crates/limiter_storage/src/redis/redis_storage.rs`

### Configuration

- [Policy configuration](https://github.com/aknexad/limiter-rs/blob/main/crates/limiter_core/src/policy.rs): `crates/limiter_core/src/policy.rs`

### Other components

- **Library caller**
- **Redis server**

## Connections

- Library caller → Key generation: builds key (evidence: `README.md`)
- Library caller → Rate limiter API: checks rate (evidence: `README.md`)
- Key generation → Rate limiter API: provides key (evidence: `README.md`)
- Rate limiter API → Request handling: dispatches check (evidence: `crates/limiter_core/src/limiter.rs`)
- Rate limiter API → Storage interfaces: reads bucket (evidence: `crates/limiter_core/src/limiter.rs`)
- Request handling → Token bucket: calculates tokens (evidence: `crates/limiter_core/src/limiter_helper.rs`)
- Request handling → Storage interfaces: writes state (evidence: `crates/limiter_core/src/limiter_helper.rs`)
- Request handling → Time utilities: timestamps state (evidence: `crates/limiter_core/src/limiter_helper.rs`)
- Request handling → Bucket state: updates state (evidence: `crates/limiter_core/src/limiter_helper.rs`)
- Rate limiter API → Check input: builds input (evidence: `crates/limiter_core/src/limiter.rs`)
- Token bucket → Time utilities: gets timestamp (evidence: `crates/limiter_core/src/algorithms/token_bucket.rs`)
- Storage interfaces → Memory store: implements interface (evidence: `crates/limiter_storage/src/store.rs`)
- Storage interfaces → Redis storage: implements interface (evidence: `crates/limiter_storage/src/store.rs`)
- Storage interfaces → Redis server: sends commands (evidence: `crates/limiter_storage/src/store.rs`)
- Redis storage → Redis server: opens connection (evidence: `crates/limiter_storage/src/redis/redis_storage.rs`)
