# yawpremuh/api-rate-limiter architecture

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

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

## Overview

This is a FastAPI service that enforces a per-client sliding-window quota. Requests are keyed by API key, or by client IP when no key is supplied; the middleware asks the limiter for a decision, dispatches allowed requests to the endpoint, and adds rate-limit headers or returns HTTP 429. The in-memory limiter keeps nanosecond timestamp logs under a lock. An optional async simulator generates concurrent traffic. The runtime flow is supported by the sampled source; other README capabilities are not separate runtime subsystems.

Main entry points: [`main.py`](https://github.com/yawpremuh/api-rate-limiter/blob/main/main.py) (Rate-limit middleware), [`rate_limiter.py`](https://github.com/yawpremuh/api-rate-limiter/blob/main/rate_limiter.py) (Sliding-window check), [`simulate_requests.py`](https://github.com/yawpremuh/api-rate-limiter/blob/main/simulate_requests.py) (Async traffic simulator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_service["API service"]
  node_middleware["Rate-limit middleware<br/>[main.py]"]
  node_client_key["Client identification<br/>[main.py]"]
  node_endpoint["Test endpoint<br/>[main.py]"]
end

subgraph group_limiter["Rate limiter"]
  node_limiter_core["Sliding-window check<br/>[rate_limiter.py]"]
  node_request_logs[("Timestamp logs<br/>[rate_limiter.py]")]
  node_lock["Thread lock<br/>[rate_limiter.py]"]
end

subgraph group_client["Traffic client"]
  node_simulator["Async traffic simulator"]
end

node_caller(("API caller"))
node_api_service(("Running API service"))

node_caller -->|"sends request"| node_middleware
node_middleware -->|"derives key"| node_client_key
node_middleware -->|"checks quota"| node_limiter_core
node_limiter_core -->|"prunes and records"| node_request_logs
node_limiter_core -->|"locks access"| node_lock
node_limiter_core -->|"returns decision"| node_middleware
node_middleware -->|"dispatches if allowed"| node_endpoint
node_middleware -->|"returns status and headers"| node_caller
node_simulator -.->|"sends concurrent requests"| node_api_service
node_api_service -.->|"returns statuses"| node_simulator

click node_middleware "https://github.com/yawpremuh/api-rate-limiter/blob/main/main.py"
click node_client_key "https://github.com/yawpremuh/api-rate-limiter/blob/main/main.py"
click node_endpoint "https://github.com/yawpremuh/api-rate-limiter/blob/main/main.py"
click node_limiter_core "https://github.com/yawpremuh/api-rate-limiter/blob/main/rate_limiter.py"
click node_request_logs "https://github.com/yawpremuh/api-rate-limiter/blob/main/rate_limiter.py"
click node_lock "https://github.com/yawpremuh/api-rate-limiter/blob/main/rate_limiter.py"
click node_simulator "https://github.com/yawpremuh/api-rate-limiter/blob/main/simulate_requests.py"

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_client_key,node_endpoint toneBlue
class node_limiter_core,node_request_logs,node_lock toneAmber
class node_simulator,node_caller,node_api_service toneMint
```

## Components

### API service

- [Rate-limit middleware](https://github.com/yawpremuh/api-rate-limiter/blob/main/main.py): `main.py`
- [Client identification](https://github.com/yawpremuh/api-rate-limiter/blob/main/main.py): `main.py`
- [Test endpoint](https://github.com/yawpremuh/api-rate-limiter/blob/main/main.py): `main.py`

### Rate limiter

- [Sliding-window check](https://github.com/yawpremuh/api-rate-limiter/blob/main/rate_limiter.py): `rate_limiter.py`
- [Timestamp logs](https://github.com/yawpremuh/api-rate-limiter/blob/main/rate_limiter.py): `rate_limiter.py`
- [Thread lock](https://github.com/yawpremuh/api-rate-limiter/blob/main/rate_limiter.py): `rate_limiter.py`

### Traffic client

- [Async traffic simulator](https://github.com/yawpremuh/api-rate-limiter/blob/main/simulate_requests.py): `simulate_requests.py`

### Other components

- **API caller**
- **Running API service**

## Connections

- API caller → Rate-limit middleware: sends request
- Rate-limit middleware → Client identification: derives key
- Rate-limit middleware → Sliding-window check: checks quota
- Sliding-window check → Timestamp logs: prunes and records
- Sliding-window check → Thread lock: locks access
- Sliding-window check → Rate-limit middleware: returns decision
- Rate-limit middleware → Test endpoint: dispatches if allowed
- Rate-limit middleware → API caller: returns status and headers
- Async traffic simulator → Running API service: sends concurrent requests
- Running API service → Async traffic simulator: returns statuses