# praval2006/agentguard architecture

> Architecture diagram of the GitHub repository praval2006/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/praval2006/agentguard
- Repository: https://github.com/praval2006/agentguard

## Overview

AgentGuard is an acceptance-verification layer for AI-built changes. Its principal reviewed workflow proposes explicit and inferred behaviours, lets a human decide which inferred behaviours to accept, grounds the selected scenarios into supported checks, executes them, and deterministically reports evidence and verdicts. The Python backend is distinct from the React presentation: the web demo plays authored fixtures and does not invoke the backend. Edges reflect the README and source references shown; unsampled details are omitted where relationships cannot be established.

Main entry points: [`agentguard/acceptance.py`](https://github.com/praval2006/agentguard/blob/main/agentguard/acceptance.py) (Execution dispatcher), [`agentguard/reviewed_workflow.py`](https://github.com/praval2006/agentguard/blob/main/agentguard/reviewed_workflow.py) (Reviewed workflow), [`agentguard/grounding.py`](https://github.com/praval2006/agentguard/blob/main/agentguard/grounding.py) (Scenario grounding), [`frontend/src/App.tsx`](https://github.com/praval2006/agentguard/blob/main/frontend/src/App.tsx) (React app router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_review["Intent and review"]
  node_planner["Acceptance planner<br/>[planner.py]"]
  node_provider["OpenAI provider<br/>[openai_provider.py]"]
  node_review_flow["Reviewed workflow"]
  node_contract["Acceptance contract"]
  node_cli["CLI workflow<br/>[cli.py]"]
end

subgraph group_verify["Grounding and verification"]
  node_grounding["Scenario grounding<br/>[grounding.py]"]
  node_scenarios["Scenario validation<br/>[scenarios.py]"]
  node_derivations["Input derivation<br/>[derivations.py]"]
  node_acceptance["Execution dispatcher<br/>[acceptance.py]"]
  node_http["HTTP executor<br/>[http_execution.py]"]
  node_sequence["HTTP sequences"]
  node_tests["Trusted test executor<br/>[execution.py]"]
  node_registry["Registered checks<br/>[check_registry.py]"]
  node_coverage["Coverage authorization"]
  node_registered["Registered executor"]
  node_verifier["Deterministic verifier<br/>[verifier.py]"]
  node_report["Acceptance report"]
end

subgraph group_presentation["Web presentation"]
  node_app["React app router<br/>[App.tsx]"]
  node_presentation_page["Product presentation"]
  node_review_demo["Controlled review demo<br/>[ReviewDemo.tsx]"]
  node_demo_fixtures["Authored demo fixtures<br/>[accountDemoData.ts]"]
  node_demo_views["Evidence and correction views<br/>[EvidenceDetail.tsx]"]
end

node_user(("Task author"))
node_human(("Human reviewer"))
node_browser(("Web visitor"))

node_user -->|"provides task"| node_cli
node_cli -->|"starts reviewed flow"| node_review_flow
node_review_flow -->|"requests proposal"| node_planner
node_planner -.->|"requests reasoning"| node_provider
node_review_flow -->|"creates contract"| node_contract
node_human -->|"submits decisions"| node_review_flow
node_review_flow -->|"grounds selections"| node_grounding
node_grounding -->|"validates scenarios"| node_scenarios
node_grounding -->|"uses derivations"| node_derivations
node_review_flow -->|"runs verification"| node_acceptance
node_acceptance -->|"validates inputs"| node_scenarios
node_acceptance -->|"dispatches HTTP"| node_http
node_acceptance -->|"dispatches sequences"| node_sequence
node_acceptance -->|"dispatches tests"| node_tests
node_acceptance -->|"checks authorization"| node_coverage
node_coverage -->|"resolves checks"| node_registry
node_acceptance -->|"runs authorized check"| node_registered
node_acceptance -->|"evaluates observations"| node_verifier
node_acceptance -->|"projects outcome"| node_report
node_browser -->|"opens experience"| node_app
node_app -->|"routes presentation"| node_presentation_page
node_app -->|"routes demo"| node_review_demo
node_review_demo -->|"selects fixture"| node_demo_fixtures
node_review_demo -->|"renders evidence"| node_demo_views

click node_planner "https://github.com/praval2006/agentguard/blob/main/agentguard/planner.py"
click node_provider "https://github.com/praval2006/agentguard/blob/main/agentguard/providers/openai_provider.py"
click node_review_flow "https://github.com/praval2006/agentguard/blob/main/agentguard/reviewed_workflow.py"
click node_contract "https://github.com/praval2006/agentguard/blob/main/agentguard/acceptance_contract.py"
click node_cli "https://github.com/praval2006/agentguard/blob/main/agentguard/cli.py"
click node_grounding "https://github.com/praval2006/agentguard/blob/main/agentguard/grounding.py"
click node_scenarios "https://github.com/praval2006/agentguard/blob/main/agentguard/scenarios.py"
click node_derivations "https://github.com/praval2006/agentguard/blob/main/agentguard/derivations.py"
click node_acceptance "https://github.com/praval2006/agentguard/blob/main/agentguard/acceptance.py"
click node_http "https://github.com/praval2006/agentguard/blob/main/agentguard/http_execution.py"
click node_sequence "https://github.com/praval2006/agentguard/blob/main/agentguard/sequence_execution.py"
click node_tests "https://github.com/praval2006/agentguard/blob/main/agentguard/execution.py"
click node_registry "https://github.com/praval2006/agentguard/blob/main/agentguard/check_registry.py"
click node_coverage "https://github.com/praval2006/agentguard/blob/main/agentguard/coverage_authorization.py"
click node_registered "https://github.com/praval2006/agentguard/blob/main/agentguard/registered_execution.py"
click node_verifier "https://github.com/praval2006/agentguard/blob/main/agentguard/verifier.py"
click node_report "https://github.com/praval2006/agentguard/blob/main/agentguard/acceptance_report.py"
click node_app "https://github.com/praval2006/agentguard/blob/main/frontend/src/App.tsx"
click node_presentation_page "https://github.com/praval2006/agentguard/blob/main/frontend/src/PresentationPage.tsx"
click node_review_demo "https://github.com/praval2006/agentguard/blob/main/frontend/src/ReviewDemo.tsx"
click node_demo_fixtures "https://github.com/praval2006/agentguard/blob/main/frontend/src/accountDemoData.ts"
click node_demo_views "https://github.com/praval2006/agentguard/blob/main/frontend/src/EvidenceDetail.tsx"

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_planner,node_provider,node_review_flow,node_contract,node_cli,node_human toneBlue
class node_grounding,node_scenarios,node_derivations,node_acceptance,node_http,node_sequence,node_tests,node_registry,node_coverage,node_registered,node_verifier,node_report toneAmber
class node_app,node_presentation_page,node_review_demo,node_demo_fixtures,node_demo_views toneMint
class node_user toneRose
class node_browser toneIndigo
```

## Components

### Intent and review

- [Acceptance planner](https://github.com/praval2006/agentguard/blob/main/agentguard/planner.py): `agentguard/planner.py`
- [OpenAI provider](https://github.com/praval2006/agentguard/blob/main/agentguard/providers/openai_provider.py): `agentguard/providers/openai_provider.py`
- [Reviewed workflow](https://github.com/praval2006/agentguard/blob/main/agentguard/reviewed_workflow.py): `agentguard/reviewed_workflow.py`
- [Acceptance contract](https://github.com/praval2006/agentguard/blob/main/agentguard/acceptance_contract.py): `agentguard/acceptance_contract.py`
- [CLI workflow](https://github.com/praval2006/agentguard/blob/main/agentguard/cli.py): `agentguard/cli.py`

### Grounding and verification

- [Scenario grounding](https://github.com/praval2006/agentguard/blob/main/agentguard/grounding.py): `agentguard/grounding.py`
- [Scenario validation](https://github.com/praval2006/agentguard/blob/main/agentguard/scenarios.py): `agentguard/scenarios.py`
- [Input derivation](https://github.com/praval2006/agentguard/blob/main/agentguard/derivations.py): `agentguard/derivations.py`
- [Execution dispatcher](https://github.com/praval2006/agentguard/blob/main/agentguard/acceptance.py): `agentguard/acceptance.py`
- [HTTP executor](https://github.com/praval2006/agentguard/blob/main/agentguard/http_execution.py): `agentguard/http_execution.py`
- [HTTP sequences](https://github.com/praval2006/agentguard/blob/main/agentguard/sequence_execution.py): `agentguard/sequence_execution.py`
- [Trusted test executor](https://github.com/praval2006/agentguard/blob/main/agentguard/execution.py): `agentguard/execution.py`
- [Registered checks](https://github.com/praval2006/agentguard/blob/main/agentguard/check_registry.py): `agentguard/check_registry.py`
- [Coverage authorization](https://github.com/praval2006/agentguard/blob/main/agentguard/coverage_authorization.py): `agentguard/coverage_authorization.py`
- [Registered executor](https://github.com/praval2006/agentguard/blob/main/agentguard/registered_execution.py): `agentguard/registered_execution.py`
- [Deterministic verifier](https://github.com/praval2006/agentguard/blob/main/agentguard/verifier.py): `agentguard/verifier.py`
- [Acceptance report](https://github.com/praval2006/agentguard/blob/main/agentguard/acceptance_report.py): `agentguard/acceptance_report.py`

### Web presentation

- [React app router](https://github.com/praval2006/agentguard/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Product presentation](https://github.com/praval2006/agentguard/blob/main/frontend/src/PresentationPage.tsx): `frontend/src/PresentationPage.tsx`
- [Controlled review demo](https://github.com/praval2006/agentguard/blob/main/frontend/src/ReviewDemo.tsx): `frontend/src/ReviewDemo.tsx`
- [Authored demo fixtures](https://github.com/praval2006/agentguard/blob/main/frontend/src/accountDemoData.ts): `frontend/src/accountDemoData.ts`
- [Evidence and correction views](https://github.com/praval2006/agentguard/blob/main/frontend/src/EvidenceDetail.tsx): `frontend/src/EvidenceDetail.tsx`

### Other components

- **Task author**
- **Human reviewer**
- **Web visitor**

## Connections

- Task author → CLI workflow: provides task (evidence: `README.md`)
- CLI workflow → Reviewed workflow: starts reviewed flow (evidence: `README.md`)
- Reviewed workflow → Acceptance planner: requests proposal (evidence: `agentguard/reviewed_workflow.py`)
- Acceptance planner → OpenAI provider: requests reasoning (evidence: `README.md`)
- Reviewed workflow → Acceptance contract: creates contract (evidence: `agentguard/reviewed_workflow.py`)
- Human reviewer → Reviewed workflow: submits decisions (evidence: `README.md`)
- Reviewed workflow → Scenario grounding: grounds selections (evidence: `agentguard/reviewed_workflow.py`)
- Scenario grounding → Scenario validation: validates scenarios (evidence: `agentguard/grounding.py`)
- Scenario grounding → Input derivation: uses derivations (evidence: `agentguard/grounding.py`)
- Reviewed workflow → Execution dispatcher: runs verification (evidence: `agentguard/reviewed_workflow.py`)
- Execution dispatcher → Scenario validation: validates inputs (evidence: `agentguard/acceptance.py`)
- Execution dispatcher → HTTP executor: dispatches HTTP (evidence: `agentguard/acceptance.py`)
- Execution dispatcher → HTTP sequences: dispatches sequences (evidence: `agentguard/acceptance.py`)
- Execution dispatcher → Trusted test executor: dispatches tests (evidence: `agentguard/acceptance.py`)
- Execution dispatcher → Coverage authorization: checks authorization (evidence: `agentguard/acceptance.py`)
- Coverage authorization → Registered checks: resolves checks (evidence: `agentguard/coverage_authorization.py`)
- Execution dispatcher → Registered executor: runs authorized check (evidence: `agentguard/acceptance.py`)
- Execution dispatcher → Deterministic verifier: evaluates observations (evidence: `agentguard/acceptance.py`)
- Execution dispatcher → Acceptance report: projects outcome (evidence: `README.md`)
- Web visitor → React app router: opens experience (evidence: `frontend/src/App.tsx`)
- React app router → Product presentation: routes presentation (evidence: `frontend/src/App.tsx`)
- React app router → Controlled review demo: routes demo (evidence: `frontend/src/App.tsx`)
- Controlled review demo → Authored demo fixtures: selects fixture (evidence: `frontend/src/ReviewDemo.tsx`)
- Controlled review demo → Evidence and correction views: renders evidence (evidence: `frontend/src/ReviewDemo.tsx`)
