# dineshkumar2006471/agentproof architecture

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

- Interactive diagram: https://gitdiagram.com/dineshkumar2006471/agentproof
- Repository: https://github.com/dineshkumar2006471/agentproof

## Overview

AgentProof registers deployed AI agents, turns their stated promises into versioned contracts and scenario tests, then runs verification asynchronously against the live endpoint and records explainable evidence for private or shareable reports. The graph includes the documented AWS queue/worker architecture and major billing, authentication, public-verification, and operator surfaces. Source excerpts confirm agent registration, run orchestration, contract drafting, and checkout; links for unsampled capability routes follow README-level documentation rather than inspected implementations.

Main entry points: [`src/lib/aws/dynamodb.ts`](https://github.com/dineshkumar2006471/agentproof/blob/main/src/lib/aws/dynamodb.ts) (DynamoDB records), [`src/app/agents/layout.tsx`](https://github.com/dineshkumar2006471/agentproof/blob/main/src/app/agents/layout.tsx) (Agent workspace), [`workers/test-runner-worker/handler.ts`](https://github.com/dineshkumar2006471/agentproof/blob/main/workers/test-runner-worker/handler.ts) (Verification worker), [`src/app/api/runs/[id]/route.ts`](https://github.com/dineshkumar2006471/agentproof/blob/main/src/app/api/runs/%5Bid%5D/route.ts) (Run and export APIs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_product["Workspace and API"]
  node_workspace["Agent workspace<br/>[layout.tsx]"]
  node_agent_api["Agent registry API<br/>[route.ts]"]
  node_agent_detail_api["Agent detail API<br/>[route.ts]"]
end

subgraph group_verification["Verification lifecycle"]
  node_contract_draft["Contract drafting API<br/>[route.ts]"]
  node_contract_api["Contract API<br/>[route.ts]"]
  node_contract_engine["Contract engine<br/>[contract-engine.ts]"]
  node_test_generation["Test generation API<br/>[route.ts]"]
  node_test_generator["Scenario generator<br/>[test-generator.ts]"]
  node_run_api["Run orchestration API<br/>[route.ts]"]
  node_worker["Verification worker<br/>[handler.ts]"]
  node_semantic_judge["Semantic evaluation<br/>[semantic-judge.ts]"]
  node_run_api_read["Run and export APIs<br/>[route.ts]"]
  node_report_ui["Run report view<br/>[page.tsx]"]
  node_public_report["Public report surface<br/>[page.tsx]"]
  node_public_verify_api["Public verification API<br/>[route.ts]"]
end

subgraph group_platform["Platform services"]
  node_queue["Amazon SQS"]
  node_dynamodb[("DynamoDB records<br/>[dynamodb.ts]")]
  node_s3[("Report artifacts<br/>[s3.ts]")]
  node_auth["Cognito authentication<br/>[cognito.ts]"]
  node_auth_api["Authentication routes<br/>[route.ts]"]
end

subgraph group_commercial["Plans and operations"]
  node_billing_api["Checkout API<br/>[route.ts]"]
  node_payments["Dodo Payments<br/>[dodo.ts]"]
  node_billing_webhook["Payment webhook<br/>[route.ts]"]
  node_founder_metrics["Operator metrics<br/>[founder.ts]"]
end

node_browser(("Browser / user"))
node_target_agent["Deployed agent endpoint"]

node_browser -->|"uses"| node_workspace
node_workspace -->|"registers agents"| node_agent_api
node_workspace -->|"manages agents"| node_agent_detail_api
node_agent_api -->|"reads/writes agents"| node_dynamodb
node_agent_detail_api -->|"reads/writes contracts"| node_dynamodb
node_workspace -->|"requests draft"| node_contract_draft
node_contract_draft -->|"drafts contract"| node_contract_engine
node_contract_engine -->|"returns contract data"| node_dynamodb
node_contract_api -->|"stores contract"| node_dynamodb
node_workspace -->|"generates tests"| node_test_generation
node_test_generation -->|"creates scenarios"| node_test_generator
node_test_generator -->|"stores test matrix"| node_dynamodb
node_workspace -->|"starts verification"| node_run_api
node_run_api -->|"loads inputs, records run"| node_dynamodb
node_run_api -->|"enqueues run"| node_queue
node_queue -->|"dispatches job"| node_worker
node_worker -->|"posts scenarios"| node_target_agent
node_worker -->|"evaluates responses"| node_semantic_judge
node_worker -->|"records evidence and score"| node_dynamodb
node_worker -.->|"stores report artifacts"| node_s3
node_workspace -->|"reviews or exports"| node_run_api_read
node_run_api_read -->|"reads run evidence"| node_dynamodb
node_run_api_read -.->|"reads artifacts"| node_s3
node_report_ui -->|"loads report data"| node_run_api_read
node_browser -->|"views shared report"| node_public_report
node_public_report -->|"loads verification"| node_public_verify_api
node_public_verify_api -->|"reads public evidence"| node_dynamodb
node_workspace -->|"signs in"| node_auth_api
node_auth_api -->|"authenticates"| node_auth
node_browser -->|"starts checkout"| node_billing_api
node_billing_api -->|"creates checkout"| node_payments
node_payments -->|"sends payment event"| node_billing_webhook
node_billing_webhook -->|"updates plan state"| node_dynamodb
node_founder_metrics -->|"reads aggregate signals"| node_dynamodb

click node_workspace "https://github.com/dineshkumar2006471/agentproof/blob/main/src/app/agents/layout.tsx"
click node_agent_api "https://github.com/dineshkumar2006471/agentproof/blob/main/src/app/api/agents/route.ts"
click node_agent_detail_api "https://github.com/dineshkumar2006471/agentproof/blob/main/src/app/api/agents/%5Bid%5D/route.ts"
click node_contract_draft "https://github.com/dineshkumar2006471/agentproof/blob/main/src/app/api/agents/%5Bid%5D/contract/draft/route.ts"
click node_contract_api "https://github.com/dineshkumar2006471/agentproof/blob/main/src/app/api/agents/%5Bid%5D/contract/route.ts"
click node_contract_engine "https://github.com/dineshkumar2006471/agentproof/blob/main/src/lib/openai/contract-engine.ts"
click node_test_generation "https://github.com/dineshkumar2006471/agentproof/blob/main/src/app/api/agents/%5Bid%5D/generate-tests/route.ts"
click node_test_generator "https://github.com/dineshkumar2006471/agentproof/blob/main/src/lib/openai/test-generator.ts"
click node_run_api "https://github.com/dineshkumar2006471/agentproof/blob/main/src/app/api/agents/%5Bid%5D/run/route.ts"
click node_worker "https://github.com/dineshkumar2006471/agentproof/blob/main/workers/test-runner-worker/handler.ts"
click node_semantic_judge "https://github.com/dineshkumar2006471/agentproof/blob/main/src/lib/openai/semantic-judge.ts"
click node_dynamodb "https://github.com/dineshkumar2006471/agentproof/blob/main/src/lib/aws/dynamodb.ts"
click node_s3 "https://github.com/dineshkumar2006471/agentproof/blob/main/src/lib/aws/s3.ts"
click node_run_api_read "https://github.com/dineshkumar2006471/agentproof/blob/main/src/app/api/runs/%5Bid%5D/route.ts"
click node_report_ui "https://github.com/dineshkumar2006471/agentproof/blob/main/src/app/agents/%5Bid%5D/report/%5Brun%5D/page.tsx"
click node_public_report "https://github.com/dineshkumar2006471/agentproof/blob/main/src/app/verify/%5BpublicId%5D/page.tsx"
click node_public_verify_api "https://github.com/dineshkumar2006471/agentproof/blob/main/src/app/api/verify/%5BpublicId%5D/route.ts"
click node_auth "https://github.com/dineshkumar2006471/agentproof/blob/main/src/lib/auth/cognito.ts"
click node_auth_api "https://github.com/dineshkumar2006471/agentproof/blob/main/src/app/api/auth/sign-in/route.ts"
click node_billing_api "https://github.com/dineshkumar2006471/agentproof/blob/main/src/app/api/billing/checkout/route.ts"
click node_payments "https://github.com/dineshkumar2006471/agentproof/blob/main/src/lib/dodo.ts"
click node_billing_webhook "https://github.com/dineshkumar2006471/agentproof/blob/main/src/app/api/webhooks/dodo/route.ts"
click node_founder_metrics "https://github.com/dineshkumar2006471/agentproof/blob/main/src/lib/founder.ts"

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_workspace,node_agent_api,node_agent_detail_api,node_browser toneBlue
class node_contract_draft,node_contract_api,node_contract_engine,node_test_generation,node_test_generator,node_run_api,node_worker,node_semantic_judge,node_run_api_read,node_report_ui,node_public_report,node_public_verify_api toneAmber
class node_queue,node_dynamodb,node_s3,node_auth,node_auth_api toneMint
class node_billing_api,node_payments,node_billing_webhook,node_founder_metrics toneRose
class node_target_agent toneIndigo
```

## Components

### Workspace and API

- [Agent workspace](https://github.com/dineshkumar2006471/agentproof/blob/main/src/app/agents/layout.tsx): `src/app/agents/layout.tsx`
- [Agent registry API](https://github.com/dineshkumar2006471/agentproof/blob/main/src/app/api/agents/route.ts): `src/app/api/agents/route.ts`
- [Agent detail API](https://github.com/dineshkumar2006471/agentproof/blob/main/src/app/api/agents/%5Bid%5D/route.ts): `src/app/api/agents/[id]/route.ts`

### Verification lifecycle

- [Contract drafting API](https://github.com/dineshkumar2006471/agentproof/blob/main/src/app/api/agents/%5Bid%5D/contract/draft/route.ts): `src/app/api/agents/[id]/contract/draft/route.ts`
- [Contract API](https://github.com/dineshkumar2006471/agentproof/blob/main/src/app/api/agents/%5Bid%5D/contract/route.ts): `src/app/api/agents/[id]/contract/route.ts`
- [Contract engine](https://github.com/dineshkumar2006471/agentproof/blob/main/src/lib/openai/contract-engine.ts): `src/lib/openai/contract-engine.ts`
- [Test generation API](https://github.com/dineshkumar2006471/agentproof/blob/main/src/app/api/agents/%5Bid%5D/generate-tests/route.ts): `src/app/api/agents/[id]/generate-tests/route.ts`
- [Scenario generator](https://github.com/dineshkumar2006471/agentproof/blob/main/src/lib/openai/test-generator.ts): `src/lib/openai/test-generator.ts`
- [Run orchestration API](https://github.com/dineshkumar2006471/agentproof/blob/main/src/app/api/agents/%5Bid%5D/run/route.ts): `src/app/api/agents/[id]/run/route.ts`
- [Verification worker](https://github.com/dineshkumar2006471/agentproof/blob/main/workers/test-runner-worker/handler.ts): `workers/test-runner-worker/handler.ts`
- [Semantic evaluation](https://github.com/dineshkumar2006471/agentproof/blob/main/src/lib/openai/semantic-judge.ts): `src/lib/openai/semantic-judge.ts`
- [Run and export APIs](https://github.com/dineshkumar2006471/agentproof/blob/main/src/app/api/runs/%5Bid%5D/route.ts): `src/app/api/runs/[id]/route.ts`
- [Run report view](https://github.com/dineshkumar2006471/agentproof/blob/main/src/app/agents/%5Bid%5D/report/%5Brun%5D/page.tsx): `src/app/agents/[id]/report/[run]/page.tsx`
- [Public report surface](https://github.com/dineshkumar2006471/agentproof/blob/main/src/app/verify/%5BpublicId%5D/page.tsx): `src/app/verify/[publicId]/page.tsx`
- [Public verification API](https://github.com/dineshkumar2006471/agentproof/blob/main/src/app/api/verify/%5BpublicId%5D/route.ts): `src/app/api/verify/[publicId]/route.ts`

### Platform services

- **Amazon SQS**
- [DynamoDB records](https://github.com/dineshkumar2006471/agentproof/blob/main/src/lib/aws/dynamodb.ts): `src/lib/aws/dynamodb.ts`
- [Report artifacts](https://github.com/dineshkumar2006471/agentproof/blob/main/src/lib/aws/s3.ts): `src/lib/aws/s3.ts`
- [Cognito authentication](https://github.com/dineshkumar2006471/agentproof/blob/main/src/lib/auth/cognito.ts): `src/lib/auth/cognito.ts`
- [Authentication routes](https://github.com/dineshkumar2006471/agentproof/blob/main/src/app/api/auth/sign-in/route.ts): `src/app/api/auth/sign-in/route.ts`

### Plans and operations

- [Checkout API](https://github.com/dineshkumar2006471/agentproof/blob/main/src/app/api/billing/checkout/route.ts): `src/app/api/billing/checkout/route.ts`
- [Dodo Payments](https://github.com/dineshkumar2006471/agentproof/blob/main/src/lib/dodo.ts): `src/lib/dodo.ts`
- [Payment webhook](https://github.com/dineshkumar2006471/agentproof/blob/main/src/app/api/webhooks/dodo/route.ts): `src/app/api/webhooks/dodo/route.ts`
- [Operator metrics](https://github.com/dineshkumar2006471/agentproof/blob/main/src/lib/founder.ts): `src/lib/founder.ts`

### Other components

- **Browser / user**
- **Deployed agent endpoint**

## Connections

- Browser / user → Agent workspace: uses
- Agent workspace → Agent registry API: registers agents
- Agent workspace → Agent detail API: manages agents
- Agent registry API → DynamoDB records: reads/writes agents
- Agent detail API → DynamoDB records: reads/writes contracts
- Agent workspace → Contract drafting API: requests draft
- Contract drafting API → Contract engine: drafts contract
- Contract engine → DynamoDB records: returns contract data
- Contract API → DynamoDB records: stores contract
- Agent workspace → Test generation API: generates tests
- Test generation API → Scenario generator: creates scenarios
- Scenario generator → DynamoDB records: stores test matrix
- Agent workspace → Run orchestration API: starts verification
- Run orchestration API → DynamoDB records: loads inputs, records run
- Run orchestration API → Amazon SQS: enqueues run
- Amazon SQS → Verification worker: dispatches job
- Verification worker → Deployed agent endpoint: posts scenarios
- Verification worker → Semantic evaluation: evaluates responses
- Verification worker → DynamoDB records: records evidence and score
- Verification worker → Report artifacts: stores report artifacts
- Agent workspace → Run and export APIs: reviews or exports
- Run and export APIs → DynamoDB records: reads run evidence
- Run and export APIs → Report artifacts: reads artifacts
- Run report view → Run and export APIs: loads report data
- Browser / user → Public report surface: views shared report
- Public report surface → Public verification API: loads verification
- Public verification API → DynamoDB records: reads public evidence
- Agent workspace → Authentication routes: signs in
- Authentication routes → Cognito authentication: authenticates
- Browser / user → Checkout API: starts checkout
- Checkout API → Dodo Payments: creates checkout
- Dodo Payments → Payment webhook: sends payment event
- Payment webhook → DynamoDB records: updates plan state
- Operator metrics → DynamoDB records: reads aggregate signals