# ibonly/verifypass architecture

> Architecture diagram of the GitHub repository ibonly/verifypass, 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/ibonly/verifypass
- Repository: https://github.com/ibonly/verifypass

## Overview

Verix is a multitenant liveness, face-recognition, and ID-verification service. A tenant creates a verification session; an end user captures documents and liveness evidence through the SDK or hosted flow; the API stores evidence and queues work; a worker evaluates the attempt and produces a decision that tenants can review in the dashboard or retrieve through the API. The README also documents onboarding, reports, settings, and signed webhook delivery. Some route-to-service and client-to-API details are unsampled, so those links are marked unverified.

Main entry points: [`backend/src/worker/pipeline.js`](https://github.com/ibonly/verifypass/blob/dev/backend/src/worker/pipeline.js) (Verification pipeline), [`frontend/dashboard/src/App.jsx`](https://github.com/ibonly/verifypass/blob/dev/frontend/dashboard/src/App.jsx) (Tenant dashboard), [`frontend/sdk/react/src/VerificationWidget.jsx`](https://github.com/ibonly/verifypass/blob/dev/frontend/sdk/react/src/VerificationWidget.jsx) (Verification widget), [`backend/src/app.js`](https://github.com/ibonly/verifypass/blob/dev/backend/src/app.js) (Express API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client capture"]
  node_sdk["Capture SDK<br/>[client.js]"]
  node_widget["Verification widget"]
  node_hosted["Hosted flow<br/>[App.jsx]"]
end

subgraph group_api["Tenant API"]
  node_apiapp["Express API<br/>[app.js]"]
  node_sessions["Session lifecycle<br/>[sessionService.js]"]
  node_uploads["Evidence uploads<br/>[uploadService.js]"]
  node_database[("MongoDB<br/>[db.js]")]
  node_jobqueue["Job dispatch<br/>[jobService.js]"]
end

subgraph group_processing["Verification processing"]
  node_worker["Worker runtime<br/>[worker.js]"]
  node_pipeline["Verification pipeline<br/>[pipeline.js]"]
  node_decision["Decision engine<br/>[decisionEngine.js]"]
  node_screening["Risk screening<br/>[screening.js]"]
  node_providers["Biometric providers"]
end

subgraph group_operations["Tenant operations"]
  node_dashboard["Tenant dashboard<br/>[App.jsx]"]
  node_review["Manual review<br/>[review.js]"]
  node_reports["Reports and settings<br/>[reports.js]"]
  node_webhookconfig["Webhook configuration<br/>[webhooks.js]"]
end

subgraph group_integrations["External delivery"]
  node_dispatcher["Webhook delivery"]
  node_receiver["Tenant webhook receiver"]
  node_email["Transactional email<br/>[emailService.js]"]
end

node_tenant(("Tenant integrator"))
node_enduser(("End user"))

node_tenant -.->|"creates sessions"| node_sessions
node_enduser -.->|"completes capture"| node_widget
node_widget -.->|"uses client"| node_sdk
node_widget -.->|"uploads evidence"| node_apiapp
node_hosted -.->|"hosts flow"| node_widget
node_apiapp -->|"mounts session routes"| node_sessions
node_apiapp -->|"mounts capture routes"| node_uploads
node_sessions -->|"enqueues work"| node_jobqueue
node_sessions -.->|"reads and writes"| node_database
node_uploads -.->|"stores evidence metadata"| node_database
node_jobqueue -->|"dispatches jobs"| node_worker
node_worker -->|"runs pipeline"| node_pipeline
node_pipeline -->|"decides outcome"| node_decision
node_pipeline -->|"screens identity"| node_screening
node_pipeline -.->|"uses providers"| node_providers
node_pipeline -.->|"loads and finalizes"| node_database
node_dashboard -.->|"calls tenant API"| node_apiapp
node_dashboard -.->|"submits decisions"| node_review
node_dashboard -.->|"manages reports"| node_reports
node_dashboard -->|"configures webhooks"| node_webhookconfig
node_webhookconfig -.->|"configures delivery"| node_dispatcher
node_dispatcher -.->|"sends signed events"| node_receiver
node_dispatcher -.->|"uses email service"| node_email

click node_sdk "https://github.com/ibonly/verifypass/blob/dev/frontend/sdk/core/src/client.js"
click node_widget "https://github.com/ibonly/verifypass/blob/dev/frontend/sdk/react/src/VerificationWidget.jsx"
click node_hosted "https://github.com/ibonly/verifypass/blob/dev/frontend/verify-page/src/App.jsx"
click node_apiapp "https://github.com/ibonly/verifypass/blob/dev/backend/src/app.js"
click node_sessions "https://github.com/ibonly/verifypass/blob/dev/backend/src/services/sessionService.js"
click node_uploads "https://github.com/ibonly/verifypass/blob/dev/backend/src/services/uploadService.js"
click node_database "https://github.com/ibonly/verifypass/blob/dev/backend/src/lib/db.js"
click node_jobqueue "https://github.com/ibonly/verifypass/blob/dev/backend/src/services/jobService.js"
click node_worker "https://github.com/ibonly/verifypass/blob/dev/backend/worker.js"
click node_pipeline "https://github.com/ibonly/verifypass/blob/dev/backend/src/worker/pipeline.js"
click node_decision "https://github.com/ibonly/verifypass/blob/dev/backend/shared/src/decisionEngine.js"
click node_screening "https://github.com/ibonly/verifypass/blob/dev/backend/src/worker/screening.js"
click node_providers "https://github.com/ibonly/verifypass/tree/dev/backend/src/worker/providers"
click node_dashboard "https://github.com/ibonly/verifypass/blob/dev/frontend/dashboard/src/App.jsx"
click node_review "https://github.com/ibonly/verifypass/blob/dev/backend/src/routes/review.js"
click node_reports "https://github.com/ibonly/verifypass/blob/dev/backend/src/routes/reports.js"
click node_webhookconfig "https://github.com/ibonly/verifypass/blob/dev/backend/src/routes/webhooks.js"
click node_dispatcher "https://github.com/ibonly/verifypass/blob/dev/backend/src/worker/webhookDispatcher.js"
click node_email "https://github.com/ibonly/verifypass/blob/dev/backend/src/services/emailService.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_sdk,node_widget,node_hosted,node_enduser toneBlue
class node_apiapp,node_sessions,node_uploads,node_database,node_jobqueue toneAmber
class node_worker,node_pipeline,node_decision,node_screening,node_providers toneMint
class node_dashboard,node_review,node_reports,node_webhookconfig toneRose
class node_dispatcher,node_receiver,node_email,node_tenant toneIndigo
```

## Components

### Client capture

- [Capture SDK](https://github.com/ibonly/verifypass/blob/dev/frontend/sdk/core/src/client.js): `frontend/sdk/core/src/client.js`
- [Verification widget](https://github.com/ibonly/verifypass/blob/dev/frontend/sdk/react/src/VerificationWidget.jsx): `frontend/sdk/react/src/VerificationWidget.jsx`
- [Hosted flow](https://github.com/ibonly/verifypass/blob/dev/frontend/verify-page/src/App.jsx): `frontend/verify-page/src/App.jsx`

### Tenant API

- [Express API](https://github.com/ibonly/verifypass/blob/dev/backend/src/app.js): `backend/src/app.js`
- [Session lifecycle](https://github.com/ibonly/verifypass/blob/dev/backend/src/services/sessionService.js): `backend/src/services/sessionService.js`
- [Evidence uploads](https://github.com/ibonly/verifypass/blob/dev/backend/src/services/uploadService.js): `backend/src/services/uploadService.js`
- [MongoDB](https://github.com/ibonly/verifypass/blob/dev/backend/src/lib/db.js): `backend/src/lib/db.js`
- [Job dispatch](https://github.com/ibonly/verifypass/blob/dev/backend/src/services/jobService.js): `backend/src/services/jobService.js`

### Verification processing

- [Worker runtime](https://github.com/ibonly/verifypass/blob/dev/backend/worker.js): `backend/worker.js`
- [Verification pipeline](https://github.com/ibonly/verifypass/blob/dev/backend/src/worker/pipeline.js): `backend/src/worker/pipeline.js`
- [Decision engine](https://github.com/ibonly/verifypass/blob/dev/backend/shared/src/decisionEngine.js): `backend/shared/src/decisionEngine.js`
- [Risk screening](https://github.com/ibonly/verifypass/blob/dev/backend/src/worker/screening.js): `backend/src/worker/screening.js`
- [Biometric providers](https://github.com/ibonly/verifypass/tree/dev/backend/src/worker/providers): `backend/src/worker/providers`

### Tenant operations

- [Tenant dashboard](https://github.com/ibonly/verifypass/blob/dev/frontend/dashboard/src/App.jsx): `frontend/dashboard/src/App.jsx`
- [Manual review](https://github.com/ibonly/verifypass/blob/dev/backend/src/routes/review.js): `backend/src/routes/review.js`
- [Reports and settings](https://github.com/ibonly/verifypass/blob/dev/backend/src/routes/reports.js): `backend/src/routes/reports.js`
- [Webhook configuration](https://github.com/ibonly/verifypass/blob/dev/backend/src/routes/webhooks.js): `backend/src/routes/webhooks.js`

### External delivery

- [Webhook delivery](https://github.com/ibonly/verifypass/blob/dev/backend/src/worker/webhookDispatcher.js): `backend/src/worker/webhookDispatcher.js`
- **Tenant webhook receiver**
- [Transactional email](https://github.com/ibonly/verifypass/blob/dev/backend/src/services/emailService.js): `backend/src/services/emailService.js`

### Other components

- **Tenant integrator**
- **End user**

## Connections

- Tenant integrator → Session lifecycle: creates sessions (evidence: `README.md`)
- End user → Verification widget: completes capture (evidence: `README.md`)
- Verification widget → Capture SDK: uses client (evidence: `README.md`)
- Verification widget → Express API: uploads evidence (evidence: `README.md`)
- Hosted flow → Verification widget: hosts flow (evidence: `README.md`)
- Express API → Session lifecycle: mounts session routes (evidence: `backend/src/app.js`)
- Express API → Evidence uploads: mounts capture routes (evidence: `backend/src/app.js`)
- Session lifecycle → Job dispatch: enqueues work (evidence: `backend/src/services/sessionService.js`)
- Session lifecycle → MongoDB: reads and writes
- Evidence uploads → MongoDB: stores evidence metadata
- Job dispatch → Worker runtime: dispatches jobs (evidence: `backend/src/services/jobService.js`)
- Worker runtime → Verification pipeline: runs pipeline (evidence: `backend/worker.js`)
- Verification pipeline → Decision engine: decides outcome (evidence: `backend/src/worker/pipeline.js`)
- Verification pipeline → Risk screening: screens identity (evidence: `backend/src/worker/pipeline.js`)
- Verification pipeline → Biometric providers: uses providers
- Verification pipeline → MongoDB: loads and finalizes (evidence: `backend/src/worker/pipeline.js`)
- Tenant dashboard → Express API: calls tenant API
- Tenant dashboard → Manual review: submits decisions (evidence: `frontend/dashboard/src/App.jsx`)
- Tenant dashboard → Reports and settings: manages reports (evidence: `README.md`)
- Tenant dashboard → Webhook configuration: configures webhooks (evidence: `frontend/dashboard/src/App.jsx`)
- Webhook configuration → Webhook delivery: configures delivery
- Webhook delivery → Tenant webhook receiver: sends signed events (evidence: `README.md`)
- Webhook delivery → Transactional email: uses email service (evidence: `backend/src/worker/webhookDispatcher.js`)