# ishamishra0408/agent-kyc architecture

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

- Interactive diagram: https://gitdiagram.com/ishamishra0408/agent-kyc
- Repository: https://github.com/ishamishra0408/agent-kyc

## Overview

Agent KYCReady is a driver-verification workflow: the driver submits identity evidence, readers and registries supply evidence, policy—not AI—decides, and approved drivers can add vehicles and book loads. Operations handles cases sent for human review. The README documents the product boundary and external integrations; several service internals were not excerpted, so only documented or indexed relationships are shown.

Main entry points: [`server/api/app.ts`](https://github.com/ishamishra0408/agent-kyc/blob/main/server/api/app.ts) (HTTP API), [`server/services/kyc.ts`](https://github.com/ishamishra0408/agent-kyc/blob/main/server/services/kyc.ts) (KYC service), [`src/api.ts`](https://github.com/ishamishra0408/agent-kyc/blob/main/src/api.ts) (API client), [`server/db/store.ts`](https://github.com/ishamishra0408/agent-kyc/blob/main/server/db/store.ts) (SQLite store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Driver and ops clients"]
  node_driver["Driver app<br/>[PhoneApp.tsx]"]
  node_driver_kyc["KYC screens<br/>[Kyc.tsx]"]
  node_driver_loads["Loads and bookings<br/>[Loads.tsx]"]
  node_ops_ui["Ops console<br/>[OpsConsole.tsx]"]
  node_ops_case["Case detail<br/>[CaseDetail.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_workflow["Verification workflow"]
  node_api["HTTP API<br/>[app.ts]"]
  node_kyc["KYC service<br/>[kyc.ts]"]
  node_onboarding["Onboarding and bookings<br/>[onboarding.ts]"]
  node_ops_service["Review operations<br/>[ops.ts]"]
  node_app_boot["Runtime wiring<br/>[index.ts]"]
  node_review_draft["Review-note draft<br/>[reviewDraft.ts]"]
end

subgraph group_decision["Evidence and decisions"]
  node_reader["Photo reading<br/>[photoReader.ts]"]
  node_ai_reader["AI reader adapter<br/>[aiReader.ts]"]
  node_verification["Submission verification<br/>[verify.ts]"]
  node_policy["KYC policy contract<br/>[rules.ts]"]
  node_vehicle_policy["Vehicle policy contract<br/>[vehicle.ts]"]
  node_policy_engine["OPA policy engine<br/>[opa.ts]"]
end

subgraph group_state["Persistence and integrations"]
  node_openrouter["OpenRouter models<br/>[openrouter.ts]"]
  node_registry["Identity registries<br/>[registry.ts]"]
  node_graph["Trust graph<br/>[graph.ts]"]
  node_neo4j["Neo4j graph adapter<br/>[neo4jGraph.ts]"]
  node_store[("SQLite store<br/>[store.ts]")]
end

subgraph group_engagement["Follow-up"]
  node_nudges["Nudge cycle<br/>[nudges.ts]"]
  node_nudge_writer["Nudge writer<br/>[nudgeWriter.ts]"]
end

node_driver_actor(("Driver"))
node_reviewer(("Ops reviewer"))
node_marketplace["Load marketplace"]

node_driver_actor -->|"uses"| node_driver
node_reviewer -->|"uses"| node_ops_ui
node_driver -->|"shows"| node_driver_kyc
node_driver -->|"shows"| node_driver_loads
node_ops_ui -->|"renders"| node_ops_case
node_driver_kyc -->|"calls"| node_api_client
node_driver_loads -->|"calls"| node_api_client
node_ops_ui -->|"calls"| node_api_client
node_ops_case -->|"calls"| node_api_client
node_api_client -->|"requests"| node_api
node_api -->|"dispatches"| node_kyc
node_api -->|"runs cycle"| node_nudges
node_api -->|"requests draft"| node_ops_service
node_api -->|"reads and writes"| node_store
node_kyc -->|"verifies submission"| node_verification
node_kyc -->|"applies decision"| node_onboarding
node_kyc -->|"updates state"| node_store
node_kyc -->|"reads photos"| node_reader
node_verification -->|"decides"| node_policy
node_verification -->|"checks records"| node_registry
node_verification -->|"checks sharing"| node_graph
node_reader -->|"uses adapter"| node_ai_reader
node_ai_reader -->|"calls models"| node_openrouter
node_app_boot -->|"configures"| node_reader
node_app_boot -->|"configures"| node_neo4j
node_neo4j -->|"implements"| node_graph
node_policy -->|"runs policy"| node_policy_engine
node_onboarding -->|"decides vehicle"| node_vehicle_policy
node_vehicle_policy -->|"runs policy"| node_policy_engine
node_onboarding -->|"persists outcome"| node_store
node_onboarding -->|"books loads"| node_marketplace
node_api -->|"builds draft"| node_review_draft
node_ops_service -->|"records decision"| node_kyc
node_ops_service -->|"reads case"| node_store
node_nudges -->|"reads history"| node_store
node_nudges -->|"writes message"| node_nudge_writer

click node_driver "https://github.com/ishamishra0408/agent-kyc/blob/main/src/driver/PhoneApp.tsx"
click node_driver_kyc "https://github.com/ishamishra0408/agent-kyc/blob/main/src/driver/Kyc.tsx"
click node_driver_loads "https://github.com/ishamishra0408/agent-kyc/blob/main/src/driver/Loads.tsx"
click node_ops_ui "https://github.com/ishamishra0408/agent-kyc/blob/main/src/ops/OpsConsole.tsx"
click node_ops_case "https://github.com/ishamishra0408/agent-kyc/blob/main/src/ops/CaseDetail.tsx"
click node_api_client "https://github.com/ishamishra0408/agent-kyc/blob/main/src/api.ts"
click node_api "https://github.com/ishamishra0408/agent-kyc/blob/main/server/api/app.ts"
click node_kyc "https://github.com/ishamishra0408/agent-kyc/blob/main/server/services/kyc.ts"
click node_onboarding "https://github.com/ishamishra0408/agent-kyc/blob/main/server/services/onboarding.ts"
click node_ops_service "https://github.com/ishamishra0408/agent-kyc/blob/main/server/services/ops.ts"
click node_reader "https://github.com/ishamishra0408/agent-kyc/blob/main/server/adapters/photoReader.ts"
click node_ai_reader "https://github.com/ishamishra0408/agent-kyc/blob/main/server/adapters/aiReader.ts"
click node_openrouter "https://github.com/ishamishra0408/agent-kyc/blob/main/server/adapters/openrouter.ts"
click node_verification "https://github.com/ishamishra0408/agent-kyc/blob/main/server/verify.ts"
click node_registry "https://github.com/ishamishra0408/agent-kyc/blob/main/server/adapters/registry.ts"
click node_graph "https://github.com/ishamishra0408/agent-kyc/blob/main/server/adapters/graph.ts"
click node_neo4j "https://github.com/ishamishra0408/agent-kyc/blob/main/server/adapters/neo4jGraph.ts"
click node_policy "https://github.com/ishamishra0408/agent-kyc/blob/main/server/domain/rules.ts"
click node_vehicle_policy "https://github.com/ishamishra0408/agent-kyc/blob/main/server/domain/vehicle.ts"
click node_policy_engine "https://github.com/ishamishra0408/agent-kyc/blob/main/server/policy/opa.ts"
click node_store "https://github.com/ishamishra0408/agent-kyc/blob/main/server/db/store.ts"
click node_nudges "https://github.com/ishamishra0408/agent-kyc/blob/main/server/services/nudges.ts"
click node_nudge_writer "https://github.com/ishamishra0408/agent-kyc/blob/main/server/ai/nudgeWriter.ts"
click node_app_boot "https://github.com/ishamishra0408/agent-kyc/blob/main/server/index.ts"
click node_review_draft "https://github.com/ishamishra0408/agent-kyc/blob/main/server/ai/reviewDraft.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_driver,node_driver_kyc,node_driver_loads,node_ops_ui,node_ops_case,node_api_client,node_reviewer toneBlue
class node_api,node_kyc,node_onboarding,node_ops_service,node_app_boot,node_review_draft toneAmber
class node_reader,node_ai_reader,node_verification,node_policy,node_vehicle_policy,node_policy_engine toneMint
class node_openrouter,node_registry,node_graph,node_neo4j,node_store toneRose
class node_nudges,node_nudge_writer,node_driver_actor,node_marketplace toneIndigo
```

## Components

### Driver and ops clients

- [Driver app](https://github.com/ishamishra0408/agent-kyc/blob/main/src/driver/PhoneApp.tsx): `src/driver/PhoneApp.tsx`
- [KYC screens](https://github.com/ishamishra0408/agent-kyc/blob/main/src/driver/Kyc.tsx): `src/driver/Kyc.tsx`
- [Loads and bookings](https://github.com/ishamishra0408/agent-kyc/blob/main/src/driver/Loads.tsx): `src/driver/Loads.tsx`
- [Ops console](https://github.com/ishamishra0408/agent-kyc/blob/main/src/ops/OpsConsole.tsx): `src/ops/OpsConsole.tsx`
- [Case detail](https://github.com/ishamishra0408/agent-kyc/blob/main/src/ops/CaseDetail.tsx): `src/ops/CaseDetail.tsx`
- [API client](https://github.com/ishamishra0408/agent-kyc/blob/main/src/api.ts): `src/api.ts`

### Verification workflow

- [HTTP API](https://github.com/ishamishra0408/agent-kyc/blob/main/server/api/app.ts): `server/api/app.ts`
- [KYC service](https://github.com/ishamishra0408/agent-kyc/blob/main/server/services/kyc.ts): `server/services/kyc.ts`
- [Onboarding and bookings](https://github.com/ishamishra0408/agent-kyc/blob/main/server/services/onboarding.ts): `server/services/onboarding.ts`
- [Review operations](https://github.com/ishamishra0408/agent-kyc/blob/main/server/services/ops.ts): `server/services/ops.ts`
- [Runtime wiring](https://github.com/ishamishra0408/agent-kyc/blob/main/server/index.ts): `server/index.ts`
- [Review-note draft](https://github.com/ishamishra0408/agent-kyc/blob/main/server/ai/reviewDraft.ts): `server/ai/reviewDraft.ts`

### Evidence and decisions

- [Photo reading](https://github.com/ishamishra0408/agent-kyc/blob/main/server/adapters/photoReader.ts): `server/adapters/photoReader.ts`
- [AI reader adapter](https://github.com/ishamishra0408/agent-kyc/blob/main/server/adapters/aiReader.ts): `server/adapters/aiReader.ts`
- [Submission verification](https://github.com/ishamishra0408/agent-kyc/blob/main/server/verify.ts): `server/verify.ts`
- [KYC policy contract](https://github.com/ishamishra0408/agent-kyc/blob/main/server/domain/rules.ts): `server/domain/rules.ts`
- [Vehicle policy contract](https://github.com/ishamishra0408/agent-kyc/blob/main/server/domain/vehicle.ts): `server/domain/vehicle.ts`
- [OPA policy engine](https://github.com/ishamishra0408/agent-kyc/blob/main/server/policy/opa.ts): `server/policy/opa.ts`

### Persistence and integrations

- [OpenRouter models](https://github.com/ishamishra0408/agent-kyc/blob/main/server/adapters/openrouter.ts): `server/adapters/openrouter.ts`
- [Identity registries](https://github.com/ishamishra0408/agent-kyc/blob/main/server/adapters/registry.ts): `server/adapters/registry.ts`
- [Trust graph](https://github.com/ishamishra0408/agent-kyc/blob/main/server/adapters/graph.ts): `server/adapters/graph.ts`
- [Neo4j graph adapter](https://github.com/ishamishra0408/agent-kyc/blob/main/server/adapters/neo4jGraph.ts): `server/adapters/neo4jGraph.ts`
- [SQLite store](https://github.com/ishamishra0408/agent-kyc/blob/main/server/db/store.ts): `server/db/store.ts`

### Follow-up

- [Nudge cycle](https://github.com/ishamishra0408/agent-kyc/blob/main/server/services/nudges.ts): `server/services/nudges.ts`
- [Nudge writer](https://github.com/ishamishra0408/agent-kyc/blob/main/server/ai/nudgeWriter.ts): `server/ai/nudgeWriter.ts`

### Other components

- **Driver**
- **Ops reviewer**
- **Load marketplace**

## Connections

- Driver → Driver app: uses (evidence: `README.md`)
- Ops reviewer → Ops console: uses (evidence: `README.md`)
- Driver app → KYC screens: shows (evidence: `src/driver/PhoneApp.tsx`)
- Driver app → Loads and bookings: shows (evidence: `src/driver/PhoneApp.tsx`)
- Ops console → Case detail: renders (evidence: `src/ops/OpsConsole.tsx`)
- KYC screens → API client: calls (evidence: `src/driver/Kyc.tsx`)
- Loads and bookings → API client: calls (evidence: `src/driver/PhoneApp.tsx`)
- Ops console → API client: calls (evidence: `src/ops/OpsConsole.tsx`)
- Case detail → API client: calls (evidence: `src/ops/CaseDetail.tsx`)
- API client → HTTP API: requests (evidence: `README.md`)
- HTTP API → KYC service: dispatches (evidence: `server/api/app.ts`)
- HTTP API → Nudge cycle: runs cycle (evidence: `server/api/app.ts`)
- HTTP API → Review operations: requests draft (evidence: `server/api/app.ts`)
- HTTP API → SQLite store: reads and writes (evidence: `server/api/app.ts`)
- KYC service → Submission verification: verifies submission (evidence: `server/services/kyc.ts`)
- KYC service → Onboarding and bookings: applies decision (evidence: `server/services/kyc.ts`)
- KYC service → SQLite store: updates state (evidence: `server/services/kyc.ts`)
- KYC service → Photo reading: reads photos (evidence: `server/services/kyc.ts`)
- Submission verification → KYC policy contract: decides (evidence: `server/verify.ts`)
- Submission verification → Identity registries: checks records (evidence: `server/verify.ts`)
- Submission verification → Trust graph: checks sharing (evidence: `server/verify.ts`)
- Photo reading → AI reader adapter: uses adapter (evidence: `server/adapters/photoReader.ts`)
- AI reader adapter → OpenRouter models: calls models (evidence: `server/index.ts`)
- Runtime wiring → Photo reading: configures (evidence: `server/index.ts`)
- Runtime wiring → Neo4j graph adapter: configures (evidence: `server/index.ts`)
- Neo4j graph adapter → Trust graph: implements (evidence: `server/adapters/neo4jGraph.ts`)
- KYC policy contract → OPA policy engine: runs policy (evidence: `server/policy/index.ts`)
- Onboarding and bookings → Vehicle policy contract: decides vehicle (evidence: `server/services/onboarding.ts`)
- Vehicle policy contract → OPA policy engine: runs policy (evidence: `server/policy/index.ts`)
- Onboarding and bookings → SQLite store: persists outcome (evidence: `server/services/onboarding.ts`)
- Onboarding and bookings → Load marketplace: books loads (evidence: `README.md`)
- HTTP API → Review-note draft: builds draft (evidence: `server/api/app.ts`)
- Review operations → KYC service: records decision (evidence: `server/services/ops.ts`)
- Review operations → SQLite store: reads case (evidence: `server/services/ops.ts`)
- Nudge cycle → SQLite store: reads history (evidence: `server/services/nudges.ts`)
- Nudge cycle → Nudge writer: writes message (evidence: `server/services/nudges.ts`)