# jacktubby/rate-guard architecture

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

- Interactive diagram: https://gitdiagram.com/jacktubby/rate-guard
- Repository: https://github.com/jacktubby/rate-guard

## Overview

Rate Guard is Express middleware that resolves a request key, checks it with a configured rate-limit algorithm and store, then either calls Express’s next handler or returns a 429 response with rate-limit headers. The factory selects Token Bucket or Fixed Window and memory or Redis storage; the store adapter supplies shared state operations. Redis is an optional external backend. The cleanup class exists in the tree but is not wired into the documented middleware workflow. Edges reflect the shown calls and README-described behavior; unsampled integrations are not inferred.

Main entry points: [`src/index.ts`](https://github.com/jacktubby/rate-guard/blob/main/src/index.ts) (Rate Guard Middleware), [`src/limiter.ts`](https://github.com/jacktubby/rate-guard/blob/main/src/limiter.ts) (Limiter Factory), [`src/store/rate-limit-store.ts`](https://github.com/jacktubby/rate-guard/blob/main/src/store/rate-limit-store.ts) (Store Adapter), [`src/limiters/bucket.ts`](https://github.com/jacktubby/rate-guard/blob/main/src/limiters/bucket.ts) (Token Bucket)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_middleware["Middleware"]
  node_middleware["Rate Guard Middleware<br/>[index.ts]"]
  node_key["Request Key Resolver<br/>[entry-helpers.ts]"]
  node_errors["Error Types<br/>[errors.ts]"]
end

subgraph group_limits["Limit Algorithms"]
  node_factory["Limiter Factory<br/>[limiter.ts]"]
  node_bucket["Token Bucket<br/>[bucket.ts]"]
  node_fixed["Fixed Window<br/>[fixed-window.ts]"]
end

subgraph group_storage["State Storage"]
  node_storeapi["Store Adapter"]
  node_memory[("Memory Store<br/>[memory.ts]")]
  node_redisstore["Redis Store<br/>[redis.ts]"]
end

node_express(("Express Request"))
node_redis[("Redis Service")]
node_response["Next Handler or 429"]

node_express -->|"invokes"| node_middleware
node_middleware -->|"resolves key"| node_key
node_key -->|"throws"| node_errors
node_middleware -->|"throws validation error"| node_errors
node_middleware -->|"creates limiter"| node_factory
node_factory -->|"constructs"| node_memory
node_factory -->|"constructs"| node_redisstore
node_factory -->|"selects"| node_bucket
node_factory -->|"selects"| node_fixed
node_factory -->|"wraps store"| node_storeapi
node_middleware -->|"checks limit"| node_bucket
node_middleware -->|"checks limit"| node_fixed
node_bucket -->|"reads and saves"| node_storeapi
node_fixed -->|"reads and saves"| node_storeapi
node_storeapi -->|"delegates state"| node_memory
node_storeapi -->|"delegates state"| node_redisstore
node_redisstore -->|"gets and sets"| node_redis
node_middleware -->|"continues or responds"| node_response

click node_middleware "https://github.com/jacktubby/rate-guard/blob/main/src/index.ts"
click node_key "https://github.com/jacktubby/rate-guard/blob/main/src/helpers/entry-helpers.ts"
click node_errors "https://github.com/jacktubby/rate-guard/blob/main/src/errors/errors.ts"
click node_factory "https://github.com/jacktubby/rate-guard/blob/main/src/limiter.ts"
click node_bucket "https://github.com/jacktubby/rate-guard/blob/main/src/limiters/bucket.ts"
click node_fixed "https://github.com/jacktubby/rate-guard/blob/main/src/limiters/fixed-window.ts"
click node_storeapi "https://github.com/jacktubby/rate-guard/blob/main/src/store/rate-limit-store.ts"
click node_memory "https://github.com/jacktubby/rate-guard/blob/main/src/store/memory.ts"
click node_redisstore "https://github.com/jacktubby/rate-guard/blob/main/src/store/redis.ts"

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_middleware,node_key,node_errors toneBlue
class node_factory,node_bucket,node_fixed,node_redis toneAmber
class node_storeapi,node_memory,node_redisstore,node_express,node_response toneMint
```

## Components

### Middleware

- [Rate Guard Middleware](https://github.com/jacktubby/rate-guard/blob/main/src/index.ts): `src/index.ts`
- [Request Key Resolver](https://github.com/jacktubby/rate-guard/blob/main/src/helpers/entry-helpers.ts): `src/helpers/entry-helpers.ts`
- [Error Types](https://github.com/jacktubby/rate-guard/blob/main/src/errors/errors.ts): `src/errors/errors.ts`

### Limit Algorithms

- [Limiter Factory](https://github.com/jacktubby/rate-guard/blob/main/src/limiter.ts): `src/limiter.ts`
- [Token Bucket](https://github.com/jacktubby/rate-guard/blob/main/src/limiters/bucket.ts): `src/limiters/bucket.ts`
- [Fixed Window](https://github.com/jacktubby/rate-guard/blob/main/src/limiters/fixed-window.ts): `src/limiters/fixed-window.ts`

### State Storage

- [Store Adapter](https://github.com/jacktubby/rate-guard/blob/main/src/store/rate-limit-store.ts): `src/store/rate-limit-store.ts`
- [Memory Store](https://github.com/jacktubby/rate-guard/blob/main/src/store/memory.ts): `src/store/memory.ts`
- [Redis Store](https://github.com/jacktubby/rate-guard/blob/main/src/store/redis.ts): `src/store/redis.ts`

### Other components

- **Express Request**
- **Redis Service**
- **Next Handler or 429**

## Connections

- Express Request → Rate Guard Middleware: invokes (evidence: `README.md`)
- Rate Guard Middleware → Request Key Resolver: resolves key (evidence: `src/index.ts`)
- Request Key Resolver → Error Types: throws (evidence: `src/helpers/entry-helpers.ts`)
- Rate Guard Middleware → Error Types: throws validation error (evidence: `src/index.ts`)
- Rate Guard Middleware → Limiter Factory: creates limiter (evidence: `src/index.ts`)
- Limiter Factory → Memory Store: constructs (evidence: `src/limiter.ts`)
- Limiter Factory → Redis Store: constructs (evidence: `src/limiter.ts`)
- Limiter Factory → Token Bucket: selects (evidence: `src/limiter.ts`)
- Limiter Factory → Fixed Window: selects (evidence: `src/limiter.ts`)
- Limiter Factory → Store Adapter: wraps store (evidence: `src/limiter.ts`)
- Rate Guard Middleware → Token Bucket: checks limit (evidence: `src/index.ts`)
- Rate Guard Middleware → Fixed Window: checks limit (evidence: `src/index.ts`)
- Token Bucket → Store Adapter: reads and saves (evidence: `src/limiters/bucket.ts`)
- Fixed Window → Store Adapter: reads and saves (evidence: `src/limiters/fixed-window.ts`)
- Store Adapter → Memory Store: delegates state (evidence: `src/store/rate-limit-store.ts`)
- Store Adapter → Redis Store: delegates state (evidence: `src/store/rate-limit-store.ts`)
- Redis Store → Redis Service: gets and sets (evidence: `src/store/redis.ts`)
- Rate Guard Middleware → Next Handler or 429: continues or responds (evidence: `src/index.ts`)
