# akpranav1/liveness_check architecture

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

- Interactive diagram: https://gitdiagram.com/akpranav1/liveness_check
- Repository: https://github.com/akpranav1/liveness_check

## Overview

#### Purpose and Entry Points
Real-time exam proctoring service for identity continuity and liveness/replay detection. The FastAPI application in `main.py` exposes session, baseline, frame, challenge, reporting, and history endpoints. Clients are the browser UI at `static/index.html` and a headless OpenCV runner at `test_harness/run_short_test.py`.

#### Session Lifecycle and API Boundary
`main.py` owns HTTP/form-data handling, JPEG decoding, in-memory session monitor instances, analyzer caching, error-to-inconclusive handling, and persistence calls. A session is created, baseline images are submitted, frames are streamed, optional challenges are issued/evaluated, then the session is ended and queried. The API boundary returns JSON outcomes and newly raised flags; raw image processing stays server-side.
Paths: `main.py`, `static/index.html`, `test_harness/run_short_test.py`.

#### Face Analysis Abstraction
`face_analyzer.py` defines the shared face-analysis contract and `DetectedFace` result: bounding box, embedding, pose, and detection confidence. `InsightFaceAnalyzer` is the intended production backend (InsightFace/ONNX Runtime, model download on first use); `MockFaceAnalyzer` is an offline smoke-test backend using OpenCV detection and texture descriptors. Both feed the same downstream identity logic, allowing runtime model selection without changing monitor code.
Paths: `face_analyzer.py`, `main.py`, `requirements.txt`.

#### Identity Continuity Pillar
`exam_identity_monitor.py` builds a baseline embedding from valid baseline frames, estimates device noise, and evaluates each frame as match, mismatch, or inconclusive. It gates extreme pose, applies pose- and device-noise-adjusted mismatch thresholds, and only admits clear match/mismatch evidence into its rolling window. Identity flags arise from sustained mismatch ratio or consecutive mismatches, never a single frame.
Paths: `exam_identity_monitor.py`, `face_analyzer.py`, `config.py`.

#### Liveness and Active Challenges
`liveness_monitor.py` combines independent replay signals: low face-crop motion for static photos, perceptual-hash periodicity for loops, FFT high-frequency/moiré scoring for screen recapture, and active raise-hand/head-turn challenges. Suspicious liveness evidence is fused with OR semantics and then debounced through a rolling window. Challenge failure/no response produces a separate flag; head-turn evaluation depends on real pose output, while hand raise uses optional MediaPipe.
Paths: `liveness_monitor.py`, `exam_identity_monitor.py`, `config.py`.

#### Composition and Frame Flow
`FullExamSessionMonitor` in `session_monitor.py` composes the identity monitor with the liveness mixin. Per submitted frame: decode at API layer; analyze face once; classify identity; update identity evidence; reuse detected face bounds/count for liveness checks when exactly one valid face exists; append resulting flags; return the result. No-face and multi-face frames are inconclusive for identity and skip liveness face analysis, avoiding ambiguous evidence and duplicate detection.
Paths: `session_monitor.py`, `exam_identity_monitor.py`, `liveness_monitor.py`.

#### Persistence, Configuration, and Deployment Constraints
`database.py` persists SQLite session metadata, per-frame outcomes, flags, and challenge events; it is a single-server/local-file persistence boundary rather than distributed infrastructure. `config.py` centralizes production and compressed test profiles for windows, thresholds, timing, and challenge behavior. Runtime dependencies are Python/FastAPI/Uvicorn, OpenCV/Numpy, SQLite stdlib, and optionally InsightFace, ONNX Runtime, and MediaPipe; model acquisition may require external network access.
Paths: `database.py`, `config.py`, `requirements.txt`.

Main entry points: [`main.py`](https://github.com/akpranav1/liveness_check/blob/main/main.py) (FastAPI app), [`face_analyzer.py`](https://github.com/akpranav1/liveness_check/blob/main/face_analyzer.py) (Face analysis contract), [`session_monitor.py`](https://github.com/akpranav1/liveness_check/blob/main/session_monitor.py) (Full session monitor), [`liveness_monitor.py`](https://github.com/akpranav1/liveness_check/blob/main/liveness_monitor.py) (Liveness monitor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Clients"]
  node_browser["Browser UI<br/>web client<br/>[index.html]"]
  node_harness["OpenCV runner<br/>headless client<br/>[run_short_test.py]"]
end

subgraph group_api["API &amp; Session Runtime"]
  node_api_app["FastAPI app<br/>HTTP API<br/>[main.py]"]
  node_session_monitor["Full session monitor<br/>session orchestrator<br/>[session_monitor.py]"]
end

subgraph group_analysis["Face Analysis"]
  node_face_contract["Face analysis contract<br/>analyzer interface<br/>[face_analyzer.py]"]
  node_insightface["InsightFace backend<br/>production analyzer<br/>[face_analyzer.py]"]
  node_mock_analyzer["Mock backend<br/>offline analyzer<br/>[face_analyzer.py]"]
end

subgraph group_monitoring["Monitoring Pipeline"]
  node_identity_monitor["Identity monitor<br/>continuity engine"]
  node_liveness_monitor["Liveness monitor<br/>replay and challenge engine"]
end

subgraph group_storage["Persistence &amp; Settings"]
  node_database[("SQLite persistence<br/>local database<br/>[database.py]")]
  node_config["Runtime profiles<br/>configuration<br/>[config.py]"]
  node_dependencies["Runtime dependencies<br/>Python packages<br/>[requirements.txt]"]
end

node_browser -->|"session, baseline, frames"| node_api_app
node_harness -->|"automated frame stream"| node_api_app
node_api_app -->|"decoded frames and lifecycle"| node_session_monitor
node_api_app -->|"selects and caches analyzer"| node_face_contract
node_api_app -->|"persists outcomes"| node_database
node_session_monitor -->|"analyze once per frame"| node_face_contract
node_session_monitor -->|"identity classification and evidence"| node_identity_monitor
node_session_monitor -->|"valid single-face evidence"| node_liveness_monitor
node_identity_monitor -->|"shared identity and pose context"| node_liveness_monitor
node_insightface -->|"implements"| node_face_contract
node_mock_analyzer -->|"implements"| node_face_contract
node_identity_monitor -->|"thresholds and windows"| node_config
node_liveness_monitor -->|"challenge and replay settings"| node_config
node_face_contract -.->|"optional model runtimes"| node_dependencies
node_liveness_monitor -.->|"optional MediaPipe"| node_dependencies

click node_browser "https://github.com/akpranav1/liveness_check/blob/main/static/index.html"
click node_harness "https://github.com/akpranav1/liveness_check/blob/main/test_harness/run_short_test.py"
click node_api_app "https://github.com/akpranav1/liveness_check/blob/main/main.py"
click node_session_monitor "https://github.com/akpranav1/liveness_check/blob/main/session_monitor.py"
click node_face_contract "https://github.com/akpranav1/liveness_check/blob/main/face_analyzer.py"
click node_insightface "https://github.com/akpranav1/liveness_check/blob/main/face_analyzer.py"
click node_mock_analyzer "https://github.com/akpranav1/liveness_check/blob/main/face_analyzer.py"
click node_identity_monitor "https://github.com/akpranav1/liveness_check/blob/main/exam_identity_monitor.py"
click node_liveness_monitor "https://github.com/akpranav1/liveness_check/blob/main/liveness_monitor.py"
click node_database "https://github.com/akpranav1/liveness_check/blob/main/database.py"
click node_config "https://github.com/akpranav1/liveness_check/blob/main/config.py"
click node_dependencies "https://github.com/akpranav1/liveness_check/blob/main/requirements.txt"

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_browser,node_harness toneBlue
class node_api_app,node_session_monitor toneAmber
class node_face_contract,node_insightface,node_mock_analyzer toneMint
class node_identity_monitor,node_liveness_monitor toneRose
class node_database,node_config,node_dependencies toneIndigo
```

## Components

### Clients

- [Browser UI](https://github.com/akpranav1/liveness_check/blob/main/static/index.html): web client · `static/index.html`
- [OpenCV runner](https://github.com/akpranav1/liveness_check/blob/main/test_harness/run_short_test.py): headless client · `test_harness/run_short_test.py`

### API & Session Runtime

- [FastAPI app](https://github.com/akpranav1/liveness_check/blob/main/main.py): HTTP API · Owns decoding, session instances, analyzer caching, and JSON outcomes. · `main.py`
- [Full session monitor](https://github.com/akpranav1/liveness_check/blob/main/session_monitor.py): session orchestrator · Analyzes each frame once and combines identity and liveness results. · `session_monitor.py`

### Face Analysis

- [Face analysis contract](https://github.com/akpranav1/liveness_check/blob/main/face_analyzer.py): analyzer interface · Produces face bounds, embeddings, pose, and confidence. · `face_analyzer.py`
- [InsightFace backend](https://github.com/akpranav1/liveness_check/blob/main/face_analyzer.py): production analyzer · Uses InsightFace and ONNX Runtime models. · `face_analyzer.py`
- [Mock backend](https://github.com/akpranav1/liveness_check/blob/main/face_analyzer.py): offline analyzer · Uses OpenCV detection and texture descriptors for smoke tests. · `face_analyzer.py`

### Monitoring Pipeline

- [Identity monitor](https://github.com/akpranav1/liveness_check/blob/main/exam_identity_monitor.py): continuity engine · Builds baselines and debounces pose- and noise-adjusted mismatch evidence. · `exam_identity_monitor.py`
- [Liveness monitor](https://github.com/akpranav1/liveness_check/blob/main/liveness_monitor.py): replay and challenge engine · Fuses replay signals and evaluates hand-raise or head-turn challenges. · `liveness_monitor.py`

### Persistence & Settings

- [SQLite persistence](https://github.com/akpranav1/liveness_check/blob/main/database.py): local database · Stores sessions, frame outcomes, flags, and challenge events. · `database.py`
- [Runtime profiles](https://github.com/akpranav1/liveness_check/blob/main/config.py): configuration · Centralizes production and compressed-test thresholds, windows, and timing. · `config.py`
- [Runtime dependencies](https://github.com/akpranav1/liveness_check/blob/main/requirements.txt): Python packages · FastAPI, OpenCV, optional model runtimes, and MediaPipe. · `requirements.txt`

## Connections

- Browser UI → FastAPI app: session, baseline, frames
- OpenCV runner → FastAPI app: automated frame stream
- FastAPI app → Full session monitor: decoded frames and lifecycle
- FastAPI app → Face analysis contract: selects and caches analyzer
- FastAPI app → SQLite persistence: persists outcomes
- Full session monitor → Face analysis contract: analyze once per frame
- Full session monitor → Identity monitor: identity classification and evidence
- Full session monitor → Liveness monitor: valid single-face evidence
- Identity monitor → Liveness monitor: shared identity and pose context
- InsightFace backend → Face analysis contract: implements
- Mock backend → Face analysis contract: implements
- Identity monitor → Runtime profiles: thresholds and windows
- Liveness monitor → Runtime profiles: challenge and replay settings
- Face analysis contract → Runtime dependencies: optional model runtimes
- Liveness monitor → Runtime dependencies: optional MediaPipe