# sollutionsit/agentgate architecture

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

- Interactive diagram: https://gitdiagram.com/sollutionsit/agentgate
- Repository: https://github.com/sollutionsit/agentgate

## Overview

AgentGate is a zero-trust gateway for agent-to-agent requests. Agents call its API with a signed JWT and capability request; the gateway authenticates identity, applies rate limits, evaluates policy or a delegation, checks replay protection for sensitive actions, then returns a decision or forwards an allowed request to a fixed registered target. Delegation creation and validation are distinct authorization stages. Audit events and Prometheus metrics provide operational visibility; Redis stores quotas, nonces and grants. The README documents the local policy-regression and security labs, but their internal wiring is not fully shown.

Main entry points: [`src/agentgate/services/gateway.py`](https://github.com/sollutionsit/agentgate/blob/main/src/agentgate/services/gateway.py) (Gateway service), [`src/agentgate/api/routes.py`](https://github.com/sollutionsit/agentgate/blob/main/src/agentgate/api/routes.py) (HTTP routes), [`src/agentgate/main.py`](https://github.com/sollutionsit/agentgate/blob/main/src/agentgate/main.py) (App assembly), [`src/agentgate/authorization/engine.py`](https://github.com/sollutionsit/agentgate/blob/main/src/agentgate/authorization/engine.py) (Authorization engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and Runtime"]
  node_api_routes["HTTP routes<br/>[routes.py]"]
  node_api_dependencies["Request dependencies<br/>[dependencies.py]"]
  node_middleware["Body limit<br/>[middleware.py]"]
  node_app["App assembly<br/>[main.py]"]
  node_gateway["Gateway service<br/>[gateway.py]"]
  node_config["Runtime settings<br/>[config.py]"]
end

subgraph group_security["Identity and Security"]
  node_identity["Agent identity<br/>[identity.py]"]
  node_token_verifier["JWT verifier<br/>[jwt.py]"]
  node_rate_limiter["Rate limiter<br/>[rate_limit.py]"]
  node_replay_guard["Replay guard<br/>[replay.py]"]
  node_delegations["Delegation grants<br/>[delegation.py]"]
end

subgraph group_authorization["Authorization"]
  node_auth_engine["Authorization engine<br/>[engine.py]"]
  node_capabilities["Capability registry<br/>[models.py]"]
  node_request_models["Request models<br/>[requests.py]"]
  node_decision_models["Decision models<br/>[decisions.py]"]
  node_policy_client["OPA client<br/>[client.py]"]
  node_rego["Rego rules<br/>[agentgate.rego]"]
end

subgraph group_operations["State and Observability"]
  node_redis[("Redis security state")]
  node_audit["Audit logger<br/>[logger.py]"]
  node_metrics["Prometheus metrics<br/>[metrics.py]"]
end

subgraph group_tools["Policy and Lab Tools"]
  node_cli["AgentGate CLI<br/>[cli.py]"]
  node_policy_loader["Policy regression<br/>[loader.py]"]
  node_lab["Security lab<br/>[lab.py]"]
end

node_agent(("Calling agent"))
node_targets["Registered workloads"]
node_opa["OPA policy service"]

node_agent -->|"sends requests"| node_api_routes
node_app -->|"registers routes"| node_api_routes
node_app -->|"adds middleware"| node_middleware
node_api_routes -->|"invokes services"| node_gateway
node_api_routes -->|"uses dependencies"| node_api_dependencies
node_api_dependencies -->|"provides service"| node_gateway
node_app -->|"assembles"| node_gateway
node_app -->|"loads settings"| node_config
node_gateway -->|"verifies tokens"| node_token_verifier
node_token_verifier -->|"creates identity"| node_identity
node_gateway -->|"checks quota"| node_rate_limiter
node_gateway -->|"evaluates access"| node_auth_engine
node_auth_engine -->|"checks capability"| node_capabilities
node_auth_engine -->|"evaluates policy"| node_policy_client
node_policy_client -->|"posts evaluation"| node_opa
node_opa -->|"evaluates rules"| node_rego
node_gateway -->|"creates or validates"| node_delegations
node_delegations -->|"checks grant policy"| node_auth_engine
node_gateway -->|"consumes nonce"| node_replay_guard
node_gateway -->|"forwards allowed calls"| node_targets
node_gateway -->|"uses security state"| node_redis
node_delegations -->|"stores and reads grants"| node_redis
node_gateway -->|"records events"| node_audit
node_gateway -->|"updates counters"| node_metrics
node_policy_client -->|"records latency"| node_metrics
node_api_routes -->|"returns decisions"| node_decision_models
node_api_routes -->|"accepts requests"| node_request_models
node_cli -->|"runs policy checks"| node_policy_loader
node_agent -.->|"runs local lab"| node_cli

click node_api_routes "https://github.com/sollutionsit/agentgate/blob/main/src/agentgate/api/routes.py"
click node_api_dependencies "https://github.com/sollutionsit/agentgate/blob/main/src/agentgate/api/dependencies.py"
click node_middleware "https://github.com/sollutionsit/agentgate/blob/main/src/agentgate/api/middleware.py"
click node_app "https://github.com/sollutionsit/agentgate/blob/main/src/agentgate/main.py"
click node_gateway "https://github.com/sollutionsit/agentgate/blob/main/src/agentgate/services/gateway.py"
click node_identity "https://github.com/sollutionsit/agentgate/blob/main/src/agentgate/auth/identity.py"
click node_token_verifier "https://github.com/sollutionsit/agentgate/blob/main/src/agentgate/auth/jwt.py"
click node_rate_limiter "https://github.com/sollutionsit/agentgate/blob/main/src/agentgate/security/rate_limit.py"
click node_replay_guard "https://github.com/sollutionsit/agentgate/blob/main/src/agentgate/security/replay.py"
click node_delegations "https://github.com/sollutionsit/agentgate/blob/main/src/agentgate/security/delegation.py"
click node_auth_engine "https://github.com/sollutionsit/agentgate/blob/main/src/agentgate/authorization/engine.py"
click node_capabilities "https://github.com/sollutionsit/agentgate/blob/main/src/agentgate/authorization/models.py"
click node_request_models "https://github.com/sollutionsit/agentgate/blob/main/src/agentgate/domain/requests.py"
click node_decision_models "https://github.com/sollutionsit/agentgate/blob/main/src/agentgate/domain/decisions.py"
click node_policy_client "https://github.com/sollutionsit/agentgate/blob/main/src/agentgate/policy/client.py"
click node_rego "https://github.com/sollutionsit/agentgate/blob/main/policies/agentgate.rego"
click node_audit "https://github.com/sollutionsit/agentgate/blob/main/src/agentgate/audit/logger.py"
click node_metrics "https://github.com/sollutionsit/agentgate/blob/main/src/agentgate/telemetry/metrics.py"
click node_config "https://github.com/sollutionsit/agentgate/blob/main/src/agentgate/config.py"
click node_cli "https://github.com/sollutionsit/agentgate/blob/main/src/agentgate/cli.py"
click node_policy_loader "https://github.com/sollutionsit/agentgate/blob/main/src/agentgate/policy/loader.py"
click node_lab "https://github.com/sollutionsit/agentgate/blob/main/src/agentgate/lab.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_api_routes,node_api_dependencies,node_middleware,node_app,node_gateway,node_config toneBlue
class node_identity,node_token_verifier,node_rate_limiter,node_replay_guard,node_delegations toneAmber
class node_auth_engine,node_capabilities,node_request_models,node_decision_models,node_policy_client,node_rego toneMint
class node_redis,node_audit,node_metrics toneRose
class node_cli,node_policy_loader,node_lab,node_agent,node_targets,node_opa toneIndigo
```

## Components

### API and Runtime

- [HTTP routes](https://github.com/sollutionsit/agentgate/blob/main/src/agentgate/api/routes.py): `src/agentgate/api/routes.py`
- [Request dependencies](https://github.com/sollutionsit/agentgate/blob/main/src/agentgate/api/dependencies.py): `src/agentgate/api/dependencies.py`
- [Body limit](https://github.com/sollutionsit/agentgate/blob/main/src/agentgate/api/middleware.py): `src/agentgate/api/middleware.py`
- [App assembly](https://github.com/sollutionsit/agentgate/blob/main/src/agentgate/main.py): `src/agentgate/main.py`
- [Gateway service](https://github.com/sollutionsit/agentgate/blob/main/src/agentgate/services/gateway.py): `src/agentgate/services/gateway.py`
- [Runtime settings](https://github.com/sollutionsit/agentgate/blob/main/src/agentgate/config.py): `src/agentgate/config.py`

### Identity and Security

- [Agent identity](https://github.com/sollutionsit/agentgate/blob/main/src/agentgate/auth/identity.py): `src/agentgate/auth/identity.py`
- [JWT verifier](https://github.com/sollutionsit/agentgate/blob/main/src/agentgate/auth/jwt.py): `src/agentgate/auth/jwt.py`
- [Rate limiter](https://github.com/sollutionsit/agentgate/blob/main/src/agentgate/security/rate_limit.py): `src/agentgate/security/rate_limit.py`
- [Replay guard](https://github.com/sollutionsit/agentgate/blob/main/src/agentgate/security/replay.py): `src/agentgate/security/replay.py`
- [Delegation grants](https://github.com/sollutionsit/agentgate/blob/main/src/agentgate/security/delegation.py): `src/agentgate/security/delegation.py`

### Authorization

- [Authorization engine](https://github.com/sollutionsit/agentgate/blob/main/src/agentgate/authorization/engine.py): `src/agentgate/authorization/engine.py`
- [Capability registry](https://github.com/sollutionsit/agentgate/blob/main/src/agentgate/authorization/models.py): `src/agentgate/authorization/models.py`
- [Request models](https://github.com/sollutionsit/agentgate/blob/main/src/agentgate/domain/requests.py): `src/agentgate/domain/requests.py`
- [Decision models](https://github.com/sollutionsit/agentgate/blob/main/src/agentgate/domain/decisions.py): `src/agentgate/domain/decisions.py`
- [OPA client](https://github.com/sollutionsit/agentgate/blob/main/src/agentgate/policy/client.py): `src/agentgate/policy/client.py`
- [Rego rules](https://github.com/sollutionsit/agentgate/blob/main/policies/agentgate.rego): `policies/agentgate.rego`

### State and Observability

- **Redis security state**
- [Audit logger](https://github.com/sollutionsit/agentgate/blob/main/src/agentgate/audit/logger.py): `src/agentgate/audit/logger.py`
- [Prometheus metrics](https://github.com/sollutionsit/agentgate/blob/main/src/agentgate/telemetry/metrics.py): `src/agentgate/telemetry/metrics.py`

### Policy and Lab Tools

- [AgentGate CLI](https://github.com/sollutionsit/agentgate/blob/main/src/agentgate/cli.py): `src/agentgate/cli.py`
- [Policy regression](https://github.com/sollutionsit/agentgate/blob/main/src/agentgate/policy/loader.py): `src/agentgate/policy/loader.py`
- [Security lab](https://github.com/sollutionsit/agentgate/blob/main/src/agentgate/lab.py): `src/agentgate/lab.py`

### Other components

- **Calling agent**
- **Registered workloads**
- **OPA policy service**

## Connections

- Calling agent → HTTP routes: sends requests (evidence: `README.md`)
- App assembly → HTTP routes: registers routes (evidence: `src/agentgate/main.py`)
- App assembly → Body limit: adds middleware (evidence: `src/agentgate/main.py`)
- HTTP routes → Gateway service: invokes services (evidence: `src/agentgate/api/routes.py`)
- HTTP routes → Request dependencies: uses dependencies (evidence: `src/agentgate/api/routes.py`)
- Request dependencies → Gateway service: provides service (evidence: `src/agentgate/api/dependencies.py`)
- App assembly → Gateway service: assembles (evidence: `src/agentgate/main.py`)
- App assembly → Runtime settings: loads settings (evidence: `src/agentgate/main.py`)
- Gateway service → JWT verifier: verifies tokens (evidence: `src/agentgate/services/gateway.py`)
- JWT verifier → Agent identity: creates identity (evidence: `src/agentgate/auth/jwt.py`)
- Gateway service → Rate limiter: checks quota (evidence: `src/agentgate/services/gateway.py`)
- Gateway service → Authorization engine: evaluates access (evidence: `src/agentgate/services/gateway.py`)
- Authorization engine → Capability registry: checks capability (evidence: `src/agentgate/authorization/engine.py`)
- Authorization engine → OPA client: evaluates policy (evidence: `src/agentgate/authorization/engine.py`)
- OPA client → OPA policy service: posts evaluation (evidence: `src/agentgate/policy/client.py`)
- OPA policy service → Rego rules: evaluates rules (evidence: `README.md`)
- Gateway service → Delegation grants: creates or validates (evidence: `src/agentgate/services/gateway.py`)
- Delegation grants → Authorization engine: checks grant policy (evidence: `src/agentgate/security/delegation.py`)
- Gateway service → Replay guard: consumes nonce (evidence: `src/agentgate/services/gateway.py`)
- Gateway service → Registered workloads: forwards allowed calls (evidence: `src/agentgate/services/gateway.py`)
- Gateway service → Redis security state: uses security state (evidence: `README.md`)
- Delegation grants → Redis security state: stores and reads grants (evidence: `src/agentgate/security/delegation.py`)
- Gateway service → Audit logger: records events (evidence: `src/agentgate/services/gateway.py`)
- Gateway service → Prometheus metrics: updates counters (evidence: `src/agentgate/services/gateway.py`)
- OPA client → Prometheus metrics: records latency (evidence: `src/agentgate/policy/client.py`)
- HTTP routes → Decision models: returns decisions (evidence: `src/agentgate/api/routes.py`)
- HTTP routes → Request models: accepts requests (evidence: `src/agentgate/api/routes.py`)
- AgentGate CLI → Policy regression: runs policy checks (evidence: `src/agentgate/cli.py`)
- Calling agent → AgentGate CLI: runs local lab (evidence: `README.md`)
