# slslz/veil-ai architecture

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

- Interactive diagram: https://gitdiagram.com/slslz/veil-ai
- Repository: https://github.com/slslz/veil-ai

## Overview

Private AI Verification turns a verifier’s natural-language requirement into a reviewed eligibility policy, adapts supported criteria for a Midnight proof flow, and returns a qualified/not-qualified result without exposing applicant values. The graph separates the policy API, browser experience, and private verification runtime. README documents the overall flow, but marks the final policy-to-execution connection as in progress; that link is shown as unverified. Some runtime modules are represented by their exact file paths, though their full implementations were not sampled.

Main entry points: [`mainAPI.ts`](https://github.com/slslz/veil-ai/blob/main/mainAPI.ts) (Verification execution), [`backend/api/controllers/policy.controller.ts`](https://github.com/slslz/veil-ai/blob/main/backend/api/controllers/policy.controller.ts) (Parse policy handler), [`backend/ai/policy-parser.ts`](https://github.com/slslz/veil-ai/blob/main/backend/ai/policy-parser.ts) (AI policy parser), [`frontend/src/App.jsx`](https://github.com/slslz/veil-ai/blob/main/frontend/src/App.jsx) (Describe, review, result UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Verifier experience"]
  node_frontend["Describe, review, result UI<br/>[App.jsx]"]
end

subgraph group_policy["Policy interpretation API"]
  node_api["Express API<br/>[app.ts]"]
  node_policy_route["Policy parse route<br/>[policy.routes.ts]"]
  node_controller["Parse policy handler"]
  node_parser["AI policy parser<br/>[policy-parser.ts]"]
  node_ai_client["Structured AI client<br/>[ai-client.ts]"]
end

subgraph group_verification["Private verification"]
  node_criteria["Public criteria adapter"]
  node_execution["Verification execution<br/>[mainAPI.ts]"]
  node_contract["Eligibility circuit runtime<br/>[index.js]"]
  node_witness["Private age/income witness<br/>[witness.ts]"]
  node_bridge["Verification bridge"]
end

subgraph group_shared["Policy foundations"]
  node_validator["Policy semantics validator"]
  node_schema["Policy schemas<br/>[policy.schema.ts]"]
  node_policy_types["Policy types<br/>[policy.ts]"]
end

node_verifier(("Verifier / applicant"))
node_llm{{"AI LLM provider"}}
node_midnight{{"Midnight proof infrastructure"}}

node_verifier -->|"enters requirement"| node_frontend
node_frontend -->|"requests policy parse"| node_api
node_api -->|"routes policy requests"| node_policy_route
node_policy_route -->|"dispatches parse"| node_controller
node_controller -->|"parses requirement"| node_parser
node_parser -->|"generates structured policy"| node_ai_client
node_ai_client -.->|"requests structured output"| node_llm
node_parser -->|"validates AI output"| node_schema
node_parser -->|"checks policy semantics"| node_validator
node_controller -->|"validates policy semantics"| node_validator
node_controller -->|"adapts policy criteria"| node_criteria
node_frontend -.->|"starts verification"| node_execution
node_criteria -.->|"hands off criteria"| node_execution
node_execution -->|"invokes circuit"| node_contract
node_execution -->|"supplies private witness"| node_witness
node_contract -->|"requests private values"| node_witness
node_execution -->|"used by bridge"| node_bridge
node_contract -.->|"runs proof flow"| node_midnight
node_execution -.->|"returns result"| node_frontend

click node_frontend "https://github.com/slslz/veil-ai/blob/main/frontend/src/App.jsx"
click node_api "https://github.com/slslz/veil-ai/blob/main/backend/api/app.ts"
click node_policy_route "https://github.com/slslz/veil-ai/blob/main/backend/api/routes/policy.routes.ts"
click node_controller "https://github.com/slslz/veil-ai/blob/main/backend/api/controllers/policy.controller.ts"
click node_parser "https://github.com/slslz/veil-ai/blob/main/backend/ai/policy-parser.ts"
click node_ai_client "https://github.com/slslz/veil-ai/blob/main/backend/ai/ai-client.ts"
click node_validator "https://github.com/slslz/veil-ai/blob/main/backend/utils/policy-validator.ts"
click node_schema "https://github.com/slslz/veil-ai/blob/main/backend/schemas/policy.schema.ts"
click node_policy_types "https://github.com/slslz/veil-ai/blob/main/backend/types/policy.ts"
click node_criteria "https://github.com/slslz/veil-ai/blob/main/backend/midnight/policy-to-criteria.ts"
click node_execution "https://github.com/slslz/veil-ai/blob/main/mainAPI.ts"
click node_contract "https://github.com/slslz/veil-ai/blob/main/managed/eligibility/contract/index.js"
click node_witness "https://github.com/slslz/veil-ai/blob/main/witness.ts"
click node_bridge "https://github.com/slslz/veil-ai/blob/main/verificationBridge.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 toneBlue
class node_api,node_policy_route,node_controller,node_parser,node_ai_client toneAmber
class node_criteria,node_execution,node_contract,node_witness,node_bridge toneMint
class node_validator,node_schema,node_policy_types toneRose
class node_verifier,node_llm,node_midnight toneIndigo
```

## Components

### Verifier experience

- [Describe, review, result UI](https://github.com/slslz/veil-ai/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`

### Policy interpretation API

- [Express API](https://github.com/slslz/veil-ai/blob/main/backend/api/app.ts): `backend/api/app.ts`
- [Policy parse route](https://github.com/slslz/veil-ai/blob/main/backend/api/routes/policy.routes.ts): `backend/api/routes/policy.routes.ts`
- [Parse policy handler](https://github.com/slslz/veil-ai/blob/main/backend/api/controllers/policy.controller.ts): `backend/api/controllers/policy.controller.ts`
- [AI policy parser](https://github.com/slslz/veil-ai/blob/main/backend/ai/policy-parser.ts): `backend/ai/policy-parser.ts`
- [Structured AI client](https://github.com/slslz/veil-ai/blob/main/backend/ai/ai-client.ts): `backend/ai/ai-client.ts`

### Private verification

- [Public criteria adapter](https://github.com/slslz/veil-ai/blob/main/backend/midnight/policy-to-criteria.ts): `backend/midnight/policy-to-criteria.ts`
- [Verification execution](https://github.com/slslz/veil-ai/blob/main/mainAPI.ts): `mainAPI.ts`
- [Eligibility circuit runtime](https://github.com/slslz/veil-ai/blob/main/managed/eligibility/contract/index.js): `managed/eligibility/contract/index.js`
- [Private age/income witness](https://github.com/slslz/veil-ai/blob/main/witness.ts): `witness.ts`
- [Verification bridge](https://github.com/slslz/veil-ai/blob/main/verificationBridge.ts): `verificationBridge.ts`

### Policy foundations

- [Policy semantics validator](https://github.com/slslz/veil-ai/blob/main/backend/utils/policy-validator.ts): `backend/utils/policy-validator.ts`
- [Policy schemas](https://github.com/slslz/veil-ai/blob/main/backend/schemas/policy.schema.ts): `backend/schemas/policy.schema.ts`
- [Policy types](https://github.com/slslz/veil-ai/blob/main/backend/types/policy.ts): `backend/types/policy.ts`

### Other components

- **Verifier / applicant**
- **AI LLM provider**
- **Midnight proof infrastructure**

## Connections

- Verifier / applicant → Describe, review, result UI: enters requirement (evidence: `README.md`)
- Describe, review, result UI → Express API: requests policy parse (evidence: `README.md`)
- Express API → Policy parse route: routes policy requests (evidence: `backend/api/app.ts`)
- Policy parse route → Parse policy handler: dispatches parse (evidence: `backend/api/routes/policy.routes.ts`)
- Parse policy handler → AI policy parser: parses requirement (evidence: `backend/api/controllers/policy.controller.ts`)
- AI policy parser → Structured AI client: generates structured policy (evidence: `backend/ai/policy-parser.ts`)
- Structured AI client → AI LLM provider: requests structured output
- AI policy parser → Policy schemas: validates AI output (evidence: `backend/ai/policy-parser.ts`)
- AI policy parser → Policy semantics validator: checks policy semantics (evidence: `backend/ai/policy-parser.ts`)
- Parse policy handler → Policy semantics validator: validates policy semantics (evidence: `backend/api/controllers/policy.controller.ts`)
- Parse policy handler → Public criteria adapter: adapts policy criteria (evidence: `backend/api/controllers/policy.controller.ts`)
- Describe, review, result UI → Verification execution: starts verification
- Public criteria adapter → Verification execution: hands off criteria
- Verification execution → Eligibility circuit runtime: invokes circuit (evidence: `mainAPI.ts`)
- Verification execution → Private age/income witness: supplies private witness (evidence: `mainAPI.ts`)
- Eligibility circuit runtime → Private age/income witness: requests private values (evidence: `managed/eligibility/contract/index.js`)
- Verification execution → Verification bridge: used by bridge (evidence: `verificationBridge.ts`)
- Eligibility circuit runtime → Midnight proof infrastructure: runs proof flow
- Verification execution → Describe, review, result UI: returns result