# silent-watcher/nestjs-quota architecture

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

- Interactive diagram: https://gitdiagram.com/silent-watcher/nestjs-quota
- Repository: https://github.com/silent-watcher/nestjs-quota

## Overview

nestjs-quota is a framework-independent quota and usage-metering engine with an optional NestJS adapter and memory/Redis stores. Its main request path is a NestJS route with quota metadata: the guard resolves policy applications and identities, asks the engine to check, consume, or reserve quota, and returns statuses or an HTTP rejection. The core also supports direct service operations, post-handler metering, usage inspection, idempotent retries, and reservation reconciliation. Relationships reflect the provided excerpts, source-index references, and README; some adapter and interceptor details were not excerpted.

Main entry points: [`src/core/application/engine.ts`](https://github.com/silent-watcher/nestjs-quota/blob/master/src/core/application/engine.ts) (Quota engine), [`src/nestjs/guards/quota.guard.ts`](https://github.com/silent-watcher/nestjs-quota/blob/master/src/nestjs/guards/quota.guard.ts) (Quota guard), [`src/core/contracts/store.ts`](https://github.com/silent-watcher/nestjs-quota/blob/master/src/core/contracts/store.ts) (Store contract), [`src/nestjs/module/quota.service.ts`](https://github.com/silent-watcher/nestjs-quota/blob/master/src/nestjs/module/quota.service.ts) (Quota service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Quota core"]
  node_engine["Quota engine<br/>[engine.ts]"]
  node_storecontract["Store contract<br/>[store.ts]"]
  node_result["Quota decision and status<br/>[types.ts]"]
end

subgraph group_nest["NestJS adapter"]
  node_guard["Quota guard<br/>[quota.guard.ts]"]
  node_decorator["Route metadata<br/>[quota.decorator.ts]"]
  node_context["Identity resolvers<br/>[quota-context.ts]"]
  node_request["Request state and headers<br/>[request-marker.ts]"]
  node_module["Module configuration"]
  node_service["Quota service<br/>[quota.service.ts]"]
  node_meter["Post-handler metering"]
end

subgraph group_stores["Storage adapters"]
  node_memory[("Memory store<br/>[memory-store.ts]")]
  node_redis[("Redis store<br/>[redis-store.ts]")]
  node_lua["Redis atomic scripts<br/>[lua-scripts.ts]"]
end

subgraph group_support["Core support"]
  node_policy["Policy resolution<br/>[policy.ts]"]
  node_window["Quota windows<br/>[window.ts]"]
  node_identity["Identity validation<br/>[identity.ts]"]
  node_key["Storage keys<br/>[key.ts]"]
  node_clock["Clock<br/>[clock.ts]"]
end

node_caller(("API caller"))
node_route["NestJS route"]

node_caller -->|"calls API"| node_route
node_route -->|"enters guard"| node_guard
node_decorator -->|"provides metadata"| node_guard
node_guard -->|"resolves identity"| node_context
node_guard -->|"reads options"| node_module
node_guard -->|"checks or consumes"| node_engine
node_guard -->|"stores request state"| node_request
node_guard -->|"uses statuses"| node_result
node_module -->|"configures engine"| node_engine
node_service -->|"delegates operations"| node_engine
node_meter -->|"records usage"| node_engine
node_engine -->|"resolves policies"| node_policy
node_engine -->|"resolves windows"| node_window
node_engine -->|"validates subjects"| node_identity
node_engine -->|"reads time"| node_clock
node_engine -->|"dispatches bucket operations"| node_storecontract
node_storecontract -->|"implemented by"| node_memory
node_storecontract -->|"implemented by"| node_redis
node_redis -->|"executes scripts"| node_lua
node_engine -->|"returns decisions"| node_result
node_engine -->|"uses key helpers"| node_key
node_service -->|"exposes usage and reservations"| node_caller

click node_guard "https://github.com/silent-watcher/nestjs-quota/blob/master/src/nestjs/guards/quota.guard.ts"
click node_decorator "https://github.com/silent-watcher/nestjs-quota/blob/master/src/nestjs/decorators/quota.decorator.ts"
click node_context "https://github.com/silent-watcher/nestjs-quota/blob/master/src/nestjs/context/quota-context.ts"
click node_request "https://github.com/silent-watcher/nestjs-quota/blob/master/src/nestjs/context/request-marker.ts"
click node_module "https://github.com/silent-watcher/nestjs-quota/blob/master/src/nestjs/module/quota-module-options.ts"
click node_service "https://github.com/silent-watcher/nestjs-quota/blob/master/src/nestjs/module/quota.service.ts"
click node_meter "https://github.com/silent-watcher/nestjs-quota/blob/master/src/nestjs/interceptors/quota-meter.interceptor.ts"
click node_engine "https://github.com/silent-watcher/nestjs-quota/blob/master/src/core/application/engine.ts"
click node_policy "https://github.com/silent-watcher/nestjs-quota/blob/master/src/core/policies/policy.ts"
click node_window "https://github.com/silent-watcher/nestjs-quota/blob/master/src/core/windows/window.ts"
click node_identity "https://github.com/silent-watcher/nestjs-quota/blob/master/src/core/domain/identity.ts"
click node_key "https://github.com/silent-watcher/nestjs-quota/blob/master/src/core/domain/key.ts"
click node_clock "https://github.com/silent-watcher/nestjs-quota/blob/master/src/core/contracts/clock.ts"
click node_storecontract "https://github.com/silent-watcher/nestjs-quota/blob/master/src/core/contracts/store.ts"
click node_memory "https://github.com/silent-watcher/nestjs-quota/blob/master/src/stores/memory/memory-store.ts"
click node_redis "https://github.com/silent-watcher/nestjs-quota/blob/master/src/stores/redis/redis-store.ts"
click node_lua "https://github.com/silent-watcher/nestjs-quota/blob/master/src/stores/redis/lua-scripts.ts"
click node_result "https://github.com/silent-watcher/nestjs-quota/blob/master/src/core/application/types.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_engine,node_storecontract,node_result toneBlue
class node_guard,node_decorator,node_context,node_request,node_module,node_service,node_meter toneAmber
class node_memory,node_redis,node_lua,node_caller,node_route toneMint
class node_policy,node_window,node_identity,node_key,node_clock toneRose
```

## Components

### Quota core

- [Quota engine](https://github.com/silent-watcher/nestjs-quota/blob/master/src/core/application/engine.ts): `src/core/application/engine.ts`
- [Store contract](https://github.com/silent-watcher/nestjs-quota/blob/master/src/core/contracts/store.ts): `src/core/contracts/store.ts`
- [Quota decision and status](https://github.com/silent-watcher/nestjs-quota/blob/master/src/core/application/types.ts): `src/core/application/types.ts`

### NestJS adapter

- [Quota guard](https://github.com/silent-watcher/nestjs-quota/blob/master/src/nestjs/guards/quota.guard.ts): `src/nestjs/guards/quota.guard.ts`
- [Route metadata](https://github.com/silent-watcher/nestjs-quota/blob/master/src/nestjs/decorators/quota.decorator.ts): `src/nestjs/decorators/quota.decorator.ts`
- [Identity resolvers](https://github.com/silent-watcher/nestjs-quota/blob/master/src/nestjs/context/quota-context.ts): `src/nestjs/context/quota-context.ts`
- [Request state and headers](https://github.com/silent-watcher/nestjs-quota/blob/master/src/nestjs/context/request-marker.ts): `src/nestjs/context/request-marker.ts`
- [Module configuration](https://github.com/silent-watcher/nestjs-quota/blob/master/src/nestjs/module/quota-module-options.ts): `src/nestjs/module/quota-module-options.ts`
- [Quota service](https://github.com/silent-watcher/nestjs-quota/blob/master/src/nestjs/module/quota.service.ts): `src/nestjs/module/quota.service.ts`
- [Post-handler metering](https://github.com/silent-watcher/nestjs-quota/blob/master/src/nestjs/interceptors/quota-meter.interceptor.ts): `src/nestjs/interceptors/quota-meter.interceptor.ts`

### Storage adapters

- [Memory store](https://github.com/silent-watcher/nestjs-quota/blob/master/src/stores/memory/memory-store.ts): `src/stores/memory/memory-store.ts`
- [Redis store](https://github.com/silent-watcher/nestjs-quota/blob/master/src/stores/redis/redis-store.ts): `src/stores/redis/redis-store.ts`
- [Redis atomic scripts](https://github.com/silent-watcher/nestjs-quota/blob/master/src/stores/redis/lua-scripts.ts): `src/stores/redis/lua-scripts.ts`

### Core support

- [Policy resolution](https://github.com/silent-watcher/nestjs-quota/blob/master/src/core/policies/policy.ts): `src/core/policies/policy.ts`
- [Quota windows](https://github.com/silent-watcher/nestjs-quota/blob/master/src/core/windows/window.ts): `src/core/windows/window.ts`
- [Identity validation](https://github.com/silent-watcher/nestjs-quota/blob/master/src/core/domain/identity.ts): `src/core/domain/identity.ts`
- [Storage keys](https://github.com/silent-watcher/nestjs-quota/blob/master/src/core/domain/key.ts): `src/core/domain/key.ts`
- [Clock](https://github.com/silent-watcher/nestjs-quota/blob/master/src/core/contracts/clock.ts): `src/core/contracts/clock.ts`

### Other components

- **API caller**
- **NestJS route**

## Connections

- API caller → NestJS route: calls API (evidence: `README.md`)
- NestJS route → Quota guard: enters guard (evidence: `README.md`)
- Route metadata → Quota guard: provides metadata (evidence: `src/nestjs/guards/quota.guard.ts`)
- Quota guard → Identity resolvers: resolves identity (evidence: `src/nestjs/guards/quota.guard.ts`)
- Quota guard → Module configuration: reads options (evidence: `src/nestjs/guards/quota.guard.ts`)
- Quota guard → Quota engine: checks or consumes (evidence: `src/nestjs/guards/quota.guard.ts`)
- Quota guard → Request state and headers: stores request state (evidence: `src/nestjs/guards/quota.guard.ts`)
- Quota guard → Quota decision and status: uses statuses (evidence: `src/nestjs/guards/quota.guard.ts`)
- Module configuration → Quota engine: configures engine (evidence: `src/nestjs/module/quota.module.ts`)
- Quota service → Quota engine: delegates operations (evidence: `src/nestjs/module/quota.service.ts`)
- Post-handler metering → Quota engine: records usage (evidence: `src/nestjs/interceptors/quota-meter.interceptor.ts`)
- Quota engine → Policy resolution: resolves policies (evidence: `src/core/application/engine.ts`)
- Quota engine → Quota windows: resolves windows (evidence: `src/core/application/engine.ts`)
- Quota engine → Identity validation: validates subjects (evidence: `src/core/application/engine.ts`)
- Quota engine → Clock: reads time (evidence: `src/core/application/engine.ts`)
- Quota engine → Store contract: dispatches bucket operations (evidence: `src/core/application/engine.ts`)
- Store contract → Memory store: implemented by (evidence: `README.md`)
- Store contract → Redis store: implemented by (evidence: `README.md`)
- Redis store → Redis atomic scripts: executes scripts (evidence: `src/stores/redis/redis-store.ts`)
- Quota engine → Quota decision and status: returns decisions (evidence: `src/core/application/engine.ts`)
- Quota engine → Storage keys: uses key helpers (evidence: `src/core/application/engine.ts`)
- Quota service → API caller: exposes usage and reservations (evidence: `README.md`)