# johnpaulpatigas/liveness architecture

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

## Overview

Liveness SDK combines browser-side challenge and face verification with a SaaS console and API for account, key, enrollment, verification, and log management. The user flow runs camera input through the SDK and vision engine to a descriptor; API-key clients can submit verification operations to the backend, while console users manage credentials and review results. The graph preserves major documented capabilities and sampled module relationships. Some web-page/API and backend route wiring is unsampled, so those links are omitted rather than inferred.

Main entry points: [`apps/saas-web/src/App.jsx`](https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-web/src/App.jsx) (Console routing), [`apps/saas-web/src/pages/Documentation.jsx`](https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-web/src/pages/Documentation.jsx) (Documentation), [`apps/saas-api/src/controllers/auth.controller.js`](https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-api/src/controllers/auth.controller.js) (Account controller), [`apps/saas-api/src/services/auth.service.js`](https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-api/src/services/auth.service.js) (Account service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser verification"]
  node_sdk["SDK wrapper<br/>[LivenessSDK.js]"]
end

subgraph group_console["SaaS console"]
  node_console_app["Console routing<br/>[App.jsx]"]
  node_api_client["API client<br/>[api.js]"]
  node_dashboard["Dashboard<br/>[Dashboard.jsx]"]
  node_api_keys_ui["API key management<br/>[ApiKeys.jsx]"]
  node_logs_ui["Verification logs<br/>[Logs.jsx]"]
  node_users_ui["User management<br/>[Users.jsx]"]
  node_settings_ui["Account settings<br/>[Settings.jsx]"]
  node_docs_ui["Documentation<br/>[Documentation.jsx]"]
  node_landing_ui["Landing page<br/>[Landing.jsx]"]
  node_signup_ui["Signup<br/>[Signup.jsx]"]
  node_navbar["Navigation<br/>[Navbar.jsx]"]
  node_dashboard_layout["Dashboard layout"]
end

subgraph group_api["SaaS API"]
  node_api_routes["API route dispatch<br/>[liveness.routes.js]"]
  node_auth_routes["Account routes<br/>[auth.routes.js]"]
  node_live_controller["Verification controller"]
  node_auth_controller["Account controller<br/>[auth.controller.js]"]
  node_auth_service["Account service<br/>[auth.service.js]"]
  node_live_service["Verification service"]
  node_key_service["API key service<br/>[api-key.service.js]"]
  node_auth_middleware["Authentication<br/>[auth.js]"]
  node_cookie["Cookie options<br/>[cookie.js]"]
end

subgraph group_vision["Vision engine"]
  node_engine["Challenge engine<br/>[LivenessEngine.js]"]
  node_recognition["Face recognition"]
  node_vision_utils["Vision utilities<br/>[utils.js]"]
end

subgraph group_storage["Persistence"]
  node_auth_repo["Account repository<br/>[auth.repository.js]"]
  node_live_repo["Verification repository"]
  node_key_repo["API key repository"]
  node_postgres[("PostgreSQL<br/>[db.js]")]
end

node_user(("End user"))
node_client_app(("Integrating application"))
node_api_user(("API client"))
node_email["Email service"]

node_user -->|"starts verification"| node_sdk
node_sdk -->|"delegates to"| node_engine
node_engine -->|"loads model"| node_recognition
node_engine -->|"calculates checks"| node_vision_utils
node_client_app -->|"integrates"| node_sdk
node_console_app -->|"routes to"| node_dashboard
node_console_app -->|"routes to"| node_api_keys_ui
node_console_app -->|"routes to"| node_docs_ui
node_console_app -->|"routes to"| node_landing_ui
node_console_app -->|"routes to"| node_signup_ui
node_console_app -->|"routes to"| node_logs_ui
node_console_app -->|"routes to"| node_users_ui
node_console_app -->|"routes to"| node_settings_ui
node_dashboard_layout -->|"requests through"| node_api_client
node_docs_ui -->|"uses"| node_dashboard_layout
node_docs_ui -->|"renders"| node_navbar
node_dashboard -->|"requests through"| node_api_client
node_api_client -->|"sends HTTP requests"| node_api_user
node_api_user -.->|"calls verification API"| node_api_routes
node_api_routes -->|"dispatches to"| node_live_controller
node_auth_routes -->|"dispatches to"| node_auth_controller
node_live_controller -->|"calls"| node_live_service
node_auth_controller -->|"calls"| node_auth_service
node_auth_controller -->|"configures cookies"| node_cookie
node_auth_service -->|"reads and writes"| node_auth_repo
node_auth_service -->|"sends reset email"| node_email
node_live_service -->|"persists verification data"| node_live_repo
node_key_service -->|"uses repository"| node_key_repo
node_auth_middleware -->|"validates API keys"| node_key_service
node_auth_middleware -->|"checks token version"| node_auth_repo
node_auth_repo -->|"queries"| node_postgres

click node_sdk "https://github.com/johnpaulpatigas/liveness/blob/main/packages/sdk/src/LivenessSDK.js"
click node_engine "https://github.com/johnpaulpatigas/liveness/blob/main/packages/engine/src/LivenessEngine.js"
click node_recognition "https://github.com/johnpaulpatigas/liveness/blob/main/packages/engine/src/FaceRecognitionNet.js"
click node_vision_utils "https://github.com/johnpaulpatigas/liveness/blob/main/packages/engine/src/utils.js"
click node_console_app "https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-web/src/App.jsx"
click node_api_client "https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-web/src/services/api.js"
click node_dashboard "https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-web/src/pages/Dashboard.jsx"
click node_api_keys_ui "https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-web/src/pages/ApiKeys.jsx"
click node_logs_ui "https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-web/src/pages/Logs.jsx"
click node_users_ui "https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-web/src/pages/Users.jsx"
click node_settings_ui "https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-web/src/pages/Settings.jsx"
click node_docs_ui "https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-web/src/pages/Documentation.jsx"
click node_landing_ui "https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-web/src/pages/Landing.jsx"
click node_signup_ui "https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-web/src/pages/Signup.jsx"
click node_navbar "https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-web/src/components/Navbar.jsx"
click node_dashboard_layout "https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-web/src/layouts/DashboardLayout.jsx"
click node_api_routes "https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-api/src/routes/liveness.routes.js"
click node_auth_routes "https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-api/src/routes/auth.routes.js"
click node_live_controller "https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-api/src/controllers/liveness.controller.js"
click node_auth_controller "https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-api/src/controllers/auth.controller.js"
click node_auth_service "https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-api/src/services/auth.service.js"
click node_live_service "https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-api/src/services/liveness.services.js"
click node_key_service "https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-api/src/services/api-key.service.js"
click node_auth_middleware "https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-api/src/middleware/auth.js"
click node_cookie "https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-api/src/utils/cookie.js"
click node_auth_repo "https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-api/src/repositories/auth.repository.js"
click node_live_repo "https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-api/src/repositories/liveness.repository.js"
click node_key_repo "https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-api/src/repositories/api-key.repository.js"
click node_postgres "https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-api/src/db.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_user,node_api_user toneBlue
class node_console_app,node_api_client,node_dashboard,node_api_keys_ui,node_logs_ui,node_users_ui,node_settings_ui,node_docs_ui,node_landing_ui,node_signup_ui,node_navbar,node_dashboard_layout toneAmber
class node_api_routes,node_auth_routes,node_live_controller,node_auth_controller,node_auth_service,node_live_service,node_key_service,node_auth_middleware,node_cookie toneMint
class node_engine,node_recognition,node_vision_utils toneRose
class node_auth_repo,node_live_repo,node_key_repo,node_postgres,node_client_app,node_email toneIndigo
```

## Components

### Browser verification

- [SDK wrapper](https://github.com/johnpaulpatigas/liveness/blob/main/packages/sdk/src/LivenessSDK.js): `packages/sdk/src/LivenessSDK.js`

### SaaS console

- [Console routing](https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-web/src/App.jsx): `apps/saas-web/src/App.jsx`
- [API client](https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-web/src/services/api.js): `apps/saas-web/src/services/api.js`
- [Dashboard](https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-web/src/pages/Dashboard.jsx): `apps/saas-web/src/pages/Dashboard.jsx`
- [API key management](https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-web/src/pages/ApiKeys.jsx): `apps/saas-web/src/pages/ApiKeys.jsx`
- [Verification logs](https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-web/src/pages/Logs.jsx): `apps/saas-web/src/pages/Logs.jsx`
- [User management](https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-web/src/pages/Users.jsx): `apps/saas-web/src/pages/Users.jsx`
- [Account settings](https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-web/src/pages/Settings.jsx): `apps/saas-web/src/pages/Settings.jsx`
- [Documentation](https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-web/src/pages/Documentation.jsx): `apps/saas-web/src/pages/Documentation.jsx`
- [Landing page](https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-web/src/pages/Landing.jsx): `apps/saas-web/src/pages/Landing.jsx`
- [Signup](https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-web/src/pages/Signup.jsx): `apps/saas-web/src/pages/Signup.jsx`
- [Navigation](https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-web/src/components/Navbar.jsx): `apps/saas-web/src/components/Navbar.jsx`
- [Dashboard layout](https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-web/src/layouts/DashboardLayout.jsx): `apps/saas-web/src/layouts/DashboardLayout.jsx`

### SaaS API

- [API route dispatch](https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-api/src/routes/liveness.routes.js): `apps/saas-api/src/routes/liveness.routes.js`
- [Account routes](https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-api/src/routes/auth.routes.js): `apps/saas-api/src/routes/auth.routes.js`
- [Verification controller](https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-api/src/controllers/liveness.controller.js): `apps/saas-api/src/controllers/liveness.controller.js`
- [Account controller](https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-api/src/controllers/auth.controller.js): `apps/saas-api/src/controllers/auth.controller.js`
- [Account service](https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-api/src/services/auth.service.js): `apps/saas-api/src/services/auth.service.js`
- [Verification service](https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-api/src/services/liveness.services.js): `apps/saas-api/src/services/liveness.services.js`
- [API key service](https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-api/src/services/api-key.service.js): `apps/saas-api/src/services/api-key.service.js`
- [Authentication](https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-api/src/middleware/auth.js): `apps/saas-api/src/middleware/auth.js`
- [Cookie options](https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-api/src/utils/cookie.js): `apps/saas-api/src/utils/cookie.js`

### Vision engine

- [Challenge engine](https://github.com/johnpaulpatigas/liveness/blob/main/packages/engine/src/LivenessEngine.js): `packages/engine/src/LivenessEngine.js`
- [Face recognition](https://github.com/johnpaulpatigas/liveness/blob/main/packages/engine/src/FaceRecognitionNet.js): `packages/engine/src/FaceRecognitionNet.js`
- [Vision utilities](https://github.com/johnpaulpatigas/liveness/blob/main/packages/engine/src/utils.js): `packages/engine/src/utils.js`

### Persistence

- [Account repository](https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-api/src/repositories/auth.repository.js): `apps/saas-api/src/repositories/auth.repository.js`
- [Verification repository](https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-api/src/repositories/liveness.repository.js): `apps/saas-api/src/repositories/liveness.repository.js`
- [API key repository](https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-api/src/repositories/api-key.repository.js): `apps/saas-api/src/repositories/api-key.repository.js`
- [PostgreSQL](https://github.com/johnpaulpatigas/liveness/blob/main/apps/saas-api/src/db.js): `apps/saas-api/src/db.js`

### Other components

- **End user**
- **Integrating application**
- **API client**
- **Email service**

## Connections

- End user → SDK wrapper: starts verification (evidence: `README.md`)
- SDK wrapper → Challenge engine: delegates to (evidence: `packages/sdk/src/LivenessSDK.js`)
- Challenge engine → Face recognition: loads model (evidence: `packages/engine/src/LivenessEngine.js`)
- Challenge engine → Vision utilities: calculates checks (evidence: `packages/engine/src/LivenessEngine.js`)
- Integrating application → SDK wrapper: integrates (evidence: `README.md`)
- Console routing → Dashboard: routes to (evidence: `apps/saas-web/src/App.jsx`)
- Console routing → API key management: routes to (evidence: `apps/saas-web/src/App.jsx`)
- Console routing → Documentation: routes to (evidence: `apps/saas-web/src/App.jsx`)
- Console routing → Landing page: routes to (evidence: `apps/saas-web/src/App.jsx`)
- Console routing → Signup: routes to (evidence: `apps/saas-web/src/App.jsx`)
- Console routing → Verification logs: routes to (evidence: `apps/saas-web/src/App.jsx`)
- Console routing → User management: routes to (evidence: `apps/saas-web/src/App.jsx`)
- Console routing → Account settings: routes to (evidence: `apps/saas-web/src/App.jsx`)
- Dashboard layout → API client: requests through (evidence: `apps/saas-web/src/layouts/DashboardLayout.jsx`)
- Documentation → Dashboard layout: uses (evidence: `apps/saas-web/src/pages/Documentation.jsx`)
- Documentation → Navigation: renders (evidence: `apps/saas-web/src/pages/Documentation.jsx`)
- Dashboard → API client: requests through (evidence: `apps/saas-web/src/pages/Dashboard.jsx`)
- API client → API client: sends HTTP requests (evidence: `apps/saas-web/src/services/api.js`)
- API client → API route dispatch: calls verification API
- API route dispatch → Verification controller: dispatches to (evidence: `apps/saas-api/src/routes/liveness.routes.js`)
- Account routes → Account controller: dispatches to (evidence: `apps/saas-api/src/routes/auth.routes.js`)
- Verification controller → Verification service: calls (evidence: `apps/saas-api/src/controllers/liveness.controller.js`)
- Account controller → Account service: calls (evidence: `apps/saas-api/src/controllers/auth.controller.js`)
- Account controller → Cookie options: configures cookies (evidence: `apps/saas-api/src/controllers/auth.controller.js`)
- Account service → Account repository: reads and writes (evidence: `apps/saas-api/src/services/auth.service.js`)
- Account service → Email service: sends reset email (evidence: `apps/saas-api/src/services/auth.service.js`)
- Verification service → Verification repository: persists verification data (evidence: `apps/saas-api/src/services/liveness.services.js`)
- API key service → API key repository: uses repository (evidence: `apps/saas-api/src/services/api-key.service.js`)
- Authentication → API key service: validates API keys (evidence: `apps/saas-api/src/middleware/auth.js`)
- Authentication → Account repository: checks token version (evidence: `apps/saas-api/src/middleware/auth.js`)
- Account repository → PostgreSQL: queries (evidence: `apps/saas-api/src/repositories/auth.repository.js`)
