# hariprasath-dlh/agentguard architecture

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

- Interactive diagram: https://gitdiagram.com/hariprasath-dlh/agentguard
- Repository: https://github.com/hariprasath-dlh/agentguard

## Overview

AgentGuard is a runtime governance control plane: agents submit proposed tool calls through an HTTP API, which authenticates the caller and evaluates governance controls before returning ALLOW, DENY, or PENDING. The Python SDK wraps this decision boundary; the web dashboard supports administration, audit, and human approval. The README documents the major capabilities, while source excerpts confirm API registration, persistence setup, authentication, policy evaluation, and SDK structure. Several route and frontend connections are documented rather than verified in sampled implementation.

Main entry points: [`backend/app/main.py`](https://github.com/hariprasath-dlh/agentguard/blob/main/backend/app/main.py) (FastAPI service), [`backend/app/services/policy_engine.py`](https://github.com/hariprasath-dlh/agentguard/blob/main/backend/app/services/policy_engine.py) (Policy evaluation), [`backend/app/api/hitl.py`](https://github.com/hariprasath-dlh/agentguard/blob/main/backend/app/api/hitl.py) (Human approvals), [`backend/app/api/auth.py`](https://github.com/hariprasath-dlh/agentguard/blob/main/backend/app/api/auth.py) (Authentication API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sdk["Agent SDK"]
  node_sdk_client["SDK client<br/>[client.py]"]
  node_sdk_guard["Dispatch guard<br/>[guard.py]"]
end

subgraph group_backend["Governance API"]
  node_api["FastAPI service<br/>[main.py]"]
  node_auth_api["Authentication API<br/>[auth.py]"]
  node_identity["Identity checks<br/>[deps.py]"]
  node_agents_api["Agent registry API<br/>[agents.py]"]
  node_guard_api["Guard endpoint<br/>[guard.py]"]
  node_policy["Policy evaluation<br/>[policy_engine.py]"]
  node_budgets["Budget controls<br/>[budget_guard.py]"]
  node_rate_limit["Rate limiting<br/>[rate_limiter.py]"]
  node_hitl["Human approvals<br/>[hitl.py]"]
  node_audit_api["Audit API<br/>[audit.py]"]
  node_dashboard_api["Dashboard API<br/>[dashboard.py]"]
end

subgraph group_control["Control Plane"]
  node_web["Admin dashboard<br/>[dashboard.tsx]"]
  node_web_auth["Web authentication<br/>[auth.tsx]"]
  node_web_api["Web API client<br/>[api.ts]"]
end

subgraph group_data["State and Audit"]
  node_db[("PostgreSQL<br/>[database.py]")]
  node_vault["Audit vault<br/>[audit_vault.py]"]
  node_redis[("Redis<br/>[redis.py]")]
end

node_agent(("AI agent"))
node_tool["External tools"]
node_reviewer(("Administrator / reviewer"))

node_agent -->|"proposes call"| node_sdk_client
node_sdk_client -->|"wraps dispatch"| node_sdk_guard
node_sdk_guard -->|"requests decision"| node_api
node_api -->|"allows execution"| node_tool
node_api -->|"routes requests"| node_auth_api
node_api -->|"routes requests"| node_agents_api
node_api -->|"routes requests"| node_guard_api
node_api -->|"routes requests"| node_hitl
node_api -->|"routes requests"| node_audit_api
node_api -->|"routes requests"| node_dashboard_api
node_auth_api -->|"uses identity checks"| node_identity
node_identity -->|"loads identity"| node_db
node_guard_api -.->|"authenticates caller"| node_identity
node_guard_api -.->|"evaluates request"| node_policy
node_policy -.->|"checks spend"| node_budgets
node_policy -.->|"checks limits"| node_rate_limit
node_policy -->|"can require approval"| node_hitl
node_hitl -->|"records decision"| node_vault
node_audit_api -.->|"verifies audit chain"| node_vault
node_web -.->|"loads dashboard data"| node_web_api
node_web_api -.->|"requests dashboard"| node_dashboard_api
node_web_auth -->|"uses API client"| node_web_api
node_reviewer -->|"reviews governance"| node_web
node_reviewer -->|"approves pending calls"| node_hitl
node_api -->|"uses sessions"| node_db
node_auth_api -->|"OAuth state storage"| node_redis

click node_sdk_client "https://github.com/hariprasath-dlh/agentguard/blob/main/sdk/agentguard/client.py"
click node_sdk_guard "https://github.com/hariprasath-dlh/agentguard/blob/main/sdk/agentguard/guard.py"
click node_api "https://github.com/hariprasath-dlh/agentguard/blob/main/backend/app/main.py"
click node_auth_api "https://github.com/hariprasath-dlh/agentguard/blob/main/backend/app/api/auth.py"
click node_identity "https://github.com/hariprasath-dlh/agentguard/blob/main/backend/app/security/deps.py"
click node_agents_api "https://github.com/hariprasath-dlh/agentguard/blob/main/backend/app/api/agents.py"
click node_guard_api "https://github.com/hariprasath-dlh/agentguard/blob/main/backend/app/api/guard.py"
click node_policy "https://github.com/hariprasath-dlh/agentguard/blob/main/backend/app/services/policy_engine.py"
click node_budgets "https://github.com/hariprasath-dlh/agentguard/blob/main/backend/app/services/budget_guard.py"
click node_rate_limit "https://github.com/hariprasath-dlh/agentguard/blob/main/backend/app/services/rate_limiter.py"
click node_hitl "https://github.com/hariprasath-dlh/agentguard/blob/main/backend/app/api/hitl.py"
click node_audit_api "https://github.com/hariprasath-dlh/agentguard/blob/main/backend/app/api/audit.py"
click node_dashboard_api "https://github.com/hariprasath-dlh/agentguard/blob/main/backend/app/api/dashboard.py"
click node_web "https://github.com/hariprasath-dlh/agentguard/blob/main/frontend/src/routes/dashboard.tsx"
click node_web_auth "https://github.com/hariprasath-dlh/agentguard/blob/main/frontend/src/lib/auth.tsx"
click node_web_api "https://github.com/hariprasath-dlh/agentguard/blob/main/frontend/src/lib/api.ts"
click node_db "https://github.com/hariprasath-dlh/agentguard/blob/main/backend/app/core/database.py"
click node_vault "https://github.com/hariprasath-dlh/agentguard/blob/main/backend/app/services/audit_vault.py"
click node_redis "https://github.com/hariprasath-dlh/agentguard/blob/main/backend/app/core/redis.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_sdk_client,node_sdk_guard,node_reviewer toneBlue
class node_api,node_auth_api,node_identity,node_agents_api,node_guard_api,node_policy,node_budgets,node_rate_limit,node_hitl,node_audit_api,node_dashboard_api toneAmber
class node_web,node_web_auth,node_web_api toneMint
class node_db,node_vault,node_redis toneRose
class node_agent,node_tool toneIndigo
```

## Components

### Agent SDK

- [SDK client](https://github.com/hariprasath-dlh/agentguard/blob/main/sdk/agentguard/client.py): `sdk/agentguard/client.py`
- [Dispatch guard](https://github.com/hariprasath-dlh/agentguard/blob/main/sdk/agentguard/guard.py): `sdk/agentguard/guard.py`

### Governance API

- [FastAPI service](https://github.com/hariprasath-dlh/agentguard/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication API](https://github.com/hariprasath-dlh/agentguard/blob/main/backend/app/api/auth.py): `backend/app/api/auth.py`
- [Identity checks](https://github.com/hariprasath-dlh/agentguard/blob/main/backend/app/security/deps.py): `backend/app/security/deps.py`
- [Agent registry API](https://github.com/hariprasath-dlh/agentguard/blob/main/backend/app/api/agents.py): `backend/app/api/agents.py`
- [Guard endpoint](https://github.com/hariprasath-dlh/agentguard/blob/main/backend/app/api/guard.py): `backend/app/api/guard.py`
- [Policy evaluation](https://github.com/hariprasath-dlh/agentguard/blob/main/backend/app/services/policy_engine.py): `backend/app/services/policy_engine.py`
- [Budget controls](https://github.com/hariprasath-dlh/agentguard/blob/main/backend/app/services/budget_guard.py): `backend/app/services/budget_guard.py`
- [Rate limiting](https://github.com/hariprasath-dlh/agentguard/blob/main/backend/app/services/rate_limiter.py): `backend/app/services/rate_limiter.py`
- [Human approvals](https://github.com/hariprasath-dlh/agentguard/blob/main/backend/app/api/hitl.py): `backend/app/api/hitl.py`
- [Audit API](https://github.com/hariprasath-dlh/agentguard/blob/main/backend/app/api/audit.py): `backend/app/api/audit.py`
- [Dashboard API](https://github.com/hariprasath-dlh/agentguard/blob/main/backend/app/api/dashboard.py): `backend/app/api/dashboard.py`

### Control Plane

- [Admin dashboard](https://github.com/hariprasath-dlh/agentguard/blob/main/frontend/src/routes/dashboard.tsx): `frontend/src/routes/dashboard.tsx`
- [Web authentication](https://github.com/hariprasath-dlh/agentguard/blob/main/frontend/src/lib/auth.tsx): `frontend/src/lib/auth.tsx`
- [Web API client](https://github.com/hariprasath-dlh/agentguard/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### State and Audit

- [PostgreSQL](https://github.com/hariprasath-dlh/agentguard/blob/main/backend/app/core/database.py): `backend/app/core/database.py`
- [Audit vault](https://github.com/hariprasath-dlh/agentguard/blob/main/backend/app/services/audit_vault.py): `backend/app/services/audit_vault.py`
- [Redis](https://github.com/hariprasath-dlh/agentguard/blob/main/backend/app/core/redis.py): `backend/app/core/redis.py`

### Other components

- **AI agent**
- **External tools**
- **Administrator / reviewer**

## Connections

- AI agent → SDK client: proposes call (evidence: `README.md`)
- SDK client → Dispatch guard: wraps dispatch (evidence: `sdk/agentguard/client.py`)
- Dispatch guard → FastAPI service: requests decision (evidence: `README.md`)
- FastAPI service → External tools: allows execution (evidence: `README.md`)
- FastAPI service → Authentication API: routes requests (evidence: `backend/app/main.py`)
- FastAPI service → Agent registry API: routes requests (evidence: `backend/app/main.py`)
- FastAPI service → Guard endpoint: routes requests (evidence: `backend/app/main.py`)
- FastAPI service → Human approvals: routes requests (evidence: `backend/app/main.py`)
- FastAPI service → Audit API: routes requests (evidence: `backend/app/main.py`)
- FastAPI service → Dashboard API: routes requests (evidence: `backend/app/main.py`)
- Authentication API → Identity checks: uses identity checks (evidence: `backend/app/api/auth.py`)
- Identity checks → PostgreSQL: loads identity (evidence: `backend/app/security/deps.py`)
- Guard endpoint → Identity checks: authenticates caller
- Guard endpoint → Policy evaluation: evaluates request
- Policy evaluation → Budget controls: checks spend
- Policy evaluation → Rate limiting: checks limits
- Policy evaluation → Human approvals: can require approval (evidence: `README.md`)
- Human approvals → Audit vault: records decision (evidence: `backend/app/api/hitl.py`)
- Audit API → Audit vault: verifies audit chain
- Admin dashboard → Web API client: loads dashboard data
- Web API client → Dashboard API: requests dashboard
- Web authentication → Web API client: uses API client (evidence: `frontend/src/lib/auth.tsx`)
- Administrator / reviewer → Admin dashboard: reviews governance (evidence: `README.md`)
- Administrator / reviewer → Human approvals: approves pending calls (evidence: `README.md`)
- FastAPI service → PostgreSQL: uses sessions (evidence: `backend/app/core/database.py`)
- Authentication API → Redis: OAuth state storage
