# bahrombekk/auto-proctoring architecture

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

- Interactive diagram: https://gitdiagram.com/bahrombekk/auto-proctoring
- Repository: https://github.com/bahrombekk/auto-proctoring

## Overview

##### Project type and purpose
- This is an “auto-proctoring” application: it uses live video or image feeds to detect a person, verify their identity, and flag prohibited behaviors (e.g., phone usage) during an exam.
- The codebase is pure Python, organizes ML models (YOLO, ONNX/PyTorch), a local key-value store (LMDB), capture and verification routines, and a small CLI/driver.

##### File structure
- Top-level scripts:
- main.py: likely the orchestration entry point.
- captury.py: helper for capturing frames (camera or video).
- config.py: global configuration (model paths, thresholds).
- “manitoring/” (sic) directory:
- person_detect.py, phone.py, proctor.py – components that load pre-trained YOLO or ONNX models to detect faces, phones, and perform combined proctoring logic.
- best.pt / best.onnx, yolov8n.pt / .onnx, etc. – ML weight files.
- “src/” directory: face pipeline and DB:
- face_capture.py: extracts face crops from frames.
- face_recognition.py: computes embeddings or classification.
- face_verification.py: verifies current face against stored profile.
- db_management.py: wrappers around LMDB.
- face_database.py: CRUD operations on face records.
- lmdb_data/: the actual LMDB store files.
- saved_images/: sample or captured face images.
- “test/” directory: unit tests for on/off detections and proctor logic.
- requirements.txt: lists Python dependencies (torch, onnxruntime, lmdb, opencv, etc.).

##### README
- Minimal (“# Auto-proctoring”), so architecture must be inferred from code layout.

##### Main components
a. Layer
– Captury module (camera/video input)
b. Pre-processing & Detection
– person_detect (YOLO model)
– phone_detect (YOLO or custom)
c. Face Pipeline
– face_capture → face_recognition → face_verification
d. Decision / Proctor Logic
– proctor.py: aggregates detection & verification results, raises alerts
e. Data Storage
– LMDB (via db_management & face_database) for enrolled identities
– saved_images for offline review
f. Model Assets
– ONNX / PyTorch weight files
g. Tests & CI
– test suite
– push_to_github.sh

##### Relationships and interactions
- Data flow starts at Captury → frame
- Frame is forked to person_detect & phone.py
- Detected face region goes to face_capture → recognition → verification
- All results feed into proctor.py
- proctor.py writes logs or updates LMDB via db_management/face_database
- Main.py ties all modules, loads config, spins up capture loop
- Tests simulate inputs through detection and proctor modules

##### Architectural patterns / design principles
- **Modular pipeline**: clear separation between detection, recognition, verification, decision
- **Model abstraction**: each ML model lives in its own module with a consistent API
- **Persistence layer**: LMDB encapsulated behind db_management and face_database
- **Config-driven**: model paths and thresholds in config.py
- **Testable units**: each component has corresponding tests

3. “face_capture” → “face_recognition” → “face_verification” in a vertical chain.
7. “main.py” wrapper around the entire flow or as a note that it initializes/configures each module.

##### Detail
- Python modules as distinct components if space allows.
- Config.py feeding parameters into each module.
- Periodic tasks (e.g., database cleanup) if present.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Orchestration"
        Main["main.py"]:::orchestration
        Config["config.py"]:::config
    end
    click Main "https://github.com/bahrombekk/auto-proctoring/blob/main/main.py"
    click Config "https://github.com/bahrombekk/auto-proctoring/blob/main/config.py"

    Main -->|load_config| Config
    Main --> Captury

    Captury["Captury (captury.py)"]:::capture
    click Captury "https://github.com/bahrombekk/auto-proctoring/blob/main/captury.py"

    Captury -->|"frame"| PersonDetect
    Captury -->|"frame"| PhoneDetect

    PersonDetect["person_detect.py"]:::mlmodule
    click PersonDetect "https://github.com/bahrombekk/auto-proctoring/blob/main/manitoring/person_detect.py"
    PhoneDetect["phone.py"]:::mlmodule
    click PhoneDetect "https://github.com/bahrombekk/auto-proctoring/blob/main/manitoring/phone.py"

    PersonDetect --> FaceCapture

    subgraph "Face Pipeline"
        FaceCapture["face_capture.py"]:::pipeline
        click FaceCapture "https://github.com/bahrombekk/auto-proctoring/blob/main/src/face_capture.py"
        FaceRecognition["face_recognition.py"]:::pipeline
        click FaceRecognition "https://github.com/bahrombekk/auto-proctoring/blob/main/src/face_recognition.py"
        FaceVerification["face_verification.py"]:::pipeline
        click FaceVerification "https://github.com/bahrombekk/auto-proctoring/blob/main/src/face_verification.py"
    end

    FaceCapture -->|"face_crop"| FaceRecognition
    FaceRecognition -->|"embedding"| FaceVerification

    PhoneDetect --> Proctor
    FaceVerification --> Proctor

    Proctor["proctor.py"]:::decision
    click Proctor "https://github.com/bahrombekk/auto-proctoring/blob/main/manitoring/proctor.py"

    Proctor --> DBMgmt
    DBMgmt["db_management.py"]:::db
    click DBMgmt "https://github.com/bahrombekk/auto-proctoring/blob/main/src/db_management.py"
    DBMgmt --> FaceDB
    FaceDB["face_database.py"]:::db
    click FaceDB "https://github.com/bahrombekk/auto-proctoring/blob/main/src/face_database.py"
    FaceDB --> LMDB
    LMDB["LMDB Store"]:::storage
    click LMDB "https://github.com/bahrombekk/auto-proctoring/blob/main/src/lmdb_data/data.mdb"
    click LMDB "https://github.com/bahrombekk/auto-proctoring/blob/main/src/lmdb_data/lock.mdb"

    Proctor -->|"save_alert"| SavedImages
    SavedImages["Saved Images"]:::storage
    click SavedImages "https://github.com/bahrombekk/auto-proctoring/tree/main/src/saved_images/"

    subgraph "Model Assets"
        BestONNX["best.onnx"]:::asset
        BestPT["best.pt"]:::asset
        YOLO11nONNX["yolo11n.onnx"]:::asset
        YOLO11nPT["yolo11n.pt"]:::asset
        Yolov8nONNX["yolov8n.onnx"]:::asset
        Yolov8nPT["yolov8n.pt"]:::asset
        TopYolov8nPT["yolov8n.pt"]:::asset
    end
    click BestONNX "https://github.com/bahrombekk/auto-proctoring/blob/main/manitoring/best.onnx"
    click BestPT "https://github.com/bahrombekk/auto-proctoring/blob/main/manitoring/best.pt"
    click YOLO11nONNX "https://github.com/bahrombekk/auto-proctoring/blob/main/manitoring/yolo11n.onnx"
    click YOLO11nPT "https://github.com/bahrombekk/auto-proctoring/blob/main/manitoring/yolo11n.pt"
    click Yolov8nONNX "https://github.com/bahrombekk/auto-proctoring/blob/main/manitoring/yolov8n.onnx"
    click Yolov8nPT "https://github.com/bahrombekk/auto-proctoring/blob/main/manitoring/yolov8n.pt"
    click TopYolov8nPT "https://github.com/bahrombekk/auto-proctoring/blob/main/yolov8n.pt"

    BestONNX --> PersonDetect
    BestPT --> PersonDetect
    YOLO11nONNX --> PersonDetect
    YOLO11nPT --> PersonDetect
    Yolov8nONNX --> PhoneDetect
    Yolov8nPT --> PhoneDetect

    subgraph "Tests"
        TestPhone["test_phone.py"]:::test
        TestYOLO["yolov_onnx_test.py"]:::test
        TestOn["on.py"]:::test
        TestOnTest["on_test.py"]:::test
        TestProctor["proctor.py"]:::test
    end
    click TestPhone "https://github.com/bahrombekk/auto-proctoring/blob/main/manitoring/test_phone.py"
    click TestYOLO "https://github.com/bahrombekk/auto-proctoring/blob/main/manitoring/yolov_onnx_test.py"
    click TestOn "https://github.com/bahrombekk/auto-proctoring/blob/main/test/on.py"
    click TestOnTest "https://github.com/bahrombekk/auto-proctoring/blob/main/test/on_test.py"
    click TestProctor "https://github.com/bahrombekk/auto-proctoring/blob/main/test/proctor.py"

    TestPhone --> PersonDetect
    TestYOLO --> PersonDetect
    TestOn --> PhoneDetect
    TestOnTest --> PhoneDetect
    TestProctor --> Proctor

    CIScript["push_to_github.sh"]:::ci
    click CIScript "https://github.com/bahrombekk/auto-proctoring/blob/main/push_to_github.sh"
    CIScript --> TestPhone
    CIScript --> TestYOLO
    CIScript --> TestOn
    CIScript --> TestOnTest
    CIScript --> TestProctor

    classDef capture fill:#D0E6FF,stroke:#4D89FF
    classDef config fill:#E8FFE8,stroke:#2ECC71
    classDef orchestration fill:#FFE6D0,stroke:#FF8C00
    classDef mlmodule fill:#E8F5E9,stroke:#2E7D32
    classDef pipeline fill:#FFF3E0,stroke:#FB8C00
    classDef decision fill:#F3E5F5,stroke:#8E24AA
    classDef db fill:#FFFDE7,stroke:#FDD835
    classDef storage fill:#ECEFF1,stroke:#607D8B
    classDef asset fill:#F0F4C3,stroke:#AFB42B
    classDef test fill:#FFEBEE,stroke:#C62828,stroke-dasharray:5 5
    classDef ci fill:#E1F5FE,stroke:#0277BD
```
