# danielx2d4144/zkverify-gatekeeper-agent architecture

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

- Interactive diagram: https://gitdiagram.com/danielx2d4144/zkverify-gatekeeper-agent
- Repository: https://github.com/danielx2d4144/zkverify-gatekeeper-agent

## Overview

This repository implements a signed proof-gatekeeper agent, with both a Vercel/local ESM transport and a separate plain-Node transport. Requests are authenticated, classified, and routed to Gatekeeper or Steal-the-VFY task logic; each task evaluates its domain rules and may generate and locally verify a Groth16 proof before returning a result. The README also identifies Vercel Blob as an optional durable proof-seen store. The graph covers both implementations; links among unsampled modules are omitted where their call relationships are not established by the available evidence.

Main entry points: [`src/gatekeeper-task.mjs`](https://github.com/danielx2d4144/zkverify-gatekeeper-agent/blob/main/src/gatekeeper-task.mjs) (Gatekeeper task), [`src/handlers.mjs`](https://github.com/danielx2d4144/zkverify-gatekeeper-agent/blob/main/src/handlers.mjs) (Task handlers), [`src/core.js`](https://github.com/danielx2d4144/zkverify-gatekeeper-agent/blob/main/src/core.js) (Legacy transport-independent core), [`src/handler.mjs`](https://github.com/danielx2d4144/zkverify-gatekeeper-agent/blob/main/src/handler.mjs) (Signed transport handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_transport["Transport and authentication"]
  node_vercel_endpoint["Vercel endpoint<br/>[agent.mjs]"]
  node_local_server["Local ESM server<br/>[server.mjs]"]
  node_plain_server["Plain Node server<br/>[server.js]"]
  node_transport_handler["Signed transport handler<br/>[handler.mjs]"]
  node_security["HMAC and time checks<br/>[security.mjs]"]
end

subgraph group_routing["Task routing"]
  node_task_handlers["Task handlers<br/>[handlers.mjs]"]
end

subgraph group_gatekeeper["Gatekeeper task"]
  node_gatekeeper_task["Gatekeeper task"]
  node_gatekeeper_eval["Statement evaluation<br/>[gatekeeper.mjs]"]
  node_gatekeeper_proofs["Gatekeeper proof generation<br/>[proofs.mjs]"]
  node_task_encoding["Task ID encoding<br/>[gk-encoding.mjs]"]
  node_proof_seen[("Accepted proof tracking<br/>[seen.mjs]")]
end

subgraph group_steal["Steal strategy"]
  node_steal_turn["Steal turn processing<br/>[steal.mjs]"]
  node_steal_policy["Strategy policy<br/>[policy.mjs]"]
end

subgraph group_legacy["Legacy gatekeeper"]
  node_legacy_core["Legacy transport-independent core<br/>[core.js]"]
  node_legacy_decision["Legacy decision logic<br/>[decide.js]"]
  node_legacy_proof["Legacy proof generation<br/>[prove.js]"]
  node_legacy_store[("Legacy response and seen store<br/>[store.js]")]
end

node_agent_games(("Agent Games platform"))
node_vercel_blob[("Vercel Blob")]

node_agent_games -->|"sends requests"| node_vercel_endpoint
node_vercel_endpoint -->|"passes request"| node_transport_handler
node_vercel_endpoint -->|"supplies handlers"| node_task_handlers
node_local_server -->|"passes request"| node_transport_handler
node_local_server -->|"loads handlers"| node_task_handlers
node_plain_server -->|"calls"| node_legacy_core
node_transport_handler -->|"authenticates and checks time"| node_security
node_transport_handler -->|"dispatches task"| node_task_handlers
node_task_handlers -->|"invokes"| node_gatekeeper_task
node_task_handlers -->|"invokes"| node_steal_turn
node_gatekeeper_task -->|"evaluates statement"| node_gatekeeper_eval
node_gatekeeper_task -->|"reads and marks"| node_proof_seen
node_gatekeeper_task -->|"requests proof"| node_gatekeeper_proofs
node_gatekeeper_task -->|"encodes task ID"| node_task_encoding
node_proof_seen -.->|"may persist to"| node_vercel_blob
node_steal_turn -->|"decides and builds witness"| node_steal_policy
node_legacy_core -->|"decides"| node_legacy_decision
node_legacy_core -->|"generates proof"| node_legacy_proof
node_legacy_core -->|"reads and writes"| node_legacy_store

click node_vercel_endpoint "https://github.com/danielx2d4144/zkverify-gatekeeper-agent/blob/main/api/agent.mjs"
click node_local_server "https://github.com/danielx2d4144/zkverify-gatekeeper-agent/blob/main/src/server.mjs"
click node_plain_server "https://github.com/danielx2d4144/zkverify-gatekeeper-agent/blob/main/src/server.js"
click node_transport_handler "https://github.com/danielx2d4144/zkverify-gatekeeper-agent/blob/main/src/handler.mjs"
click node_security "https://github.com/danielx2d4144/zkverify-gatekeeper-agent/blob/main/src/security.mjs"
click node_task_handlers "https://github.com/danielx2d4144/zkverify-gatekeeper-agent/blob/main/src/handlers.mjs"
click node_gatekeeper_task "https://github.com/danielx2d4144/zkverify-gatekeeper-agent/blob/main/src/gatekeeper-task.mjs"
click node_gatekeeper_eval "https://github.com/danielx2d4144/zkverify-gatekeeper-agent/blob/main/src/gatekeeper.mjs"
click node_gatekeeper_proofs "https://github.com/danielx2d4144/zkverify-gatekeeper-agent/blob/main/src/proofs.mjs"
click node_task_encoding "https://github.com/danielx2d4144/zkverify-gatekeeper-agent/blob/main/src/gk-encoding.mjs"
click node_proof_seen "https://github.com/danielx2d4144/zkverify-gatekeeper-agent/blob/main/src/seen.mjs"
click node_steal_turn "https://github.com/danielx2d4144/zkverify-gatekeeper-agent/blob/main/src/steal.mjs"
click node_steal_policy "https://github.com/danielx2d4144/zkverify-gatekeeper-agent/blob/main/src/policy.mjs"
click node_legacy_core "https://github.com/danielx2d4144/zkverify-gatekeeper-agent/blob/main/src/core.js"
click node_legacy_decision "https://github.com/danielx2d4144/zkverify-gatekeeper-agent/blob/main/src/decide.js"
click node_legacy_proof "https://github.com/danielx2d4144/zkverify-gatekeeper-agent/blob/main/src/prove.js"
click node_legacy_store "https://github.com/danielx2d4144/zkverify-gatekeeper-agent/blob/main/src/store.js"

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_vercel_endpoint,node_local_server,node_plain_server,node_transport_handler,node_security toneBlue
class node_task_handlers,node_vercel_blob toneAmber
class node_gatekeeper_task,node_gatekeeper_eval,node_gatekeeper_proofs,node_task_encoding,node_proof_seen toneMint
class node_steal_turn,node_steal_policy toneRose
class node_legacy_core,node_legacy_decision,node_legacy_proof,node_legacy_store,node_agent_games toneIndigo
```

## Components

### Transport and authentication

- [Vercel endpoint](https://github.com/danielx2d4144/zkverify-gatekeeper-agent/blob/main/api/agent.mjs): `api/agent.mjs`
- [Local ESM server](https://github.com/danielx2d4144/zkverify-gatekeeper-agent/blob/main/src/server.mjs): `src/server.mjs`
- [Plain Node server](https://github.com/danielx2d4144/zkverify-gatekeeper-agent/blob/main/src/server.js): `src/server.js`
- [Signed transport handler](https://github.com/danielx2d4144/zkverify-gatekeeper-agent/blob/main/src/handler.mjs): `src/handler.mjs`
- [HMAC and time checks](https://github.com/danielx2d4144/zkverify-gatekeeper-agent/blob/main/src/security.mjs): `src/security.mjs`

### Task routing

- [Task handlers](https://github.com/danielx2d4144/zkverify-gatekeeper-agent/blob/main/src/handlers.mjs): `src/handlers.mjs`

### Gatekeeper task

- [Gatekeeper task](https://github.com/danielx2d4144/zkverify-gatekeeper-agent/blob/main/src/gatekeeper-task.mjs): `src/gatekeeper-task.mjs`
- [Statement evaluation](https://github.com/danielx2d4144/zkverify-gatekeeper-agent/blob/main/src/gatekeeper.mjs): `src/gatekeeper.mjs`
- [Gatekeeper proof generation](https://github.com/danielx2d4144/zkverify-gatekeeper-agent/blob/main/src/proofs.mjs): `src/proofs.mjs`
- [Task ID encoding](https://github.com/danielx2d4144/zkverify-gatekeeper-agent/blob/main/src/gk-encoding.mjs): `src/gk-encoding.mjs`
- [Accepted proof tracking](https://github.com/danielx2d4144/zkverify-gatekeeper-agent/blob/main/src/seen.mjs): `src/seen.mjs`

### Steal strategy

- [Steal turn processing](https://github.com/danielx2d4144/zkverify-gatekeeper-agent/blob/main/src/steal.mjs): `src/steal.mjs`
- [Strategy policy](https://github.com/danielx2d4144/zkverify-gatekeeper-agent/blob/main/src/policy.mjs): `src/policy.mjs`

### Legacy gatekeeper

- [Legacy transport-independent core](https://github.com/danielx2d4144/zkverify-gatekeeper-agent/blob/main/src/core.js): `src/core.js`
- [Legacy decision logic](https://github.com/danielx2d4144/zkverify-gatekeeper-agent/blob/main/src/decide.js): `src/decide.js`
- [Legacy proof generation](https://github.com/danielx2d4144/zkverify-gatekeeper-agent/blob/main/src/prove.js): `src/prove.js`
- [Legacy response and seen store](https://github.com/danielx2d4144/zkverify-gatekeeper-agent/blob/main/src/store.js): `src/store.js`

### Other components

- **Agent Games platform**
- **Vercel Blob**

## Connections

- Agent Games platform → Vercel endpoint: sends requests (evidence: `README.md`)
- Vercel endpoint → Signed transport handler: passes request (evidence: `api/agent.mjs`)
- Vercel endpoint → Task handlers: supplies handlers (evidence: `api/agent.mjs`)
- Local ESM server → Signed transport handler: passes request (evidence: `src/server.mjs`)
- Local ESM server → Task handlers: loads handlers (evidence: `src/server.mjs`)
- Plain Node server → Legacy transport-independent core: calls (evidence: `src/server.js`)
- Signed transport handler → HMAC and time checks: authenticates and checks time (evidence: `src/handler.mjs`)
- Signed transport handler → Task handlers: dispatches task (evidence: `src/handler.mjs`)
- Task handlers → Gatekeeper task: invokes (evidence: `src/handlers.mjs`)
- Task handlers → Steal turn processing: invokes (evidence: `src/handlers.mjs`)
- Gatekeeper task → Statement evaluation: evaluates statement (evidence: `src/gatekeeper-task.mjs`)
- Gatekeeper task → Accepted proof tracking: reads and marks (evidence: `src/gatekeeper-task.mjs`)
- Gatekeeper task → Gatekeeper proof generation: requests proof (evidence: `src/gatekeeper-task.mjs`)
- Gatekeeper task → Task ID encoding: encodes task ID (evidence: `src/gatekeeper-task.mjs`)
- Accepted proof tracking → Vercel Blob: may persist to (evidence: `README.md`)
- Steal turn processing → Strategy policy: decides and builds witness (evidence: `src/steal.mjs`)
- Legacy transport-independent core → Legacy decision logic: decides (evidence: `src/core.js`)
- Legacy transport-independent core → Legacy proof generation: generates proof (evidence: `src/core.js`)
- Legacy transport-independent core → Legacy response and seen store: reads and writes (evidence: `src/core.js`)
