# agnivesh13/aegis-distributed-limiter architecture

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

- Interactive diagram: https://gitdiagram.com/agnivesh13/aegis-distributed-limiter
- Repository: https://github.com/agnivesh13/aegis-distributed-limiter

## Overview

Aegis is a distributed rate-limiting HTTP gateway, with memory, exact Redis, and approximate gossip backends. A client request enters a gateway, whose proxy matches a route, identifies the client, asks the configured limiter, then proxies permitted traffic upstream. Separately, load generation records request outcomes; analysis compares a run with a reference limiter and reports accuracy and latency. The graph preserves the documented backend and measurement branches. Some internal gossip wiring is not shown in the excerpts, so those relationships are omitted.

Main entry points: [`cmd/gateway/main.go`](https://github.com/agnivesh13/aegis-distributed-limiter/blob/main/cmd/gateway/main.go) (Gateway startup), [`internal/proxy/proxy.go`](https://github.com/agnivesh13/aegis-distributed-limiter/blob/main/internal/proxy/proxy.go) (Proxy and middleware), [`internal/limiter/gossip/node.go`](https://github.com/agnivesh13/aegis-distributed-limiter/blob/main/internal/limiter/gossip/node.go) (Gossip node), [`internal/limiter/limiter.go`](https://github.com/agnivesh13/aegis-distributed-limiter/blob/main/internal/limiter/limiter.go) (Limiter contract)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["Gateway request path"]
  node_gateway_app["Gateway startup<br/>[main.go]"]
  node_config["Configuration<br/>[config.go]"]
  node_proxy["Proxy and middleware<br/>[proxy.go]"]
end

subgraph group_limiting["Limiter backends"]
  node_limiter_contract["Limiter contract<br/>[limiter.go]"]
  node_memory["Memory backend<br/>[memory.go]"]
  node_redis_backend["Redis backend<br/>[redis.go]"]
  node_gossip_node["Gossip node<br/>[node.go]"]
  node_gossip_store[("Gossip state store<br/>[store.go]")]
  node_gossip_codec["Gossip codec<br/>[codec.go]"]
  node_gossip_memberlist["Memberlist transport<br/>[memberlist.go]"]
  node_gossip_merge["State merge<br/>[merge.go]"]
  node_gossip_transport["Transport interface<br/>[transport.go]"]
end

subgraph group_measurement["Load and analysis"]
  node_loadgen["Load generator<br/>[main.go]"]
  node_schedule["Request scheduling<br/>[schedule.go]"]
  node_analyze_cli["Analysis command<br/>[main.go]"]
  node_analysis["Run analysis<br/>[analyze.go]"]
end

subgraph group_operations["Service operations"]
  node_metrics["Gateway metrics<br/>[metrics.go]"]
  node_admin["Admin endpoints<br/>[admin.go]"]
  node_upstream["Echo upstream<br/>[main.go]"]
end

node_client(("HTTP client"))
node_redis[("Redis")]

node_client -->|"sends requests"| node_gateway_app
node_gateway_app -->|"loads settings"| node_config
node_gateway_app -->|"serves requests"| node_proxy
node_gateway_app -->|"serves admin"| node_admin
node_gateway_app -->|"configures metrics"| node_metrics
node_gateway_app -->|"selects backend"| node_memory
node_gateway_app -->|"selects backend"| node_redis_backend
node_gateway_app -->|"starts gossip"| node_gossip_node
node_proxy -->|"checks limits"| node_limiter_contract
node_proxy -->|"records requests"| node_metrics
node_proxy -.->|"proxies allowed traffic"| node_upstream
node_memory -->|"implements"| node_limiter_contract
node_redis_backend -->|"implements"| node_limiter_contract
node_redis_backend -->|"runs atomic scripts"| node_redis
node_gossip_node -->|"implements"| node_limiter_contract
node_gossip_node -->|"decides from local state"| node_gossip_store
node_gossip_node -.->|"attaches transport"| node_gossip_memberlist
node_loadgen -->|"schedules requests"| node_schedule
node_loadgen -->|"sends load"| node_gateway_app
node_analyze_cli -->|"analyzes CSV"| node_analysis
node_analysis -->|"replays reference"| node_memory

click node_gateway_app "https://github.com/agnivesh13/aegis-distributed-limiter/blob/main/cmd/gateway/main.go"
click node_config "https://github.com/agnivesh13/aegis-distributed-limiter/blob/main/internal/config/config.go"
click node_proxy "https://github.com/agnivesh13/aegis-distributed-limiter/blob/main/internal/proxy/proxy.go"
click node_metrics "https://github.com/agnivesh13/aegis-distributed-limiter/blob/main/internal/metrics/metrics.go"
click node_admin "https://github.com/agnivesh13/aegis-distributed-limiter/blob/main/internal/admin/admin.go"
click node_limiter_contract "https://github.com/agnivesh13/aegis-distributed-limiter/blob/main/internal/limiter/limiter.go"
click node_memory "https://github.com/agnivesh13/aegis-distributed-limiter/blob/main/internal/limiter/memory/memory.go"
click node_redis_backend "https://github.com/agnivesh13/aegis-distributed-limiter/blob/main/internal/limiter/redis/redis.go"
click node_gossip_node "https://github.com/agnivesh13/aegis-distributed-limiter/blob/main/internal/limiter/gossip/node.go"
click node_gossip_store "https://github.com/agnivesh13/aegis-distributed-limiter/blob/main/internal/limiter/gossip/store.go"
click node_gossip_codec "https://github.com/agnivesh13/aegis-distributed-limiter/blob/main/internal/limiter/gossip/codec.go"
click node_gossip_memberlist "https://github.com/agnivesh13/aegis-distributed-limiter/blob/main/internal/limiter/gossip/memberlist.go"
click node_gossip_merge "https://github.com/agnivesh13/aegis-distributed-limiter/blob/main/internal/limiter/gossip/merge.go"
click node_gossip_transport "https://github.com/agnivesh13/aegis-distributed-limiter/blob/main/internal/limiter/gossip/transport.go"
click node_upstream "https://github.com/agnivesh13/aegis-distributed-limiter/blob/main/cmd/upstream/main.go"
click node_loadgen "https://github.com/agnivesh13/aegis-distributed-limiter/blob/main/cmd/loadgen/main.go"
click node_schedule "https://github.com/agnivesh13/aegis-distributed-limiter/blob/main/internal/loadgen/schedule.go"
click node_analyze_cli "https://github.com/agnivesh13/aegis-distributed-limiter/blob/main/cmd/analyze/main.go"
click node_analysis "https://github.com/agnivesh13/aegis-distributed-limiter/blob/main/internal/analyze/analyze.go"

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_gateway_app,node_config,node_proxy,node_client toneBlue
class node_limiter_contract,node_memory,node_redis_backend,node_gossip_node,node_gossip_store,node_gossip_codec,node_gossip_memberlist,node_gossip_merge,node_gossip_transport,node_redis toneAmber
class node_loadgen,node_schedule,node_analyze_cli,node_analysis toneMint
class node_metrics,node_admin,node_upstream toneRose
```

## Components

### Gateway request path

- [Gateway startup](https://github.com/agnivesh13/aegis-distributed-limiter/blob/main/cmd/gateway/main.go): `cmd/gateway/main.go`
- [Configuration](https://github.com/agnivesh13/aegis-distributed-limiter/blob/main/internal/config/config.go): `internal/config/config.go`
- [Proxy and middleware](https://github.com/agnivesh13/aegis-distributed-limiter/blob/main/internal/proxy/proxy.go): `internal/proxy/proxy.go`

### Limiter backends

- [Limiter contract](https://github.com/agnivesh13/aegis-distributed-limiter/blob/main/internal/limiter/limiter.go): `internal/limiter/limiter.go`
- [Memory backend](https://github.com/agnivesh13/aegis-distributed-limiter/blob/main/internal/limiter/memory/memory.go): `internal/limiter/memory/memory.go`
- [Redis backend](https://github.com/agnivesh13/aegis-distributed-limiter/blob/main/internal/limiter/redis/redis.go): `internal/limiter/redis/redis.go`
- [Gossip node](https://github.com/agnivesh13/aegis-distributed-limiter/blob/main/internal/limiter/gossip/node.go): `internal/limiter/gossip/node.go`
- [Gossip state store](https://github.com/agnivesh13/aegis-distributed-limiter/blob/main/internal/limiter/gossip/store.go): `internal/limiter/gossip/store.go`
- [Gossip codec](https://github.com/agnivesh13/aegis-distributed-limiter/blob/main/internal/limiter/gossip/codec.go): `internal/limiter/gossip/codec.go`
- [Memberlist transport](https://github.com/agnivesh13/aegis-distributed-limiter/blob/main/internal/limiter/gossip/memberlist.go): `internal/limiter/gossip/memberlist.go`
- [State merge](https://github.com/agnivesh13/aegis-distributed-limiter/blob/main/internal/limiter/gossip/merge.go): `internal/limiter/gossip/merge.go`
- [Transport interface](https://github.com/agnivesh13/aegis-distributed-limiter/blob/main/internal/limiter/gossip/transport.go): `internal/limiter/gossip/transport.go`

### Load and analysis

- [Load generator](https://github.com/agnivesh13/aegis-distributed-limiter/blob/main/cmd/loadgen/main.go): `cmd/loadgen/main.go`
- [Request scheduling](https://github.com/agnivesh13/aegis-distributed-limiter/blob/main/internal/loadgen/schedule.go): `internal/loadgen/schedule.go`
- [Analysis command](https://github.com/agnivesh13/aegis-distributed-limiter/blob/main/cmd/analyze/main.go): `cmd/analyze/main.go`
- [Run analysis](https://github.com/agnivesh13/aegis-distributed-limiter/blob/main/internal/analyze/analyze.go): `internal/analyze/analyze.go`

### Service operations

- [Gateway metrics](https://github.com/agnivesh13/aegis-distributed-limiter/blob/main/internal/metrics/metrics.go): `internal/metrics/metrics.go`
- [Admin endpoints](https://github.com/agnivesh13/aegis-distributed-limiter/blob/main/internal/admin/admin.go): `internal/admin/admin.go`
- [Echo upstream](https://github.com/agnivesh13/aegis-distributed-limiter/blob/main/cmd/upstream/main.go): `cmd/upstream/main.go`

### Other components

- **HTTP client**
- **Redis**

## Connections

- HTTP client → Gateway startup: sends requests (evidence: `README.md`)
- Gateway startup → Configuration: loads settings (evidence: `cmd/gateway/main.go`)
- Gateway startup → Proxy and middleware: serves requests (evidence: `cmd/gateway/main.go`)
- Gateway startup → Admin endpoints: serves admin (evidence: `cmd/gateway/main.go`)
- Gateway startup → Gateway metrics: configures metrics (evidence: `cmd/gateway/main.go`)
- Gateway startup → Memory backend: selects backend (evidence: `cmd/gateway/main.go`)
- Gateway startup → Redis backend: selects backend (evidence: `cmd/gateway/main.go`)
- Gateway startup → Gossip node: starts gossip (evidence: `cmd/gateway/main.go`)
- Proxy and middleware → Limiter contract: checks limits (evidence: `internal/proxy/proxy.go`)
- Proxy and middleware → Gateway metrics: records requests (evidence: `internal/proxy/proxy.go`)
- Proxy and middleware → Echo upstream: proxies allowed traffic
- Memory backend → Limiter contract: implements (evidence: `internal/limiter/memory/memory.go`)
- Redis backend → Limiter contract: implements (evidence: `internal/limiter/redis/redis.go`)
- Redis backend → Redis: runs atomic scripts (evidence: `internal/limiter/redis/redis.go`)
- Gossip node → Limiter contract: implements (evidence: `internal/limiter/gossip/node.go`)
- Gossip node → Gossip state store: decides from local state (evidence: `internal/limiter/gossip/node.go`)
- Gossip node → Memberlist transport: attaches transport
- Load generator → Request scheduling: schedules requests (evidence: `cmd/loadgen/main.go`)
- Load generator → Gateway startup: sends load (evidence: `README.md`)
- Analysis command → Run analysis: analyzes CSV (evidence: `cmd/analyze/main.go`)
- Run analysis → Memory backend: replays reference (evidence: `internal/analyze/analyze.go`)