# rupayan-san/request-guard architecture

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

- Interactive diagram: https://gitdiagram.com/rupayan-san/request-guard
- Repository: https://github.com/rupayan-san/request-guard

## Overview

Request Guard is a Node.js library for Redis-backed rate limiting and semantic caching. The primary workflows are selecting a limiter strategy and checking each user request, or embedding a query, searching cached vectors, and returning a hit or generating and storing an LLM response on a miss. Source confirms the rate-limit algorithms’ Redis calls and the semantic cache’s provider and Redis calls; the README documents the capabilities and provider contracts. The semantic cache method name in the sampled source differs from the README’s API name.

Main entry points: [`src/semantic_cache/services/semantic_cache.service.ts`](https://github.com/rupayan-san/request-guard/blob/main/src/semantic_cache/services/semantic_cache.service.ts) (Semantic Cache Service), [`src/rate_limiter/rateLimiter.factory.ts`](https://github.com/rupayan-san/request-guard/blob/main/src/rate_limiter/rateLimiter.factory.ts) (Limiter Factory), [`src/rate_limiter/algorithms/tokenBucket.algo.ts`](https://github.com/rupayan-san/request-guard/blob/main/src/rate_limiter/algorithms/tokenBucket.algo.ts) (Token Bucket), [`src/rate_limiter/algorithms/leakyBucket.algo.ts`](https://github.com/rupayan-san/request-guard/blob/main/src/rate_limiter/algorithms/leakyBucket.algo.ts) (Leaky Bucket)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_rate["Rate Limiting"]
  node_factory["Limiter Factory"]
  node_limiter_contract["Limiter Contract"]
  node_token["Token Bucket"]
  node_leaky["Leaky Bucket"]
  node_window["Sliding Window"]
end

subgraph group_semantic["Semantic Cache"]
  node_semantic_service["Semantic Cache Service"]
  node_vector_utils["Vector Encoding<br/>[vector.utils.ts]"]
  node_similarity_utils["Similarity Utility"]
  node_cache_config["Cache Threshold"]
end

subgraph group_providers["Provider Contracts"]
  node_embedding_contract["Embedding Contract"]
  node_llm_contract["LLM Contract<br/>[llm.interface.ts]"]
end

subgraph group_entry["Library API"]
  node_api["Package Exports<br/>[index.ts]"]
end

node_caller(("Node.js Application"))
node_embedding_provider["Embedding Provider"]
node_llm_provider["LLM Provider"]
node_redis[("Redis")]

node_caller -->|"imports"| node_api
node_caller -->|"creates limiter"| node_factory
node_factory -->|"instantiates"| node_token
node_factory -->|"instantiates"| node_leaky
node_factory -->|"instantiates"| node_window
node_token -->|"evaluates script"| node_redis
node_leaky -->|"evaluates script"| node_redis
node_window -->|"evaluates script"| node_redis
node_caller -->|"uses cache"| node_semantic_service
node_semantic_service -->|"generates embedding"| node_embedding_provider
node_semantic_service -->|"generates response"| node_llm_provider
node_semantic_service -->|"searches and stores"| node_redis
node_semantic_service -->|"encodes vectors"| node_vector_utils
node_semantic_service -->|"uses default"| node_cache_config
node_semantic_service -->|"uses contract"| node_embedding_contract
node_semantic_service -->|"uses contract"| node_llm_contract
node_token -->|"implements"| node_limiter_contract
node_leaky -->|"implements"| node_limiter_contract
node_window -->|"implements"| node_limiter_contract

click node_api "https://github.com/rupayan-san/request-guard/blob/main/src/index.ts"
click node_factory "https://github.com/rupayan-san/request-guard/blob/main/src/rate_limiter/rateLimiter.factory.ts"
click node_limiter_contract "https://github.com/rupayan-san/request-guard/blob/main/src/rate_limiter/rateLimiter.interface.ts"
click node_token "https://github.com/rupayan-san/request-guard/blob/main/src/rate_limiter/algorithms/tokenBucket.algo.ts"
click node_leaky "https://github.com/rupayan-san/request-guard/blob/main/src/rate_limiter/algorithms/leakyBucket.algo.ts"
click node_window "https://github.com/rupayan-san/request-guard/blob/main/src/rate_limiter/algorithms/slidingWindow.algo.ts"
click node_semantic_service "https://github.com/rupayan-san/request-guard/blob/main/src/semantic_cache/services/semantic_cache.service.ts"
click node_vector_utils "https://github.com/rupayan-san/request-guard/blob/main/src/semantic_cache/utils/vector.utils.ts"
click node_similarity_utils "https://github.com/rupayan-san/request-guard/blob/main/src/semantic_cache/utils/similarity.utils.ts"
click node_cache_config "https://github.com/rupayan-san/request-guard/blob/main/src/semantic_cache/config/semantic_cache.config.ts"
click node_embedding_contract "https://github.com/rupayan-san/request-guard/blob/main/src/interfaces/embedding.interface.ts"
click node_llm_contract "https://github.com/rupayan-san/request-guard/blob/main/src/interfaces/llm.interface.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_factory,node_limiter_contract,node_token,node_leaky,node_window toneBlue
class node_semantic_service,node_vector_utils,node_similarity_utils,node_cache_config,node_redis toneAmber
class node_embedding_contract,node_llm_contract toneMint
class node_api toneRose
class node_caller,node_embedding_provider,node_llm_provider toneIndigo
```

## Components

### Rate Limiting

- [Limiter Factory](https://github.com/rupayan-san/request-guard/blob/main/src/rate_limiter/rateLimiter.factory.ts): `src/rate_limiter/rateLimiter.factory.ts`
- [Limiter Contract](https://github.com/rupayan-san/request-guard/blob/main/src/rate_limiter/rateLimiter.interface.ts): `src/rate_limiter/rateLimiter.interface.ts`
- [Token Bucket](https://github.com/rupayan-san/request-guard/blob/main/src/rate_limiter/algorithms/tokenBucket.algo.ts): `src/rate_limiter/algorithms/tokenBucket.algo.ts`
- [Leaky Bucket](https://github.com/rupayan-san/request-guard/blob/main/src/rate_limiter/algorithms/leakyBucket.algo.ts): `src/rate_limiter/algorithms/leakyBucket.algo.ts`
- [Sliding Window](https://github.com/rupayan-san/request-guard/blob/main/src/rate_limiter/algorithms/slidingWindow.algo.ts): `src/rate_limiter/algorithms/slidingWindow.algo.ts`

### Semantic Cache

- [Semantic Cache Service](https://github.com/rupayan-san/request-guard/blob/main/src/semantic_cache/services/semantic_cache.service.ts): `src/semantic_cache/services/semantic_cache.service.ts`
- [Vector Encoding](https://github.com/rupayan-san/request-guard/blob/main/src/semantic_cache/utils/vector.utils.ts): `src/semantic_cache/utils/vector.utils.ts`
- [Similarity Utility](https://github.com/rupayan-san/request-guard/blob/main/src/semantic_cache/utils/similarity.utils.ts): `src/semantic_cache/utils/similarity.utils.ts`
- [Cache Threshold](https://github.com/rupayan-san/request-guard/blob/main/src/semantic_cache/config/semantic_cache.config.ts): `src/semantic_cache/config/semantic_cache.config.ts`

### Provider Contracts

- [Embedding Contract](https://github.com/rupayan-san/request-guard/blob/main/src/interfaces/embedding.interface.ts): `src/interfaces/embedding.interface.ts`
- [LLM Contract](https://github.com/rupayan-san/request-guard/blob/main/src/interfaces/llm.interface.ts): `src/interfaces/llm.interface.ts`

### Library API

- [Package Exports](https://github.com/rupayan-san/request-guard/blob/main/src/index.ts): `src/index.ts`

### Other components

- **Node.js Application**
- **Embedding Provider**
- **LLM Provider**
- **Redis**

## Connections

- Node.js Application → Package Exports: imports
- Node.js Application → Limiter Factory: creates limiter
- Limiter Factory → Token Bucket: instantiates
- Limiter Factory → Leaky Bucket: instantiates
- Limiter Factory → Sliding Window: instantiates
- Token Bucket → Redis: evaluates script
- Leaky Bucket → Redis: evaluates script
- Sliding Window → Redis: evaluates script
- Node.js Application → Semantic Cache Service: uses cache
- Semantic Cache Service → Embedding Provider: generates embedding
- Semantic Cache Service → LLM Provider: generates response
- Semantic Cache Service → Redis: searches and stores
- Semantic Cache Service → Vector Encoding: encodes vectors
- Semantic Cache Service → Cache Threshold: uses default
- Semantic Cache Service → Embedding Contract: uses contract
- Semantic Cache Service → LLM Contract: uses contract
- Token Bucket → Limiter Contract: implements
- Leaky Bucket → Limiter Contract: implements
- Sliding Window → Limiter Contract: implements