# nidjbs/go-ai-gateway architecture

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

- Interactive diagram: https://gitdiagram.com/nidjbs/go-ai-gateway
- Repository: https://github.com/nidjbs/go-ai-gateway

## Overview

go-ai-gateway is an OpenAI-compatible gateway that authenticates client requests, applies limits and optional guardrails, routes model aliases to upstream providers, and records outcomes. The gateway handlers own request execution, including retries and failover; provider adapters handle upstream protocols. A separate operational surface exposes administration and observability, while the documented `gw` CLI provides a local HTTP client for chat, agent commands, and scheduling. Relationships among unsampled subsystems are included only where documented; some internal wiring remains unverified.

Main entry points: [`internal/gateway/handlers.go`](https://github.com/nidjbs/go-ai-gateway/blob/main/internal/gateway/handlers.go) (API handlers), [`internal/gateway/server.go`](https://github.com/nidjbs/go-ai-gateway/blob/main/internal/gateway/server.go) (HTTP server), [`internal/retry/executor.go`](https://github.com/nidjbs/go-ai-gateway/blob/main/internal/retry/executor.go) (Retry and failover), [`cli/main.go`](https://github.com/nidjbs/go-ai-gateway/blob/main/cli/main.go) (gw CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Gateway API"]
  node_handlers["API handlers<br/>[handlers.go]"]
  node_auth["Authentication<br/>[auth.go]"]
  node_limits["Limits and quotas<br/>[limiter.go]"]
  node_guardrails["Injection guardrails<br/>[middleware.go]"]
  node_dlp["Output DLP<br/>[dlp.go]"]
  node_gateway_server["HTTP server<br/>[server.go]"]
end

subgraph group_execution["Request Execution"]
  node_routing["Alias routing<br/>[router.go]"]
  node_retry["Retry and failover<br/>[executor.go]"]
  node_breaker["Circuit breaker<br/>[breaker.go]"]
  node_openai["OpenAI adapter<br/>[openai.go]"]
  node_anthropic["Anthropic adapter<br/>[anthropic.go]"]
  node_plugin["Plugin framework<br/>[plugin.go]"]
end

subgraph group_operations["Operations"]
  node_usage["Usage records<br/>[usage.go]"]
  node_usage_store[("SQLite usage store<br/>[sqlite_driver.go]")]
  node_revocation["Key revocation<br/>[revocation.go]"]
  node_metrics["Prometheus metrics<br/>[metrics.go]"]
  node_tracing["OpenTelemetry tracing<br/>[tracing.go]"]
end

subgraph group_cli["CLI Client"]
  node_cli["gw CLI<br/>[main.go]"]
  node_cli_repl["Agent REPL<br/>[repl.go]"]
  node_cli_schedule["Task scheduler<br/>[schedule.go]"]
end

node_clients(("AI clients"))
node_upstream["Model providers"]
node_cli_user(("CLI user"))

node_clients -->|"sends API requests"| node_handlers
node_gateway_server -->|"routes requests"| node_handlers
node_handlers -->|"checks identity"| node_auth
node_handlers -->|"checks quotas"| node_limits
node_gateway_server -->|"installs middleware"| node_guardrails
node_handlers -->|"masks output"| node_dlp
node_handlers -->|"runs plugins"| node_plugin
node_handlers -->|"resolves aliases"| node_routing
node_handlers -->|"executes attempts"| node_retry
node_retry -->|"checks breaker"| node_breaker
node_retry -.->|"invokes adapter"| node_openai
node_retry -.->|"invokes adapter"| node_anthropic
node_openai -.->|"calls provider"| node_upstream
node_anthropic -.->|"calls provider"| node_upstream
node_handlers -->|"records usage"| node_usage
node_usage -.->|"persists records"| node_usage_store
node_gateway_server -.->|"configures revocation"| node_revocation
node_gateway_server -->|"serves metrics"| node_metrics
node_gateway_server -.->|"enables tracing"| node_tracing
node_cli_user -->|"runs commands"| node_cli
node_cli -->|"calls gateway API"| node_handlers
node_cli -.->|"starts REPL"| node_cli_repl
node_cli -.->|"manages schedules"| node_cli_schedule

click node_handlers "https://github.com/nidjbs/go-ai-gateway/blob/main/internal/gateway/handlers.go"
click node_auth "https://github.com/nidjbs/go-ai-gateway/blob/main/internal/auth/auth.go"
click node_limits "https://github.com/nidjbs/go-ai-gateway/blob/main/internal/ratelimit/limiter.go"
click node_guardrails "https://github.com/nidjbs/go-ai-gateway/blob/main/internal/guardrails/middleware.go"
click node_dlp "https://github.com/nidjbs/go-ai-gateway/blob/main/internal/dlp/dlp.go"
click node_routing "https://github.com/nidjbs/go-ai-gateway/blob/main/internal/routing/router.go"
click node_retry "https://github.com/nidjbs/go-ai-gateway/blob/main/internal/retry/executor.go"
click node_breaker "https://github.com/nidjbs/go-ai-gateway/blob/main/internal/circuitbreaker/breaker.go"
click node_openai "https://github.com/nidjbs/go-ai-gateway/blob/main/internal/provider/openai.go"
click node_anthropic "https://github.com/nidjbs/go-ai-gateway/blob/main/internal/provider/anthropic.go"
click node_plugin "https://github.com/nidjbs/go-ai-gateway/blob/main/internal/plugin/plugin.go"
click node_usage "https://github.com/nidjbs/go-ai-gateway/blob/main/internal/usage/usage.go"
click node_usage_store "https://github.com/nidjbs/go-ai-gateway/blob/main/internal/usage/sqlite_driver.go"
click node_revocation "https://github.com/nidjbs/go-ai-gateway/blob/main/internal/revocation/revocation.go"
click node_metrics "https://github.com/nidjbs/go-ai-gateway/blob/main/internal/metrics/metrics.go"
click node_tracing "https://github.com/nidjbs/go-ai-gateway/blob/main/internal/tracing/tracing.go"
click node_gateway_server "https://github.com/nidjbs/go-ai-gateway/blob/main/internal/gateway/server.go"
click node_cli "https://github.com/nidjbs/go-ai-gateway/blob/main/cli/main.go"
click node_cli_repl "https://github.com/nidjbs/go-ai-gateway/blob/main/cli/repl.go"
click node_cli_schedule "https://github.com/nidjbs/go-ai-gateway/blob/main/cli/schedule.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_handlers,node_auth,node_limits,node_guardrails,node_dlp,node_gateway_server,node_clients,node_cli_user toneBlue
class node_routing,node_retry,node_breaker,node_openai,node_anthropic,node_plugin toneAmber
class node_usage,node_usage_store,node_revocation,node_metrics,node_tracing toneMint
class node_cli,node_cli_repl,node_cli_schedule toneRose
class node_upstream toneIndigo
```

## Components

### Gateway API

- [API handlers](https://github.com/nidjbs/go-ai-gateway/blob/main/internal/gateway/handlers.go): `internal/gateway/handlers.go`
- [Authentication](https://github.com/nidjbs/go-ai-gateway/blob/main/internal/auth/auth.go): `internal/auth/auth.go`
- [Limits and quotas](https://github.com/nidjbs/go-ai-gateway/blob/main/internal/ratelimit/limiter.go): `internal/ratelimit/limiter.go`
- [Injection guardrails](https://github.com/nidjbs/go-ai-gateway/blob/main/internal/guardrails/middleware.go): `internal/guardrails/middleware.go`
- [Output DLP](https://github.com/nidjbs/go-ai-gateway/blob/main/internal/dlp/dlp.go): `internal/dlp/dlp.go`
- [HTTP server](https://github.com/nidjbs/go-ai-gateway/blob/main/internal/gateway/server.go): `internal/gateway/server.go`

### Request Execution

- [Alias routing](https://github.com/nidjbs/go-ai-gateway/blob/main/internal/routing/router.go): `internal/routing/router.go`
- [Retry and failover](https://github.com/nidjbs/go-ai-gateway/blob/main/internal/retry/executor.go): `internal/retry/executor.go`
- [Circuit breaker](https://github.com/nidjbs/go-ai-gateway/blob/main/internal/circuitbreaker/breaker.go): `internal/circuitbreaker/breaker.go`
- [OpenAI adapter](https://github.com/nidjbs/go-ai-gateway/blob/main/internal/provider/openai.go): `internal/provider/openai.go`
- [Anthropic adapter](https://github.com/nidjbs/go-ai-gateway/blob/main/internal/provider/anthropic.go): `internal/provider/anthropic.go`
- [Plugin framework](https://github.com/nidjbs/go-ai-gateway/blob/main/internal/plugin/plugin.go): `internal/plugin/plugin.go`

### Operations

- [Usage records](https://github.com/nidjbs/go-ai-gateway/blob/main/internal/usage/usage.go): `internal/usage/usage.go`
- [SQLite usage store](https://github.com/nidjbs/go-ai-gateway/blob/main/internal/usage/sqlite_driver.go): `internal/usage/sqlite_driver.go`
- [Key revocation](https://github.com/nidjbs/go-ai-gateway/blob/main/internal/revocation/revocation.go): `internal/revocation/revocation.go`
- [Prometheus metrics](https://github.com/nidjbs/go-ai-gateway/blob/main/internal/metrics/metrics.go): `internal/metrics/metrics.go`
- [OpenTelemetry tracing](https://github.com/nidjbs/go-ai-gateway/blob/main/internal/tracing/tracing.go): `internal/tracing/tracing.go`

### CLI Client

- [gw CLI](https://github.com/nidjbs/go-ai-gateway/blob/main/cli/main.go): `cli/main.go`
- [Agent REPL](https://github.com/nidjbs/go-ai-gateway/blob/main/cli/repl.go): `cli/repl.go`
- [Task scheduler](https://github.com/nidjbs/go-ai-gateway/blob/main/cli/schedule.go): `cli/schedule.go`

### Other components

- **AI clients**
- **Model providers**
- **CLI user**

## Connections

- AI clients → API handlers: sends API requests (evidence: `README.md`)
- HTTP server → API handlers: routes requests (evidence: `internal/gateway/server.go`)
- API handlers → Authentication: checks identity (evidence: `internal/gateway/handlers.go`)
- API handlers → Limits and quotas: checks quotas (evidence: `internal/gateway/handlers.go`)
- HTTP server → Injection guardrails: installs middleware (evidence: `internal/gateway/server.go`)
- API handlers → Output DLP: masks output (evidence: `internal/gateway/handlers.go`)
- API handlers → Plugin framework: runs plugins (evidence: `internal/gateway/handlers.go`)
- API handlers → Alias routing: resolves aliases (evidence: `internal/gateway/handlers.go`)
- API handlers → Retry and failover: executes attempts (evidence: `internal/gateway/handlers.go`)
- Retry and failover → Circuit breaker: checks breaker (evidence: `internal/retry/executor.go`)
- Retry and failover → OpenAI adapter: invokes adapter
- Retry and failover → Anthropic adapter: invokes adapter
- OpenAI adapter → Model providers: calls provider
- Anthropic adapter → Model providers: calls provider
- API handlers → Usage records: records usage (evidence: `internal/gateway/handlers.go`)
- Usage records → SQLite usage store: persists records
- HTTP server → Key revocation: configures revocation
- HTTP server → Prometheus metrics: serves metrics (evidence: `internal/gateway/server.go`)
- HTTP server → OpenTelemetry tracing: enables tracing
- CLI user → gw CLI: runs commands (evidence: `README.md`)
- gw CLI → API handlers: calls gateway API (evidence: `README.md`)
- gw CLI → Agent REPL: starts REPL
- gw CLI → Task scheduler: manages schedules
