# physics0070/actionproof architecture

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

- Interactive diagram: https://gitdiagram.com/physics0070/actionproof
- Repository: https://github.com/physics0070/actionproof

## Overview

ActionProof is an evidence-verified safety gateway for AI-agent writes. Its main workflow intercepts an MCP request, checks cited and derived claims, obtains a policy decision, then commits an approved action once and records the outcome. REVIEW requests branch to a human console; the README also documents a proxy, LangChain adapter, audit verification, and an evaluation harness. Some console and evaluation internals were not sampled, so those connections are shown only where documented.

Main entry points: [`src/actionproof/gate.py`](https://github.com/physics0070/actionproof/blob/main/src/actionproof/gate.py) (Action Gate), [`src/actionproof/server.py`](https://github.com/physics0070/actionproof/blob/main/src/actionproof/server.py) (MCP Server), [`src/actionproof/review.py`](https://github.com/physics0070/actionproof/blob/main/src/actionproof/review.py) (Review Workflow), [`src/actionproof/verify.py`](https://github.com/physics0070/actionproof/blob/main/src/actionproof/verify.py) (Claim Verification)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["Request Gateway"]
  node_mcp["MCP Server<br/>[server.py]"]
  node_contracts["Request Contracts<br/>[contracts.py]"]
  node_gate["Action Gate<br/>[gate.py]"]
end

subgraph group_assurance["Verification and Assurance"]
  node_extract["Document Extraction<br/>[extract.py]"]
  node_verify["Claim Verification<br/>[verify.py]"]
  node_policy["OPA Policy<br/>[policy.py]"]
  node_signing["Receipt Signing<br/>[signing.py]"]
  node_db[("PostgreSQL State<br/>[db.py]")]
  node_audit["Audit Chain<br/>[audit.py]"]
end

subgraph group_review["Human Review"]
  node_review["Review Workflow<br/>[review.py]"]
  node_console_api["Console API<br/>[console.py]"]
  node_console_ui["Review Console<br/>[RequestView.tsx]"]
  node_web_api["Web API Client<br/>[api.ts]"]
end

subgraph group_product["Integrations and Evaluation"]
  node_proxy["MCP Proxy<br/>[proxy.py]"]
  node_adapter["LangChain Adapter<br/>[langchain.py]"]
  node_site["Product Site<br/>[Story.tsx]"]
  node_eval_cases["Evaluation Cases<br/>[cases.py]"]
  node_eval_runner["Evaluation Harness<br/>[run.py]"]
end

node_agent(("AI Agent"))
node_opa["OPA Service"]

node_agent -->|"submits calls"| node_mcp
node_mcp -->|"parses request"| node_contracts
node_mcp -->|"prepares action"| node_gate
node_gate -->|"verifies claims"| node_verify
node_verify -->|"re-extracts evidence"| node_extract
node_gate -->|"requests decision"| node_policy
node_policy -->|"queries policy"| node_opa
node_gate -->|"signs receipts"| node_signing
node_gate -->|"rechecks and commits"| node_db
node_gate -->|"records outcomes"| node_audit
node_mcp -->|"parks review"| node_review
node_review -->|"stores review state"| node_db
node_review -->|"approves and commits"| node_gate
node_console_api -->|"decides review"| node_review
node_console_ui -->|"requests console data"| node_web_api
node_web_api -->|"calls console API"| node_console_api
node_mcp -->|"starts proxy mode"| node_proxy
node_adapter -->|"wraps tool actions"| node_gate
node_eval_runner -->|"loads cases"| node_eval_cases
node_site -.->|"explains product"| node_agent

click node_mcp "https://github.com/physics0070/actionproof/blob/main/src/actionproof/server.py"
click node_contracts "https://github.com/physics0070/actionproof/blob/main/src/actionproof/contracts.py"
click node_proxy "https://github.com/physics0070/actionproof/blob/main/src/actionproof/proxy.py"
click node_adapter "https://github.com/physics0070/actionproof/blob/main/src/actionproof/adapters/langchain.py"
click node_gate "https://github.com/physics0070/actionproof/blob/main/src/actionproof/gate.py"
click node_extract "https://github.com/physics0070/actionproof/blob/main/src/actionproof/extract.py"
click node_verify "https://github.com/physics0070/actionproof/blob/main/src/actionproof/verify.py"
click node_policy "https://github.com/physics0070/actionproof/blob/main/src/actionproof/policy.py"
click node_signing "https://github.com/physics0070/actionproof/blob/main/src/actionproof/signing.py"
click node_db "https://github.com/physics0070/actionproof/blob/main/src/actionproof/db.py"
click node_audit "https://github.com/physics0070/actionproof/blob/main/src/actionproof/audit.py"
click node_review "https://github.com/physics0070/actionproof/blob/main/src/actionproof/review.py"
click node_console_api "https://github.com/physics0070/actionproof/blob/main/src/actionproof/console.py"
click node_console_ui "https://github.com/physics0070/actionproof/blob/main/web/components/console/RequestView.tsx"
click node_web_api "https://github.com/physics0070/actionproof/blob/main/web/lib/api.ts"
click node_site "https://github.com/physics0070/actionproof/blob/main/web/components/site/Story.tsx"
click node_eval_cases "https://github.com/physics0070/actionproof/blob/main/eval/cases.py"
click node_eval_runner "https://github.com/physics0070/actionproof/blob/main/eval/run.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_mcp,node_contracts,node_gate toneBlue
class node_extract,node_verify,node_policy,node_signing,node_db,node_audit toneAmber
class node_review,node_console_api,node_console_ui,node_web_api toneMint
class node_proxy,node_adapter,node_site,node_eval_cases,node_eval_runner toneRose
class node_agent,node_opa toneIndigo
```

## Components

### Request Gateway

- [MCP Server](https://github.com/physics0070/actionproof/blob/main/src/actionproof/server.py): `src/actionproof/server.py`
- [Request Contracts](https://github.com/physics0070/actionproof/blob/main/src/actionproof/contracts.py): `src/actionproof/contracts.py`
- [Action Gate](https://github.com/physics0070/actionproof/blob/main/src/actionproof/gate.py): `src/actionproof/gate.py`

### Verification and Assurance

- [Document Extraction](https://github.com/physics0070/actionproof/blob/main/src/actionproof/extract.py): `src/actionproof/extract.py`
- [Claim Verification](https://github.com/physics0070/actionproof/blob/main/src/actionproof/verify.py): `src/actionproof/verify.py`
- [OPA Policy](https://github.com/physics0070/actionproof/blob/main/src/actionproof/policy.py): `src/actionproof/policy.py`
- [Receipt Signing](https://github.com/physics0070/actionproof/blob/main/src/actionproof/signing.py): `src/actionproof/signing.py`
- [PostgreSQL State](https://github.com/physics0070/actionproof/blob/main/src/actionproof/db.py): `src/actionproof/db.py`
- [Audit Chain](https://github.com/physics0070/actionproof/blob/main/src/actionproof/audit.py): `src/actionproof/audit.py`

### Human Review

- [Review Workflow](https://github.com/physics0070/actionproof/blob/main/src/actionproof/review.py): `src/actionproof/review.py`
- [Console API](https://github.com/physics0070/actionproof/blob/main/src/actionproof/console.py): `src/actionproof/console.py`
- [Review Console](https://github.com/physics0070/actionproof/blob/main/web/components/console/RequestView.tsx): `web/components/console/RequestView.tsx`
- [Web API Client](https://github.com/physics0070/actionproof/blob/main/web/lib/api.ts): `web/lib/api.ts`

### Integrations and Evaluation

- [MCP Proxy](https://github.com/physics0070/actionproof/blob/main/src/actionproof/proxy.py): `src/actionproof/proxy.py`
- [LangChain Adapter](https://github.com/physics0070/actionproof/blob/main/src/actionproof/adapters/langchain.py): `src/actionproof/adapters/langchain.py`
- [Product Site](https://github.com/physics0070/actionproof/blob/main/web/components/site/Story.tsx): `web/components/site/Story.tsx`
- [Evaluation Cases](https://github.com/physics0070/actionproof/blob/main/eval/cases.py): `eval/cases.py`
- [Evaluation Harness](https://github.com/physics0070/actionproof/blob/main/eval/run.py): `eval/run.py`

### Other components

- **AI Agent**
- **OPA Service**

## Connections

- AI Agent → MCP Server: submits calls (evidence: `README.md`)
- MCP Server → Request Contracts: parses request (evidence: `src/actionproof/server.py`)
- MCP Server → Action Gate: prepares action (evidence: `src/actionproof/server.py`)
- Action Gate → Claim Verification: verifies claims (evidence: `src/actionproof/gate.py`)
- Claim Verification → Document Extraction: re-extracts evidence (evidence: `src/actionproof/verify.py`)
- Action Gate → OPA Policy: requests decision (evidence: `src/actionproof/gate.py`)
- OPA Policy → OPA Service: queries policy (evidence: `README.md`)
- Action Gate → Receipt Signing: signs receipts (evidence: `src/actionproof/gate.py`)
- Action Gate → PostgreSQL State: rechecks and commits (evidence: `README.md`)
- Action Gate → Audit Chain: records outcomes (evidence: `src/actionproof/gate.py`)
- MCP Server → Review Workflow: parks review (evidence: `src/actionproof/server.py`)
- Review Workflow → PostgreSQL State: stores review state (evidence: `src/actionproof/review.py`)
- Review Workflow → Action Gate: approves and commits (evidence: `src/actionproof/review.py`)
- Console API → Review Workflow: decides review (evidence: `src/actionproof/review.py`)
- Review Console → Web API Client: requests console data
- Web API Client → Console API: calls console API (evidence: `README.md`)
- MCP Server → MCP Proxy: starts proxy mode (evidence: `src/actionproof/server.py`)
- LangChain Adapter → Action Gate: wraps tool actions (evidence: `src/actionproof/adapters/langchain.py`)
- Evaluation Harness → Evaluation Cases: loads cases
- Product Site → AI Agent: explains product (evidence: `README.md`)
