# rishankreddy12/proofgate architecture

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

- Interactive diagram: https://gitdiagram.com/rishankreddy12/proofgate
- Repository: https://github.com/rishankreddy12/proofgate

## Overview

ProofGate is an OpenAI-compatible, multi-tenant LLM gateway. Client requests enter through the public HTTP API, are authenticated and processed by an ordered policy pipeline, then routed to provider adapters; results and usage are returned and recorded. Separate branches provide embeddings, MCP governance, administration, and evidence-based cache/routing optimization. PostgreSQL, Redis, and ClickHouse serve distinct control-plane, coordination/cache, and telemetry roles. Some subsystem links reflect README-documented behavior because their implementation files were not sampled.

Main entry points: [`internal/app/pipeline.go`](https://github.com/rishankreddy12/proofgate/blob/main/internal/app/pipeline.go) (Stage Wiring), [`internal/server/routes.go`](https://github.com/rishankreddy12/proofgate/blob/main/internal/server/routes.go) (HTTP Routes), [`internal/pipeline/pipeline.go`](https://github.com/rishankreddy12/proofgate/blob/main/internal/pipeline/pipeline.go) (Stage Pipeline), [`internal/router/route.go`](https://github.com/rishankreddy12/proofgate/blob/main/internal/router/route.go) (Route Executor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["Gateway API"]
  node_routes["HTTP Routes<br/>[routes.go]"]
  node_chat["Chat Handler<br/>[chat.go]"]
  node_embeddings["Embeddings<br/>[embeddings.go]"]
  node_auth["API Authentication<br/>[middleware.go]"]
end

subgraph group_execution["Request Execution"]
  node_pipeline["Stage Pipeline<br/>[pipeline.go]"]
  node_pipelinewiring["Stage Wiring<br/>[pipeline.go]"]
  node_ratelimit["Rate Limits<br/>[limiter.go]"]
  node_budget["Tenant Budgets<br/>[budget.go]"]
  node_guard["Privacy Guardrails<br/>[stage.go]"]
  node_router["Route Executor<br/>[route.go]"]
  node_providers["Provider Adapters<br/>[gemini.go]"]
end

subgraph group_proof["Proof and Governance"]
  node_mcp["MCP Proxy<br/>[proxy.go]"]
  node_cache["Response Cache<br/>[stage.go]"]
  node_smartroute["Smart Routing<br/>[stage.go]"]
  node_proofjudge["Quality Judge<br/>[judge.go]"]
  node_agent["Agent Run Limits<br/>[runs.go]"]
end

subgraph group_operations["Control and Operations"]
  node_admincli["Admin CLI<br/>[main.go]"]
  node_adminsession["Admin Sessions<br/>[session.go]"]
  node_gatewaymain["Gateway Runtime<br/>[main.go]"]
end

subgraph group_state["State and Telemetry"]
  node_postgres[("PostgreSQL")]
  node_redis[("Redis")]
  node_clickhouse[("ClickHouse<br/>[clickhouse.go]")]
  node_metrics["Metrics<br/>[metrics.go]"]
end

node_client(("API Client"))

node_client -->|"sends requests"| node_routes
node_routes -->|"authenticates API"| node_auth
node_routes -->|"dispatches chat"| node_chat
node_routes -->|"dispatches embeddings"| node_embeddings
node_routes -->|"mounts proxy"| node_mcp
node_auth -->|"looks up keys"| node_postgres
node_chat -.->|"runs stages"| node_pipeline
node_pipelinewiring -->|"constructs stages"| node_pipeline
node_pipelinewiring -->|"registers stage"| node_ratelimit
node_pipelinewiring -->|"registers stage"| node_budget
node_pipelinewiring -->|"registers stage"| node_guard
node_pipelinewiring -->|"registers stage"| node_cache
node_pipelinewiring -->|"registers stage"| node_smartroute
node_pipelinewiring -->|"registers stage"| node_agent
node_pipeline -->|"dispatches requests"| node_router
node_router -->|"executes target"| node_providers
node_embeddings -->|"executes embedding"| node_router
node_ratelimit -.->|"coordinates limits"| node_redis
node_budget -.->|"reserves spend"| node_redis
node_cache -.->|"stores responses"| node_redis
node_smartroute -.->|"records quality evidence"| node_proofjudge
node_mcp -.->|"audits calls"| node_clickhouse
node_pipelinewiring -->|"registers stage"| node_metrics
node_metrics -.->|"records usage"| node_clickhouse
node_gatewaymain -.->|"builds pipeline"| node_pipelinewiring
node_gatewaymain -.->|"starts gateway"| node_routes
node_admincli -->|"manages records"| node_postgres
node_admincli -.->|"manages sessions"| node_adminsession
node_adminsession -->|"persists sessions"| node_postgres
node_agent -.->|"tracks run budgets"| node_redis

click node_routes "https://github.com/rishankreddy12/proofgate/blob/main/internal/server/routes.go"
click node_chat "https://github.com/rishankreddy12/proofgate/blob/main/internal/server/chat.go"
click node_embeddings "https://github.com/rishankreddy12/proofgate/blob/main/internal/server/embeddings.go"
click node_auth "https://github.com/rishankreddy12/proofgate/blob/main/internal/auth/middleware.go"
click node_admincli "https://github.com/rishankreddy12/proofgate/blob/main/cmd/proofgatectl/main.go"
click node_adminsession "https://github.com/rishankreddy12/proofgate/blob/main/internal/adminauth/session.go"
click node_mcp "https://github.com/rishankreddy12/proofgate/blob/main/internal/mcpproxy/proxy.go"
click node_pipeline "https://github.com/rishankreddy12/proofgate/blob/main/internal/pipeline/pipeline.go"
click node_pipelinewiring "https://github.com/rishankreddy12/proofgate/blob/main/internal/app/pipeline.go"
click node_ratelimit "https://github.com/rishankreddy12/proofgate/blob/main/internal/ratelimit/limiter.go"
click node_budget "https://github.com/rishankreddy12/proofgate/blob/main/internal/budget/budget.go"
click node_guard "https://github.com/rishankreddy12/proofgate/blob/main/internal/guard/stage.go"
click node_cache "https://github.com/rishankreddy12/proofgate/blob/main/internal/cache/stage.go"
click node_smartroute "https://github.com/rishankreddy12/proofgate/blob/main/internal/smartroute/stage.go"
click node_router "https://github.com/rishankreddy12/proofgate/blob/main/internal/router/route.go"
click node_providers "https://github.com/rishankreddy12/proofgate/blob/main/internal/provider/gemini.go"
click node_proofjudge "https://github.com/rishankreddy12/proofgate/blob/main/internal/proof/judge.go"
click node_agent "https://github.com/rishankreddy12/proofgate/blob/main/internal/agentrun/runs.go"
click node_clickhouse "https://github.com/rishankreddy12/proofgate/blob/main/internal/analytics/clickhouse.go"
click node_metrics "https://github.com/rishankreddy12/proofgate/blob/main/internal/telemetry/metrics.go"
click node_gatewaymain "https://github.com/rishankreddy12/proofgate/blob/main/cmd/proofgate/main.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_routes,node_chat,node_embeddings,node_auth,node_client toneBlue
class node_pipeline,node_pipelinewiring,node_ratelimit,node_budget,node_guard,node_router,node_providers toneAmber
class node_mcp,node_cache,node_smartroute,node_proofjudge,node_agent toneMint
class node_admincli,node_adminsession,node_gatewaymain toneRose
class node_postgres,node_redis,node_clickhouse,node_metrics toneIndigo
```

## Components

### Gateway API

- [HTTP Routes](https://github.com/rishankreddy12/proofgate/blob/main/internal/server/routes.go): `internal/server/routes.go`
- [Chat Handler](https://github.com/rishankreddy12/proofgate/blob/main/internal/server/chat.go): `internal/server/chat.go`
- [Embeddings](https://github.com/rishankreddy12/proofgate/blob/main/internal/server/embeddings.go): `internal/server/embeddings.go`
- [API Authentication](https://github.com/rishankreddy12/proofgate/blob/main/internal/auth/middleware.go): `internal/auth/middleware.go`

### Request Execution

- [Stage Pipeline](https://github.com/rishankreddy12/proofgate/blob/main/internal/pipeline/pipeline.go): `internal/pipeline/pipeline.go`
- [Stage Wiring](https://github.com/rishankreddy12/proofgate/blob/main/internal/app/pipeline.go): `internal/app/pipeline.go`
- [Rate Limits](https://github.com/rishankreddy12/proofgate/blob/main/internal/ratelimit/limiter.go): `internal/ratelimit/limiter.go`
- [Tenant Budgets](https://github.com/rishankreddy12/proofgate/blob/main/internal/budget/budget.go): `internal/budget/budget.go`
- [Privacy Guardrails](https://github.com/rishankreddy12/proofgate/blob/main/internal/guard/stage.go): `internal/guard/stage.go`
- [Route Executor](https://github.com/rishankreddy12/proofgate/blob/main/internal/router/route.go): `internal/router/route.go`
- [Provider Adapters](https://github.com/rishankreddy12/proofgate/blob/main/internal/provider/gemini.go): `internal/provider/gemini.go`

### Proof and Governance

- [MCP Proxy](https://github.com/rishankreddy12/proofgate/blob/main/internal/mcpproxy/proxy.go): `internal/mcpproxy/proxy.go`
- [Response Cache](https://github.com/rishankreddy12/proofgate/blob/main/internal/cache/stage.go): `internal/cache/stage.go`
- [Smart Routing](https://github.com/rishankreddy12/proofgate/blob/main/internal/smartroute/stage.go): `internal/smartroute/stage.go`
- [Quality Judge](https://github.com/rishankreddy12/proofgate/blob/main/internal/proof/judge.go): `internal/proof/judge.go`
- [Agent Run Limits](https://github.com/rishankreddy12/proofgate/blob/main/internal/agentrun/runs.go): `internal/agentrun/runs.go`

### Control and Operations

- [Admin CLI](https://github.com/rishankreddy12/proofgate/blob/main/cmd/proofgatectl/main.go): `cmd/proofgatectl/main.go`
- [Admin Sessions](https://github.com/rishankreddy12/proofgate/blob/main/internal/adminauth/session.go): `internal/adminauth/session.go`
- [Gateway Runtime](https://github.com/rishankreddy12/proofgate/blob/main/cmd/proofgate/main.go): `cmd/proofgate/main.go`

### State and Telemetry

- **PostgreSQL**
- **Redis**
- [ClickHouse](https://github.com/rishankreddy12/proofgate/blob/main/internal/analytics/clickhouse.go): `internal/analytics/clickhouse.go`
- [Metrics](https://github.com/rishankreddy12/proofgate/blob/main/internal/telemetry/metrics.go): `internal/telemetry/metrics.go`

### Other components

- **API Client**

## Connections

- API Client → HTTP Routes: sends requests (evidence: `internal/server/routes.go`)
- HTTP Routes → API Authentication: authenticates API (evidence: `internal/server/routes.go`)
- HTTP Routes → Chat Handler: dispatches chat (evidence: `internal/server/routes.go`)
- HTTP Routes → Embeddings: dispatches embeddings (evidence: `internal/server/routes.go`)
- HTTP Routes → MCP Proxy: mounts proxy (evidence: `internal/server/routes.go`)
- API Authentication → PostgreSQL: looks up keys (evidence: `internal/auth/middleware.go`)
- Chat Handler → Stage Pipeline: runs stages
- Stage Wiring → Stage Pipeline: constructs stages (evidence: `internal/app/pipeline.go`)
- Stage Wiring → Rate Limits: registers stage (evidence: `internal/app/pipeline.go`)
- Stage Wiring → Tenant Budgets: registers stage (evidence: `internal/app/pipeline.go`)
- Stage Wiring → Privacy Guardrails: registers stage (evidence: `internal/app/pipeline.go`)
- Stage Wiring → Response Cache: registers stage (evidence: `internal/app/pipeline.go`)
- Stage Wiring → Smart Routing: registers stage (evidence: `internal/app/pipeline.go`)
- Stage Wiring → Agent Run Limits: registers stage (evidence: `internal/app/pipeline.go`)
- Stage Pipeline → Route Executor: dispatches requests (evidence: `internal/pipeline/pipeline.go`)
- Route Executor → Provider Adapters: executes target (evidence: `README.md`)
- Embeddings → Route Executor: executes embedding (evidence: `internal/server/embeddings.go`)
- Rate Limits → Redis: coordinates limits (evidence: `README.md`)
- Tenant Budgets → Redis: reserves spend (evidence: `README.md`)
- Response Cache → Redis: stores responses (evidence: `README.md`)
- Smart Routing → Quality Judge: records quality evidence (evidence: `README.md`)
- MCP Proxy → ClickHouse: audits calls (evidence: `README.md`)
- Stage Wiring → Metrics: registers stage (evidence: `internal/app/pipeline.go`)
- Metrics → ClickHouse: records usage (evidence: `README.md`)
- Gateway Runtime → Stage Wiring: builds pipeline
- Gateway Runtime → HTTP Routes: starts gateway
- Admin CLI → PostgreSQL: manages records (evidence: `cmd/proofgatectl/main.go`)
- Admin CLI → Admin Sessions: manages sessions
- Admin Sessions → PostgreSQL: persists sessions (evidence: `internal/adminauth/session.go`)
- Agent Run Limits → Redis: tracks run budgets (evidence: `README.md`)
