# rohitamalraj/surety architecture

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

- Interactive diagram: https://gitdiagram.com/rohitamalraj/surety
- Repository: https://github.com/rohitamalraj/surety

## Overview

Surety is an on-chain insurance product for AI-agent activity: ENS records publish policy rules, a Uniswap v4 hook enforces swap limits, and World ID human verification gates payouts. The main user journey is to configure and purchase a policy, fund/use an agent vault, observe payment events and violations, then file and authorize a claim. The README documents contract capabilities not represented by source files in this tree; those are shown as external system components. Backend excerpts establish several service relationships; frontend-to-service links are limited to documented REST and wallet flows.

Main entry points: [`backend/src/server.ts`](https://github.com/rohitamalraj/surety/blob/main/backend/src/server.ts) (HTTP API server), [`frontend/app/page.tsx`](https://github.com/rohitamalraj/surety/blob/main/frontend/app/page.tsx) (Surety web app), [`frontend/lib/api.ts`](https://github.com/rohitamalraj/surety/blob/main/frontend/lib/api.ts) (Frontend API client), [`frontend/app/insure/page.tsx`](https://github.com/rohitamalraj/surety/blob/main/frontend/app/insure/page.tsx) (Policy purchase)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_purchase["Policy and discovery"]
  node_frontend["Surety web app<br/>[page.tsx]"]
  node_policy_ui["Policy purchase<br/>[page.tsx]"]
  node_agent_ui["Agent activity<br/>[page.tsx]"]
  node_policy_view["Policy and claims<br/>[page.tsx]"]
  node_dashboard["Dashboard and feed<br/>[page.tsx]"]
  node_api_client["Frontend API client<br/>[api.ts]"]
end

subgraph group_backend["Backend services"]
  node_server["HTTP API server<br/>[server.ts]"]
  node_policy_data["Policy and feed API<br/>[data.ts]"]
  node_event_indexer[("Event indexer<br/>[watchEvents.ts]")]
  node_label_lookup["ENS label lookup<br/>[labels.ts]"]
  node_payments_agent["Hosted payments agent<br/>[payments.ts]"]
  node_agent_simulator["Agent simulator<br/>[simulator.ts]"]
end

subgraph group_human["Human verification"]
  node_idkit_api["IDKit verification API<br/>[idkit.ts]"]
  node_idkit_verify["Proof-of-human checks<br/>[proofOfHuman.ts]"]
  node_oidc["World ID OIDC<br/>[oidc.ts]"]
  node_sessions[("Verification sessions<br/>[sessions.ts]")]
  node_human_attest["Human attestations<br/>[signer.ts]"]
end

subgraph group_chain["On-chain insurance"]
  node_ethereum[("Ethereum Sepolia contracts")]
  node_policy_registry["Policy registry"]
  node_agent_vault["Agent vault"]
  node_surety_hook["Surety v4 hook"]
  node_claim_system["Oracle and claim router"]
end

node_user(("Policyholder / user"))
node_ens[("ENSv2")]
node_world_id["World ID issuer"]
node_uniswap[("Uniswap v4 PoolManager")]

node_user -->|"uses"| node_frontend
node_frontend -->|"opens purchase"| node_policy_ui
node_frontend -->|"opens agents"| node_agent_ui
node_frontend -->|"views policy"| node_policy_view
node_frontend -->|"views activity"| node_dashboard
node_policy_ui -.->|"requests REST"| node_api_client
node_agent_ui -.->|"requests REST"| node_api_client
node_policy_view -.->|"requests REST"| node_api_client
node_dashboard -.->|"requests REST"| node_api_client
node_api_client -->|"calls REST"| node_server
node_server -->|"mounts routes"| node_policy_data
node_server -->|"starts and syncs"| node_event_indexer
node_policy_data -->|"reads feed"| node_event_indexer
node_policy_data -->|"resolves labels"| node_label_lookup
node_label_lookup -->|"reads events"| node_event_indexer
node_server -->|"mounts routes"| node_idkit_api
node_idkit_api -->|"verifies proofs"| node_idkit_verify
node_server -->|"starts and verifies login"| node_oidc
node_server -->|"creates and consumes"| node_sessions
node_server -->|"submits claim approval"| node_human_attest
node_oidc -->|"exchanges and verifies tokens"| node_world_id
node_policy_data -->|"runs demo step"| node_agent_simulator
node_payments_agent -->|"uses swap helpers"| node_agent_simulator
node_policy_ui -->|"issues policy"| node_policy_registry
node_policy_registry -->|"registers policy name"| node_ens
node_policy_registry -->|"creates agent coverage"| node_agent_vault
node_agent_ui -->|"sends agent payments"| node_agent_vault
node_agent_vault -->|"routes swaps"| node_surety_hook
node_surety_hook -->|"enforces before swap"| node_uniswap
node_surety_hook -->|"releases verified payouts"| node_claim_system
node_claim_system -->|"requires fresh human proof"| node_world_id
node_human_attest -->|"signs claim approvals"| node_claim_system
node_policy_view -->|"files and tracks claims"| node_claim_system
node_policy_ui -->|"enrolls policyholder"| node_world_id
node_policy_registry -->|"checks reserve"| node_surety_hook

click node_frontend "https://github.com/rohitamalraj/surety/blob/main/frontend/app/page.tsx"
click node_policy_ui "https://github.com/rohitamalraj/surety/blob/main/frontend/app/insure/page.tsx"
click node_agent_ui "https://github.com/rohitamalraj/surety/blob/main/frontend/app/agents/payments/page.tsx"
click node_policy_view "https://github.com/rohitamalraj/surety/blob/main/frontend/app/policy/%5BagentName%5D/page.tsx"
click node_dashboard "https://github.com/rohitamalraj/surety/blob/main/frontend/app/dashboard/page.tsx"
click node_api_client "https://github.com/rohitamalraj/surety/blob/main/frontend/lib/api.ts"
click node_server "https://github.com/rohitamalraj/surety/blob/main/backend/src/server.ts"
click node_policy_data "https://github.com/rohitamalraj/surety/blob/main/backend/src/routes/data.ts"
click node_event_indexer "https://github.com/rohitamalraj/surety/blob/main/backend/src/indexer/watchEvents.ts"
click node_label_lookup "https://github.com/rohitamalraj/surety/blob/main/backend/src/chain/labels.ts"
click node_payments_agent "https://github.com/rohitamalraj/surety/blob/main/backend/src/agent/payments.ts"
click node_agent_simulator "https://github.com/rohitamalraj/surety/blob/main/backend/src/agent/simulator.ts"
click node_idkit_api "https://github.com/rohitamalraj/surety/blob/main/backend/src/routes/idkit.ts"
click node_idkit_verify "https://github.com/rohitamalraj/surety/blob/main/backend/src/idkit/proofOfHuman.ts"
click node_oidc "https://github.com/rohitamalraj/surety/blob/main/backend/src/worldid/oidc.ts"
click node_sessions "https://github.com/rohitamalraj/surety/blob/main/backend/src/worldid/sessions.ts"
click node_human_attest "https://github.com/rohitamalraj/surety/blob/main/backend/src/worldid/signer.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_frontend,node_policy_ui,node_agent_ui,node_policy_view,node_dashboard,node_api_client,node_user toneBlue
class node_server,node_policy_data,node_event_indexer,node_label_lookup,node_payments_agent,node_agent_simulator,node_ens,node_uniswap toneAmber
class node_idkit_api,node_idkit_verify,node_oidc,node_sessions,node_human_attest toneMint
class node_ethereum,node_policy_registry,node_agent_vault,node_surety_hook,node_claim_system toneRose
class node_world_id toneIndigo
```

## Components

### Policy and discovery

- [Surety web app](https://github.com/rohitamalraj/surety/blob/main/frontend/app/page.tsx): `frontend/app/page.tsx`
- [Policy purchase](https://github.com/rohitamalraj/surety/blob/main/frontend/app/insure/page.tsx): `frontend/app/insure/page.tsx`
- [Agent activity](https://github.com/rohitamalraj/surety/blob/main/frontend/app/agents/payments/page.tsx): `frontend/app/agents/payments/page.tsx`
- [Policy and claims](https://github.com/rohitamalraj/surety/blob/main/frontend/app/policy/%5BagentName%5D/page.tsx): `frontend/app/policy/[agentName]/page.tsx`
- [Dashboard and feed](https://github.com/rohitamalraj/surety/blob/main/frontend/app/dashboard/page.tsx): `frontend/app/dashboard/page.tsx`
- [Frontend API client](https://github.com/rohitamalraj/surety/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`

### Backend services

- [HTTP API server](https://github.com/rohitamalraj/surety/blob/main/backend/src/server.ts): `backend/src/server.ts`
- [Policy and feed API](https://github.com/rohitamalraj/surety/blob/main/backend/src/routes/data.ts): `backend/src/routes/data.ts`
- [Event indexer](https://github.com/rohitamalraj/surety/blob/main/backend/src/indexer/watchEvents.ts): `backend/src/indexer/watchEvents.ts`
- [ENS label lookup](https://github.com/rohitamalraj/surety/blob/main/backend/src/chain/labels.ts): `backend/src/chain/labels.ts`
- [Hosted payments agent](https://github.com/rohitamalraj/surety/blob/main/backend/src/agent/payments.ts): `backend/src/agent/payments.ts`
- [Agent simulator](https://github.com/rohitamalraj/surety/blob/main/backend/src/agent/simulator.ts): `backend/src/agent/simulator.ts`

### Human verification

- [IDKit verification API](https://github.com/rohitamalraj/surety/blob/main/backend/src/routes/idkit.ts): `backend/src/routes/idkit.ts`
- [Proof-of-human checks](https://github.com/rohitamalraj/surety/blob/main/backend/src/idkit/proofOfHuman.ts): `backend/src/idkit/proofOfHuman.ts`
- [World ID OIDC](https://github.com/rohitamalraj/surety/blob/main/backend/src/worldid/oidc.ts): `backend/src/worldid/oidc.ts`
- [Verification sessions](https://github.com/rohitamalraj/surety/blob/main/backend/src/worldid/sessions.ts): `backend/src/worldid/sessions.ts`
- [Human attestations](https://github.com/rohitamalraj/surety/blob/main/backend/src/worldid/signer.ts): `backend/src/worldid/signer.ts`

### On-chain insurance

- **Ethereum Sepolia contracts**
- **Policy registry**
- **Agent vault**
- **Surety v4 hook**
- **Oracle and claim router**

### Other components

- **Policyholder / user**
- **ENSv2**
- **World ID issuer**
- **Uniswap v4 PoolManager**

## Connections

- Policyholder / user → Surety web app: uses (evidence: `README.md`)
- Surety web app → Policy purchase: opens purchase (evidence: `README.md`)
- Surety web app → Agent activity: opens agents (evidence: `README.md`)
- Surety web app → Policy and claims: views policy (evidence: `README.md`)
- Surety web app → Dashboard and feed: views activity (evidence: `README.md`)
- Policy purchase → Frontend API client: requests REST
- Agent activity → Frontend API client: requests REST
- Policy and claims → Frontend API client: requests REST
- Dashboard and feed → Frontend API client: requests REST
- Frontend API client → HTTP API server: calls REST (evidence: `README.md`)
- HTTP API server → Policy and feed API: mounts routes (evidence: `backend/src/server.ts`)
- HTTP API server → Event indexer: starts and syncs (evidence: `backend/src/server.ts`)
- Policy and feed API → Event indexer: reads feed (evidence: `backend/src/routes/data.ts`)
- Policy and feed API → ENS label lookup: resolves labels (evidence: `backend/src/routes/data.ts`)
- ENS label lookup → Event indexer: reads events (evidence: `backend/src/chain/labels.ts`)
- HTTP API server → IDKit verification API: mounts routes (evidence: `backend/src/server.ts`)
- IDKit verification API → Proof-of-human checks: verifies proofs (evidence: `backend/src/routes/idkit.ts`)
- HTTP API server → World ID OIDC: starts and verifies login (evidence: `backend/src/server.ts`)
- HTTP API server → Verification sessions: creates and consumes (evidence: `backend/src/server.ts`)
- HTTP API server → Human attestations: submits claim approval (evidence: `backend/src/server.ts`)
- World ID OIDC → World ID issuer: exchanges and verifies tokens (evidence: `backend/src/worldid/oidc.ts`)
- Policy and feed API → Agent simulator: runs demo step (evidence: `backend/src/routes/data.ts`)
- Hosted payments agent → Agent simulator: uses swap helpers (evidence: `backend/src/agent/payments.ts`)
- Policy purchase → Policy registry: issues policy (evidence: `README.md`)
- Policy registry → ENSv2: registers policy name (evidence: `README.md`)
- Policy registry → Agent vault: creates agent coverage (evidence: `README.md`)
- Agent activity → Agent vault: sends agent payments (evidence: `README.md`)
- Agent vault → Surety v4 hook: routes swaps (evidence: `README.md`)
- Surety v4 hook → Uniswap v4 PoolManager: enforces before swap (evidence: `README.md`)
- Surety v4 hook → Oracle and claim router: releases verified payouts (evidence: `README.md`)
- Oracle and claim router → World ID issuer: requires fresh human proof (evidence: `README.md`)
- Human attestations → Oracle and claim router: signs claim approvals (evidence: `README.md`)
- Policy and claims → Oracle and claim router: files and tracks claims (evidence: `README.md`)
- Policy purchase → World ID issuer: enrolls policyholder (evidence: `README.md`)
- Policy registry → Surety v4 hook: checks reserve (evidence: `README.md`)
