# atsurak/automated-proctoring architecture

> Architecture diagram of the GitHub repository atsurak/automated-proctoring, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/atsurak/automated-proctoring
- Repository: https://github.com/atsurak/automated-proctoring

## Overview

##### Project Type and Purpose
- This is a Python‑based, open‑source proctoring application that processes live webcam feeds to detect cheating behaviors in online exams.
- Key features (from README): face detection/recognition, landmark detection, head‑pose estimation, spoof detection, lip tracking, and cheating aggregation.

##### File Structure
- Top‑level files:
- main.py – orchestrator, launches the proctoring loop
- cheating_detector.py – core logic to decide if cheating occurred
- utils.py, testing.py, plot_graphs.py – helpers, testing, reporting
- Top‑level modules (face_detector.py, face_recognition.py, face_landmarks.py, head_pose.py, face_spoofing.py, mouth_detector.py): each implements a specific detection/estimation step.
- assets/ holds environment configuration (proctorenv.yml) and sample images.
- results/ is the output directory for per‑session reports.

##### Extract Architecture Insights from the README
- Runtime: Python 3.x inside a Conda environment (proctorenv).
- Dependencies: OpenCV, TensorFlow/Keras (FaceNet, anti‑spoofing), dlib, BlazeFace (lightweight detector).
- Workflow: from registration (image capture) → continuous proctoring → detection modules → report generation.

##### Main Components to Capture
a. Input Layer
- Webcam (live video frames)
- User registration subflow (captures 5 images via main.py)
1. Face Detector (blazeface)
2. Face Recognizer (FaceNet512)
3. Face Landmarks (shape_predictor_68)
4. Head Pose Estimation
5. Lip/Mouth Detector
6. Face Spoofing Detector (anti‑spoofing h5/json model)
7. Cheating Detector (aggregator logic in cheating_detector.py)
c. Data / Model Storage
- models/ directory (weights and model definitions)
- assets/proctorenv.yml (environment spec)
d. Output Layer
- Real‑time display / GUI overlays (via OpenCV windows)
- Report files in results/ (CSV or JSON logs)
- plot_graphs.py – post‑hoc visualization
e. External Dependencies
- OEP dataset (for offline testing)
- Conda (environment manager)

##### Relationships & Data Flow
- Face Detector → branches to Face Recognizer & Face Landmarks
- Face Landmarks → Head Pose + Mouth Detector
- Face Recognizer + Spoof Detector + Head Pose + Mouth Detector → Cheating Detector
- Cheating Detector → Report Writer (results/) + GUI
- Testing pipeline (testing.py) reads from OEP dataset → modules → plot_graphs.py

##### Architectural Patterns & Design Principles
- Modular pipeline: each detection step is its own module/file.
- Single‑process orchestrator (main.py) coordinating modules in sequence.
- Separation of concerns: model loading (models/) vs. detection logic.
- Extensibility: add new detectors by dropping in new .py modules and updating cheating_detector.py.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Legend
    subgraph Legend
        direction TB
        IO["Green: Input/Output"]:::io
        Core["Blue: Core Processing"]:::core
        Storage["Orange: Model/Data Storage"]:::storage
        Util["Gray: Utilities/Testing"]:::util
    end

    %% Input Layer
    Webcam["Webcam (Live Frames)"]:::io
    Registration["User Registration\n(capture 5 images)"]:::io

    %% Orchestration
    Main["main.py\n(Orchestrator)"]:::core

    %% Proctoring Pipeline
    subgraph "Proctoring Pipeline"
        direction TB
        FD["face_detector.py\n(BlazeFace)"]:::core
        FR["face_recognition.py\n(FaceNet512)"]:::core
        FRModel["models/Facenet512.py\n& weights.h5"]:::storage
        FL["face_landmarks.py\ndlib landmarks"]:::core
        ShapeModel["models/shape_predictor_68_face_landmarks.dat"]:::storage
        HP["head_pose.py\nHead Pose Estimation"]:::core
        MD["mouth_detector.py\nLip Tracking"]:::core
        FS["face_spoofing.py\nAnti-Spoofing"]:::core
        ASModel["models/antispoofing_models/\nmodel.h5 & .json"]:::storage
        CD["cheating_detector.py\n(Aggregator Logic)"]:::core
    end

    %% Outputs
    GUI["Real-time GUI\n(OpenCV Overlays)"]:::io
    Reports["results/\n(Session Reports)"]:::io

    %% Utilities & Testing
    Utils["utils.py"]:::util
    Testing["testing.py\n(Offline OEP Pipeline)"]:::util
    Plot["plot_graphs.py"]:::util
    Dataset["OEP Dataset"]:::storage

    %% Configuration & Models
    ModelsDir["models/ root"]:::storage
    FaceGeo["models/face_geometry.py"]:::storage
    Env["assets/proctorenv.yml"]:::storage

    %% Data Flow
    Webcam --> Main
    Registration --> Main
    Main --> FD
    FD --> FR
    FD --> FL
    FD --> FS
    FL --> HP
    FL --> MD
    FR --> CD
    FS --> CD
    HP --> CD
    MD --> CD
    CD --> GUI
    CD --> Reports

    %% Dependency Flow
    ModelsDir --> FD
    ModelsDir --> FRModel
    ModelsDir --> ShapeModel
    ModelsDir --> ASModel
    ModelsDir --> FaceGeo
    ModelsDir --> FL
    ModelsDir --> FS
    Env --> Main
    Utils --> Main
    Utils --> CD

    %% Testing Flow
    Testing --> Dataset
    Testing --> FD
    Testing --> FR
    Testing --> FL
    Testing --> HP
    Testing --> MD
    Testing --> FS
    Testing --> CD
    Testing --> Plot
    Plot --> Reports

    %% Click Events
    click Main "https://github.com/atsurak/automated-proctoring/blob/main/main.py"
    click CD "https://github.com/atsurak/automated-proctoring/blob/main/cheating_detector.py"
    click FD "https://github.com/atsurak/automated-proctoring/blob/main/face_detector.py"
    click FR "https://github.com/atsurak/automated-proctoring/blob/main/face_recognition.py"
    click FRModel "https://github.com/atsurak/automated-proctoring/blob/main/models/Facenet512.py"
    click ShapeModel "https://github.com/atsurak/automated-proctoring/blob/main/models/shape_predictor_68_face_landmarks.dat"
    click ASModel "https://github.com/atsurak/automated-proctoring/blob/main/models/antispoofing_models/antispoofing_model.h5"
    click ASModel "https://github.com/atsurak/automated-proctoring/blob/main/models/antispoofing_models/antispoofing_model.json"
    click ModelsDir "https://github.com/atsurak/automated-proctoring/tree/main/models/"
    click FaceGeo "https://github.com/atsurak/automated-proctoring/blob/main/models/face_geometry.py"
    click Env "https://github.com/atsurak/automated-proctoring/blob/main/assets/proctorenv.yml"
    click Utils "https://github.com/atsurak/automated-proctoring/blob/main/utils.py"
    click Testing "https://github.com/atsurak/automated-proctoring/blob/main/testing.py"
    click Plot "https://github.com/atsurak/automated-proctoring/blob/main/plot_graphs.py"
    click Reports "https://github.com/atsurak/automated-proctoring/tree/main/results/"

    %% Styles
    classDef io fill:#d5f5e3,stroke:#27ae60,stroke-width:2px
    classDef core fill:#d6eaf8,stroke:#2e86c1,stroke-width:2px
    classDef storage fill:#fcf3cf,stroke:#d68910,stroke-width:2px
    classDef util fill:#f2f3f4,stroke:#566573,stroke-width:2px
```
