# saintparish4/gate architecture

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

- Interactive diagram: https://gitdiagram.com/saintparish4/gate
- Repository: https://github.com/saintparish4/gate

## Overview

Gate accepts authenticated API requests for globally distributed rate limiting, idempotency checks, and LLM token quotas, then returns decisions and usage outcomes. Rate-limit requests pass through resilience controls before shared state is accessed; idempotency and quota use their own persistence paths. The README documents event publishing, health/readiness, metrics, tracing, and a demo dashboard as additional capabilities. Some wiring and handlers were not sampled, so links for documented but unsampled branches are limited to the documented architecture.

Main entry points: [`src/main/scala/api/Routes.scala`](https://github.com/saintparish4/gate/blob/master/src/main/scala/api/Routes.scala) (HTTP routes), [`src/main/scala/Main.scala`](https://github.com/saintparish4/gate/blob/master/src/main/scala/Main.scala) (Application runtime), [`src/main/scala/api/RateLimitApi.scala`](https://github.com/saintparish4/gate/blob/master/src/main/scala/api/RateLimitApi.scala) (Rate-limit API), [`src/main/scala/api/IdempotencyApi.scala`](https://github.com/saintparish4/gate/blob/master/src/main/scala/api/IdempotencyApi.scala) (Idempotency API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["HTTP and security"]
  node_routes["HTTP routes<br/>[Routes.scala]"]
  node_auth["API key auth<br/>[ApiKeyAuth.scala]"]
  node_rateapi["Rate-limit API<br/>[RateLimitApi.scala]"]
  node_idemapi["Idempotency API"]
  node_quotaapi["Quota API"]
  node_dashboard["Demo dashboard<br/>[DashboardApi.scala]"]
end

subgraph group_domain["Decision engines"]
  node_rateengine["Rate-limit engine<br/>[TokenBucket.scala]"]
  node_idemengine["Idempotency engine"]
  node_quotaservice["Quota service"]
end

subgraph group_state["State and resilience"]
  node_resilience["Resilience wrapper"]
  node_ratestore["Rate-limit store"]
  node_idemstore["Idempotency store"]
  node_quotastore["Quota store"]
  node_dynamodb[("DynamoDB")]
end

subgraph group_ops["Events and observability"]
  node_events["Event publisher"]
  node_kinesis["Kinesis stream"]
  node_metrics["Metrics publisher"]
  node_prom["Prometheus metrics"]
  node_tracing["Tracing middleware"]
  node_health["Health aggregation"]
end

subgraph group_runtime["Application wiring"]
  node_main["Application runtime<br/>[Main.scala]"]
  node_storemodule["Store wiring<br/>[StoreModule.scala]"]
end

node_client(("API client"))

node_client -->|"sends HTTP"| node_routes
node_routes -->|"authenticates"| node_auth
node_routes -->|"dispatches checks"| node_rateapi
node_routes -->|"dispatches checks"| node_idemapi
node_routes -->|"dispatches quota"| node_quotaapi
node_routes -.->|"serves dashboard"| node_dashboard
node_routes -->|"scrapes metrics"| node_prom
node_routes -->|"checks readiness"| node_health
node_rateapi -->|"checks limits"| node_resilience
node_resilience -->|"wraps operations"| node_ratestore
node_ratestore -->|"reads and writes"| node_dynamodb
node_idemapi -->|"checks and completes"| node_idemstore
node_idemstore -->|"reads and writes"| node_dynamodb
node_quotaapi -->|"checks and reconciles"| node_quotaservice
node_quotaservice -->|"reserves quota"| node_quotastore
node_quotastore -->|"reads and writes"| node_dynamodb
node_rateapi -->|"publishes decisions"| node_events
node_idemapi -->|"publishes outcomes"| node_events
node_quotaapi -.->|"publishes outcomes"| node_events
node_events -.->|"queues events"| node_kinesis
node_rateapi -->|"records metrics"| node_metrics
node_idemapi -->|"records metrics"| node_metrics
node_quotaservice -->|"records metrics"| node_metrics
node_main -->|"creates stores"| node_storemodule
node_storemodule -->|"wraps rate store"| node_resilience
node_storemodule -->|"selects backend"| node_ratestore
node_main -->|"starts HTTP app"| node_routes
node_main -->|"assembles checks"| node_health
node_main -->|"configures metrics"| node_metrics
node_main -->|"installs tracing"| node_tracing

click node_routes "https://github.com/saintparish4/gate/blob/master/src/main/scala/api/Routes.scala"
click node_auth "https://github.com/saintparish4/gate/blob/master/src/main/scala/security/ApiKeyAuth.scala"
click node_rateapi "https://github.com/saintparish4/gate/blob/master/src/main/scala/api/RateLimitApi.scala"
click node_idemapi "https://github.com/saintparish4/gate/blob/master/src/main/scala/api/IdempotencyApi.scala"
click node_quotaapi "https://github.com/saintparish4/gate/blob/master/src/main/scala/api/TokenQuotaApi.scala"
click node_dashboard "https://github.com/saintparish4/gate/blob/master/src/main/scala/api/DashboardApi.scala"
click node_rateengine "https://github.com/saintparish4/gate/blob/master/src/main/scala/core/TokenBucket.scala"
click node_idemengine "https://github.com/saintparish4/gate/blob/master/src/main/scala/core/IdempotencyStore.scala"
click node_quotaservice "https://github.com/saintparish4/gate/blob/master/src/main/scala/core/TokenQuotaService.scala"
click node_resilience "https://github.com/saintparish4/gate/blob/master/src/main/scala/resilience/ResilientWrapper.scala"
click node_ratestore "https://github.com/saintparish4/gate/blob/master/src/main/scala/storage/DynamoDBRateLimitStore.scala"
click node_idemstore "https://github.com/saintparish4/gate/blob/master/src/main/scala/storage/DynamoDBIdempotencyStore.scala"
click node_quotastore "https://github.com/saintparish4/gate/blob/master/src/main/scala/storage/DynamoDBTokenQuotaStore.scala"
click node_events "https://github.com/saintparish4/gate/blob/master/src/main/scala/events/EventPublisher.scala"
click node_metrics "https://github.com/saintparish4/gate/blob/master/src/main/scala/observability/MetricsPublisher.scala"
click node_prom "https://github.com/saintparish4/gate/blob/master/src/main/scala/observability/PrometheusMetrics.scala"
click node_tracing "https://github.com/saintparish4/gate/blob/master/src/main/scala/observability/TracingMiddleware.scala"
click node_health "https://github.com/saintparish4/gate/blob/master/src/main/scala/resilience/HealthAggregator.scala"
click node_main "https://github.com/saintparish4/gate/blob/master/src/main/scala/Main.scala"
click node_storemodule "https://github.com/saintparish4/gate/blob/master/src/main/scala/wiring/StoreModule.scala"

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_routes,node_auth,node_rateapi,node_idemapi,node_quotaapi,node_dashboard,node_client toneBlue
class node_rateengine,node_idemengine,node_quotaservice toneAmber
class node_resilience,node_ratestore,node_idemstore,node_quotastore,node_dynamodb toneMint
class node_events,node_kinesis,node_metrics,node_prom,node_tracing,node_health toneRose
class node_main,node_storemodule toneIndigo
```

## Components

### HTTP and security

- [HTTP routes](https://github.com/saintparish4/gate/blob/master/src/main/scala/api/Routes.scala): `src/main/scala/api/Routes.scala`
- [API key auth](https://github.com/saintparish4/gate/blob/master/src/main/scala/security/ApiKeyAuth.scala): `src/main/scala/security/ApiKeyAuth.scala`
- [Rate-limit API](https://github.com/saintparish4/gate/blob/master/src/main/scala/api/RateLimitApi.scala): `src/main/scala/api/RateLimitApi.scala`
- [Idempotency API](https://github.com/saintparish4/gate/blob/master/src/main/scala/api/IdempotencyApi.scala): `src/main/scala/api/IdempotencyApi.scala`
- [Quota API](https://github.com/saintparish4/gate/blob/master/src/main/scala/api/TokenQuotaApi.scala): `src/main/scala/api/TokenQuotaApi.scala`
- [Demo dashboard](https://github.com/saintparish4/gate/blob/master/src/main/scala/api/DashboardApi.scala): `src/main/scala/api/DashboardApi.scala`

### Decision engines

- [Rate-limit engine](https://github.com/saintparish4/gate/blob/master/src/main/scala/core/TokenBucket.scala): `src/main/scala/core/TokenBucket.scala`
- [Idempotency engine](https://github.com/saintparish4/gate/blob/master/src/main/scala/core/IdempotencyStore.scala): `src/main/scala/core/IdempotencyStore.scala`
- [Quota service](https://github.com/saintparish4/gate/blob/master/src/main/scala/core/TokenQuotaService.scala): `src/main/scala/core/TokenQuotaService.scala`

### State and resilience

- [Resilience wrapper](https://github.com/saintparish4/gate/blob/master/src/main/scala/resilience/ResilientWrapper.scala): `src/main/scala/resilience/ResilientWrapper.scala`
- [Rate-limit store](https://github.com/saintparish4/gate/blob/master/src/main/scala/storage/DynamoDBRateLimitStore.scala): `src/main/scala/storage/DynamoDBRateLimitStore.scala`
- [Idempotency store](https://github.com/saintparish4/gate/blob/master/src/main/scala/storage/DynamoDBIdempotencyStore.scala): `src/main/scala/storage/DynamoDBIdempotencyStore.scala`
- [Quota store](https://github.com/saintparish4/gate/blob/master/src/main/scala/storage/DynamoDBTokenQuotaStore.scala): `src/main/scala/storage/DynamoDBTokenQuotaStore.scala`
- **DynamoDB**

### Events and observability

- [Event publisher](https://github.com/saintparish4/gate/blob/master/src/main/scala/events/EventPublisher.scala): `src/main/scala/events/EventPublisher.scala`
- **Kinesis stream**
- [Metrics publisher](https://github.com/saintparish4/gate/blob/master/src/main/scala/observability/MetricsPublisher.scala): `src/main/scala/observability/MetricsPublisher.scala`
- [Prometheus metrics](https://github.com/saintparish4/gate/blob/master/src/main/scala/observability/PrometheusMetrics.scala): `src/main/scala/observability/PrometheusMetrics.scala`
- [Tracing middleware](https://github.com/saintparish4/gate/blob/master/src/main/scala/observability/TracingMiddleware.scala): `src/main/scala/observability/TracingMiddleware.scala`
- [Health aggregation](https://github.com/saintparish4/gate/blob/master/src/main/scala/resilience/HealthAggregator.scala): `src/main/scala/resilience/HealthAggregator.scala`

### Application wiring

- [Application runtime](https://github.com/saintparish4/gate/blob/master/src/main/scala/Main.scala): `src/main/scala/Main.scala`
- [Store wiring](https://github.com/saintparish4/gate/blob/master/src/main/scala/wiring/StoreModule.scala): `src/main/scala/wiring/StoreModule.scala`

### Other components

- **API client**

## Connections

- API client → HTTP routes: sends HTTP
- HTTP routes → API key auth: authenticates
- HTTP routes → Rate-limit API: dispatches checks
- HTTP routes → Idempotency API: dispatches checks
- HTTP routes → Quota API: dispatches quota
- HTTP routes → Demo dashboard: serves dashboard
- HTTP routes → Prometheus metrics: scrapes metrics
- HTTP routes → Health aggregation: checks readiness
- Rate-limit API → Resilience wrapper: checks limits
- Resilience wrapper → Rate-limit store: wraps operations
- Rate-limit store → DynamoDB: reads and writes
- Idempotency API → Idempotency store: checks and completes
- Idempotency store → DynamoDB: reads and writes
- Quota API → Quota service: checks and reconciles
- Quota service → Quota store: reserves quota
- Quota store → DynamoDB: reads and writes
- Rate-limit API → Event publisher: publishes decisions
- Idempotency API → Event publisher: publishes outcomes
- Quota API → Event publisher: publishes outcomes
- Event publisher → Kinesis stream: queues events
- Rate-limit API → Metrics publisher: records metrics
- Idempotency API → Metrics publisher: records metrics
- Quota service → Metrics publisher: records metrics
- Application runtime → Store wiring: creates stores
- Store wiring → Resilience wrapper: wraps rate store
- Store wiring → Rate-limit store: selects backend
- Application runtime → HTTP routes: starts HTTP app
- Application runtime → Health aggregation: assembles checks
- Application runtime → Metrics publisher: configures metrics
- Application runtime → Tracing middleware: installs tracing