# varad2343/proctor-lens- architecture

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

- Interactive diagram: https://gitdiagram.com/varad2343/proctor-lens-
- Repository: https://github.com/varad2343/proctor-lens-

## Overview

ProctorLens turns webcam or video input into timestamped, explainable observations, not judgments. Its principal workflow is capture or replay → per-frame perception and quality checks → 10 Hz feature rows → temporal scores and event state machines → persisted events and review materials. The same pipeline is exposed through CLI commands and a local candidate/proctor web app; separate data, training, and evaluation modules support the ML lifecycle. Edges reflect README statements and SOURCE INDEX references; unsampled modules are represented only where the tree and documented capabilities support them.

Main entry points: [`src/proctorlens/perception/__init__.py`](https://github.com/varad2343/proctor-lens-/blob/main/src/proctorlens/perception/__init__.py) (Frame perception), [`src/proctorlens/features/extractor.py`](https://github.com/varad2343/proctor-lens-/blob/main/src/proctorlens/features/extractor.py) (Feature extraction), [`src/proctorlens/cli.py`](https://github.com/varad2343/proctor-lens-/blob/main/src/proctorlens/cli.py) (CLI commands), [`src/proctorlens/server/app.py`](https://github.com/varad2343/proctor-lens-/blob/main/src/proctorlens/server/app.py) (HTTP and live sessions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Pipeline runtime"]
  node_cli["CLI commands<br/>[cli.py]"]
  node_calibration["Gaze calibration<br/>[calibration.py]"]
  node_perception["Frame perception<br/>[__init__.py]"]
  node_landmarks["Face landmarks<br/>[landmarks.py]"]
  node_gaze["Gaze estimation<br/>[gaze.py]"]
  node_objects["Object detection<br/>[objects.py]"]
  node_identity["Identity checks<br/>[identity.py]"]
  node_quality["Observation quality<br/>[quality.py]"]
  node_features["Feature extraction<br/>[extractor.py]"]
  node_schema["Feature schema<br/>[schema.py]"]
  node_temporal["Temporal scoring<br/>[scores_learned.py]"]
  node_state["Event state machines<br/>[state_machine.py]"]
  node_io["Feature and event files<br/>[io.py]"]
end

subgraph group_review["Review and reporting"]
  node_reports["Reports and evidence<br/>[report.py]"]
  node_segments["Review segments<br/>[review.py]"]
end

subgraph group_web["Local web app"]
  node_server["HTTP and live sessions<br/>[app.py]"]
  node_database[("Session database<br/>[db.py]")]
  node_live["Live processing<br/>[live.py]"]
  node_candidateui["Candidate exam page<br/>[Candidate.tsx]"]
  node_proctorui["Proctor dashboard<br/>[Proctor.tsx]"]
  node_reviewui["Review interface<br/>[Review.tsx]"]
  node_frontendlib["Web API and stream<br/>[lib.ts]"]
end

subgraph group_ml["ML lifecycle"]
  node_labels["Dataset labels<br/>[labels.py]"]
  node_manifest["Dataset manifest<br/>[build_manifest.py]"]
  node_training["Model training"]
  node_identitytraining["Identity calibration"]
  node_evaluation["Model evaluation<br/>[run_eval.py]"]
end

node_operator(("Operator"))
node_candidate(("Candidate"))
node_video["Video or camera"]

node_operator -->|"runs commands"| node_cli
node_video -->|"provides input"| node_cli
node_cli -->|"starts calibration"| node_calibration
node_calibration -->|"fits calibration"| node_gaze
node_cli -->|"configures perception"| node_perception
node_perception -->|"detects faces"| node_landmarks
node_perception -->|"detects objects"| node_objects
node_perception -->|"checks identity"| node_identity
node_perception -->|"assesses quality"| node_quality
node_features -->|"uses gaze signals"| node_gaze
node_features -->|"builds rows"| node_schema
node_video -->|"frames enter"| node_perception
node_perception -->|"produces observations"| node_features
node_features -->|"scores rows"| node_temporal
node_temporal -->|"feeds scores"| node_state
node_state -->|"writes events"| node_io
node_features -->|"writes features"| node_io
node_cli -->|"generates reports"| node_reports
node_reports -->|"groups events"| node_segments
node_reports -->|"loads event data"| node_io
node_operator -->|"reviews sessions"| node_server
node_candidate -->|"uses exam page"| node_candidateui
node_candidateui -->|"streams frames"| node_frontendlib
node_proctorui -->|"calls API"| node_frontendlib
node_reviewui -->|"calls API"| node_frontendlib
node_server -->|"stores sessions"| node_database
node_server -->|"routes live work"| node_live
node_server -->|"configures perception"| node_perception
node_manifest -->|"uses label loaders"| node_labels
node_training -->|"loads labels"| node_labels
node_training -->|"uses feature schema"| node_schema
node_identitytraining -->|"calibrates thresholds"| node_identity
node_evaluation -->|"loads ground truth"| node_labels
node_evaluation -->|"reads pipeline outputs"| node_io

click node_cli "https://github.com/varad2343/proctor-lens-/blob/main/src/proctorlens/cli.py"
click node_calibration "https://github.com/varad2343/proctor-lens-/blob/main/src/proctorlens/pipeline/calibration.py"
click node_perception "https://github.com/varad2343/proctor-lens-/blob/main/src/proctorlens/perception/__init__.py"
click node_landmarks "https://github.com/varad2343/proctor-lens-/blob/main/src/proctorlens/perception/landmarks.py"
click node_gaze "https://github.com/varad2343/proctor-lens-/blob/main/src/proctorlens/perception/gaze.py"
click node_objects "https://github.com/varad2343/proctor-lens-/blob/main/src/proctorlens/perception/objects.py"
click node_identity "https://github.com/varad2343/proctor-lens-/blob/main/src/proctorlens/perception/identity.py"
click node_quality "https://github.com/varad2343/proctor-lens-/blob/main/src/proctorlens/perception/quality.py"
click node_features "https://github.com/varad2343/proctor-lens-/blob/main/src/proctorlens/features/extractor.py"
click node_schema "https://github.com/varad2343/proctor-lens-/blob/main/src/proctorlens/features/schema.py"
click node_temporal "https://github.com/varad2343/proctor-lens-/blob/main/src/proctorlens/temporal/scores_learned.py"
click node_state "https://github.com/varad2343/proctor-lens-/blob/main/src/proctorlens/temporal/state_machine.py"
click node_io "https://github.com/varad2343/proctor-lens-/blob/main/src/proctorlens/io.py"
click node_reports "https://github.com/varad2343/proctor-lens-/blob/main/src/proctorlens/explain/report.py"
click node_segments "https://github.com/varad2343/proctor-lens-/blob/main/src/proctorlens/explain/review.py"
click node_server "https://github.com/varad2343/proctor-lens-/blob/main/src/proctorlens/server/app.py"
click node_database "https://github.com/varad2343/proctor-lens-/blob/main/src/proctorlens/server/db.py"
click node_live "https://github.com/varad2343/proctor-lens-/blob/main/src/proctorlens/server/live.py"
click node_candidateui "https://github.com/varad2343/proctor-lens-/blob/main/frontend/src/Candidate.tsx"
click node_proctorui "https://github.com/varad2343/proctor-lens-/blob/main/frontend/src/Proctor.tsx"
click node_reviewui "https://github.com/varad2343/proctor-lens-/blob/main/frontend/src/Review.tsx"
click node_frontendlib "https://github.com/varad2343/proctor-lens-/blob/main/frontend/src/lib.ts"
click node_labels "https://github.com/varad2343/proctor-lens-/blob/main/ml/data/labels.py"
click node_manifest "https://github.com/varad2343/proctor-lens-/blob/main/ml/data/build_manifest.py"
click node_training "https://github.com/varad2343/proctor-lens-/blob/main/ml/training/train_temporal_gbm.py"
click node_identitytraining "https://github.com/varad2343/proctor-lens-/blob/main/ml/training/calibrate_identity.py"
click node_evaluation "https://github.com/varad2343/proctor-lens-/blob/main/ml/evaluation/run_eval.py"

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_cli,node_calibration,node_perception,node_landmarks,node_gaze,node_objects,node_identity,node_quality,node_features,node_schema,node_temporal,node_state,node_io toneBlue
class node_reports,node_segments toneAmber
class node_server,node_database,node_live,node_candidateui,node_proctorui,node_reviewui,node_frontendlib toneMint
class node_labels,node_manifest,node_training,node_identitytraining,node_evaluation toneRose
class node_operator,node_candidate,node_video toneIndigo
```

## Components

### Pipeline runtime

- [CLI commands](https://github.com/varad2343/proctor-lens-/blob/main/src/proctorlens/cli.py): `src/proctorlens/cli.py`
- [Gaze calibration](https://github.com/varad2343/proctor-lens-/blob/main/src/proctorlens/pipeline/calibration.py): `src/proctorlens/pipeline/calibration.py`
- [Frame perception](https://github.com/varad2343/proctor-lens-/blob/main/src/proctorlens/perception/__init__.py): `src/proctorlens/perception/__init__.py`
- [Face landmarks](https://github.com/varad2343/proctor-lens-/blob/main/src/proctorlens/perception/landmarks.py): `src/proctorlens/perception/landmarks.py`
- [Gaze estimation](https://github.com/varad2343/proctor-lens-/blob/main/src/proctorlens/perception/gaze.py): `src/proctorlens/perception/gaze.py`
- [Object detection](https://github.com/varad2343/proctor-lens-/blob/main/src/proctorlens/perception/objects.py): `src/proctorlens/perception/objects.py`
- [Identity checks](https://github.com/varad2343/proctor-lens-/blob/main/src/proctorlens/perception/identity.py): `src/proctorlens/perception/identity.py`
- [Observation quality](https://github.com/varad2343/proctor-lens-/blob/main/src/proctorlens/perception/quality.py): `src/proctorlens/perception/quality.py`
- [Feature extraction](https://github.com/varad2343/proctor-lens-/blob/main/src/proctorlens/features/extractor.py): `src/proctorlens/features/extractor.py`
- [Feature schema](https://github.com/varad2343/proctor-lens-/blob/main/src/proctorlens/features/schema.py): `src/proctorlens/features/schema.py`
- [Temporal scoring](https://github.com/varad2343/proctor-lens-/blob/main/src/proctorlens/temporal/scores_learned.py): `src/proctorlens/temporal/scores_learned.py`
- [Event state machines](https://github.com/varad2343/proctor-lens-/blob/main/src/proctorlens/temporal/state_machine.py): `src/proctorlens/temporal/state_machine.py`
- [Feature and event files](https://github.com/varad2343/proctor-lens-/blob/main/src/proctorlens/io.py): `src/proctorlens/io.py`

### Review and reporting

- [Reports and evidence](https://github.com/varad2343/proctor-lens-/blob/main/src/proctorlens/explain/report.py): `src/proctorlens/explain/report.py`
- [Review segments](https://github.com/varad2343/proctor-lens-/blob/main/src/proctorlens/explain/review.py): `src/proctorlens/explain/review.py`

### Local web app

- [HTTP and live sessions](https://github.com/varad2343/proctor-lens-/blob/main/src/proctorlens/server/app.py): `src/proctorlens/server/app.py`
- [Session database](https://github.com/varad2343/proctor-lens-/blob/main/src/proctorlens/server/db.py): `src/proctorlens/server/db.py`
- [Live processing](https://github.com/varad2343/proctor-lens-/blob/main/src/proctorlens/server/live.py): `src/proctorlens/server/live.py`
- [Candidate exam page](https://github.com/varad2343/proctor-lens-/blob/main/frontend/src/Candidate.tsx): `frontend/src/Candidate.tsx`
- [Proctor dashboard](https://github.com/varad2343/proctor-lens-/blob/main/frontend/src/Proctor.tsx): `frontend/src/Proctor.tsx`
- [Review interface](https://github.com/varad2343/proctor-lens-/blob/main/frontend/src/Review.tsx): `frontend/src/Review.tsx`
- [Web API and stream](https://github.com/varad2343/proctor-lens-/blob/main/frontend/src/lib.ts): `frontend/src/lib.ts`

### ML lifecycle

- [Dataset labels](https://github.com/varad2343/proctor-lens-/blob/main/ml/data/labels.py): `ml/data/labels.py`
- [Dataset manifest](https://github.com/varad2343/proctor-lens-/blob/main/ml/data/build_manifest.py): `ml/data/build_manifest.py`
- [Model training](https://github.com/varad2343/proctor-lens-/blob/main/ml/training/train_temporal_gbm.py): `ml/training/train_temporal_gbm.py`
- [Identity calibration](https://github.com/varad2343/proctor-lens-/blob/main/ml/training/calibrate_identity.py): `ml/training/calibrate_identity.py`
- [Model evaluation](https://github.com/varad2343/proctor-lens-/blob/main/ml/evaluation/run_eval.py): `ml/evaluation/run_eval.py`

### Other components

- **Operator**
- **Candidate**
- **Video or camera**

## Connections

- Operator → CLI commands: runs commands
- Video or camera → CLI commands: provides input
- CLI commands → Gaze calibration: starts calibration (evidence: `src/proctorlens/cli.py`)
- Gaze calibration → Gaze estimation: fits calibration (evidence: `src/proctorlens/pipeline/calibration.py`)
- CLI commands → Frame perception: configures perception (evidence: `src/proctorlens/cli.py`)
- Frame perception → Face landmarks: detects faces (evidence: `src/proctorlens/perception/__init__.py`)
- Frame perception → Object detection: detects objects (evidence: `src/proctorlens/perception/__init__.py`)
- Frame perception → Identity checks: checks identity (evidence: `src/proctorlens/perception/__init__.py`)
- Frame perception → Observation quality: assesses quality (evidence: `src/proctorlens/perception/__init__.py`)
- Feature extraction → Gaze estimation: uses gaze signals (evidence: `src/proctorlens/features/extractor.py`)
- Feature extraction → Feature schema: builds rows (evidence: `src/proctorlens/features/extractor.py`)
- Video or camera → Frame perception: frames enter
- Frame perception → Feature extraction: produces observations
- Feature extraction → Temporal scoring: scores rows
- Temporal scoring → Event state machines: feeds scores
- Event state machines → Feature and event files: writes events
- Feature extraction → Feature and event files: writes features
- CLI commands → Reports and evidence: generates reports (evidence: `src/proctorlens/cli.py`)
- Reports and evidence → Review segments: groups events (evidence: `src/proctorlens/explain/report.py`)
- Reports and evidence → Feature and event files: loads event data (evidence: `src/proctorlens/explain/report.py`)
- Operator → HTTP and live sessions: reviews sessions
- Candidate → Candidate exam page: uses exam page
- Candidate exam page → Web API and stream: streams frames (evidence: `frontend/src/Candidate.tsx`)
- Proctor dashboard → Web API and stream: calls API (evidence: `frontend/src/Proctor.tsx`)
- Review interface → Web API and stream: calls API (evidence: `frontend/src/Review.tsx`)
- HTTP and live sessions → Session database: stores sessions (evidence: `src/proctorlens/server/app.py`)
- HTTP and live sessions → Live processing: routes live work (evidence: `src/proctorlens/server/app.py`)
- HTTP and live sessions → Frame perception: configures perception (evidence: `src/proctorlens/server/app.py`)
- Dataset manifest → Dataset labels: uses label loaders (evidence: `ml/data/build_manifest.py`)
- Model training → Dataset labels: loads labels (evidence: `ml/training/train_temporal_gbm.py`)
- Model training → Feature schema: uses feature schema (evidence: `ml/training/train_temporal_gbm.py`)
- Identity calibration → Identity checks: calibrates thresholds (evidence: `ml/training/calibrate_identity.py`)
- Model evaluation → Dataset labels: loads ground truth (evidence: `ml/evaluation/run_eval.py`)
- Model evaluation → Feature and event files: reads pipeline outputs (evidence: `ml/evaluation/run_eval.py`)
