# vasikumar/classai architecture

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

- Interactive diagram: https://gitdiagram.com/vasikumar/classai
- Repository: https://github.com/vasikumar/classai

## Overview

##### What this project is (type + purpose)
This is a **single-node, Python computer-vision monitoring system** for online classes/exams. It:
- Captures live video from a **webcam**
- Runs **real-time detection pipelines**: face detection/recognition, eye/gaze-based “focus” detection, and **mobile phone detection**
- Emits **real-time alerts** on the video feed
- Produces **post-session reports** (console + JSON)
- Includes an optional **Streamlit dashboard/UI** (`streamlit_app.py`) and helper scripts (`*.bat`, setup checkers)

##### Read the file tree as architecture clues (what to map)
Top-level files indicate the main subsystems:

##### Core runtime / orchestration
- `student_monitor.py` → likely the **primary entrypoint** and session orchestrator (loads config, opens camera, loops frames, calls detectors, aggregates stats, writes report)

- `streamlit_app.py` → **dashboard / visualization / report viewer** (possibly launches via `launch_dashboard.bat`)
- `demo.py`, `examples.py` → examples / alternative runners

##### Inputs / models / configuration
- `config.json`, `monitor_config.json` → static configuration inputs (thresholds, durations, camera index, etc.)
- `yolov8l.pt` → object detection model weights for **mobile detection**
- `sample_student_photos/` + zip workflow described in README → **face database source**

##### Setup / environment / dependency helpers
- `requirements.txt`
- `check_setup.py`, `setup_test.py`, `install.bat`, `check_setup.bat`

##### Reporting tests
- `test_report.py`, `test_end_session.py`, plus report fix guides in docs

##### Operator / Environment (external actors)
- **Teacher/Proctor** (starts session, views alerts/reports)
- **Student(s)** (appear in webcam feed)
- **Webcam** (video input device)
- **Filesystem** (student photo zip, model weights, generated JSON reports)

##### Monitoring Runtime (Python process)
- Entry: `student_monitor.py`
##### Dashboard Runtime (Streamlit)
- Entry: `streamlit_app.py` (optional, may read report JSONs)

##### Inside Monitoring Runtime: key components (module-level)
Even if the code is in a single file, represent these as logical components:
- **Frame Capture**
- OpenCV `VideoCapture` (implied)
- **Preprocessing**
- **Face Detection**
- Detect faces per frame
- **Face Recognition / Identity Resolver**
- Loads student photos from ZIP → creates face database/encodings/templates
- Matches detected face → student name/ID
- **Focus (Gaze/Eye) Detector**
- Eye detection; if both eyes visible => “Focused”
- **Mobile Phone Detector**
- Uses YOLOv8 weights (`yolov8l.pt`) or a simpler heuristic (README hints basic detection; file suggests YOLO is present)
- **Policy / Threshold Evaluator**
- Focus threshold (default 50%)
- Mobile detection incident rules
- **Aggregation + Session State**
- Per-student counters: focused/unfocused/total checks
- Incident timeline (timestamps for alerts)
- **Renderer / Overlay**
- **Report Generator**
- Console summary
- JSON report writer: `focus_report_YYYYMMDD_HHMMSS.json`

##### Offline/setup components (important but non-runtime)
- **Setup Validator** (`check_setup.py`, `setup_test.py`)
- **Dependency Fixers** (`fix_face_recognition.py`, bundled dlib wheel)

##### Teacher starts monitoring
- Teacher → `student_monitor.py` (CLI run)

##### Initialization phase
- `student_monitor.py` → reads `config.json` / `monitor_config.json` (config)
- `student_monitor.py` → reads `name.zip` (student photos) → builds **Face DB**
- `student_monitor.py` → loads `yolov8l.pt` (mobile detection model)

##### Runtime loop (per frame)
- Webcam → Frame Capture → Preprocessing
- Preprocessing → Face Detection → (Face crops) → Face Recognition → Student ID
- Preprocessing/face region → Eye/Focus Detector → Focus signal
- Full frame → Mobile Detector → Mobile incident signal
- Signals → Policy/Threshold Evaluator + Aggregator
- Aggregator → Overlay Renderer → Display (real-time visual feedback)
- Aggregator → Incident log (in memory)

##### Session end
- Aggregator → Report Generator → JSON report file on filesystem
- Report Generator → console output

##### Optional dashboard
- Teacher → Streamlit (`streamlit_app.py`)
- Streamlit → reads JSON report files (and possibly config) → renders charts/tables

**Key detail to include:** face recognition depends on the **student photo ZIP** artifact, while mobile detection depends on the **YOLO weights** artifact.

##### Architectural patterns to highlight (keep it grounded in this repo)
- **Pipeline / staged processing**: capture → detect → classify → decide → render → report
- **Session-based aggregation**: statistics computed over a monitoring interval (`CHECK_INTERVAL`)
- **Config-driven behavior**: threshold + duration + camera index
- **Local-first** execution: no server, no DB; persistence is JSON files

##### “Don’t overthink it” guidance (but still detailed)
For this repo, “best and most accurate” means:
- Split into **as many logical components as exist in the README features** (face recognition, focus detection, mobile detection, reporting, alerts)
- **key artifacts** (`name.zip`, `yolov8l.pt`, `focus_report_*.json`, configs)
- **optional dashboard path** separately so it doesn’t clutter the monitoring loop

- Does it show **how mobile detection is implemented**? (YOLO weights artifact + detector component)
- Does it show **real-time vs post-session outputs**? (overlay alerts vs JSON report)
- Does it show **configuration points** (threshold, interval, camera index)?
- Does it show the **optional Streamlit dashboard** and that it likely reads saved reports?

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% External Actors & Systems
  %% =========================
  subgraph "External Actors / Environment"
    Teacher["Teacher/Proctor"]:::actor
    Student["Student(s) in view"]:::actor
    Webcam["Webcam Device"]:::external
    OSFS[("Local Filesystem")]:::storage
    Display["Live Video Display (OpenCV window)"]:::external
    Console["Console Output"]:::external
  end

  %% =========================
  %% Runtime Containers (Local)
  %% =========================
  subgraph "Local Runtimes (Single Node)"
    subgraph "Monitoring Runtime (Python process)"
      Orchestrator["Monitoring Orchestrator: session loop + orchestration"]:::runtime
      FrameCap["Frame Capture (OpenCV VideoCapture)"]:::vision
      Preproc["Preprocessing (resize/normalize/colorspace)"]:::vision

      FaceDetect["Face Detection"]:::vision
      FaceRecog["Face Recognition / Identity Resolver"]:::vision
      FaceDB["Face DB (encodings/templates in memory)"]:::data

      FocusDet["Focus (Eye/Gaze) Detector"]:::vision
      MobileDet["Mobile Phone Detector (YOLOv8 inference)"]:::vision

      Policy["Policy / Threshold Evaluator"]:::policy
      Agg["Aggregation + Session State (counters, timelines)"]:::policy

      Overlay["Overlay Renderer (boxes/labels/alerts)"]:::output
      ReportGen["Report Generator (summary + JSON writer)"]:::output
    end

    subgraph "Dashboard Runtime (Streamlit)"
      StreamlitUI["Streamlit Dashboard / Report Viewer"]:::ui
    end
  end

  %% =========================
  %% Artifacts on Filesystem
  %% =========================
  subgraph "Artifacts (on Local Filesystem)"
    Config1["config.json (thresholds, camera index, intervals)"]:::artifact
    Config2["monitor_config.json (monitoring-specific config)"]:::artifact
    PhotosDir["sample_student_photos/ (face DB source)"]:::artifact
    PhotosReadme["sample_student_photos/README.txt (photo DB instructions)"]:::artifact
    YoloWeights["yolov8l.pt (YOLOv8 weights)"]:::artifact
    Reports["focus_report_*.json (session report output)"]:::artifactOut
  end

  %% =========================
  %% Setup / Supporting Utilities (Offline)
  %% =========================
  subgraph "Setup & Supporting Utilities (Offline / Optional)"
    Req["requirements.txt"]:::support
    DlibWhl["Bundled dlib wheel (Windows)"]:::support
    FixFR["Dependency Fixer (face_recognition/dlib)"]:::support
    CheckSetup["Setup Validator / Environment Checker"]:::support
    SetupTest["Setup Test Script"]:::support
    InstallBat["install.bat (Windows install)"]:::support
    CheckSetupBat["check_setup.bat (Windows setup check launcher)"]:::support
    LaunchDashBat["launch_dashboard.bat (Windows dashboard launcher)"]:::support
    AudioRec["audio_recorder.py (optional utility)"]:::support
  end

  %% =========================
  %% Docs / Guides
  %% =========================
  subgraph "Documentation / Guides"
    Readme["README.md"]:::doc
    Quickstart1["QUICKSTART.md"]:::doc
    Quickstart2["QUICK_START.md"]:::doc
    UsageGuide["USAGE_GUIDE.md"]:::doc
    CompleteGuide["COMPLETE_GUIDE.md"]:::doc
    ProjectSummary["PROJECT_SUMMARY.md"]:::doc
    SetupGuide["SETUP_GUIDE.md"]:::doc
    StreamlitGuide["STREAMLIT_GUIDE.md"]:::doc
    MobileInfo["MOBILE_DETECTION_INFO.md"]:::doc
    ReportsTrouble["REPORTS_TROUBLESHOOTING.md"]:::doc
    ReportFix["REPORT_FIX_GUIDE.md"]:::doc
    UpdateNotes["UPDATE_NOTES.md"]:::doc
  end

  %% =========================
  %% Tests / Verification
  %% =========================
  subgraph "Tests"
    TestReport["test_report.py"]:::test
    TestEnd["test_end_session.py"]:::test
  end

  %% =========================
  %% Control / Config Flows (dashed)
  %% =========================
  Teacher -.->|"starts_session"| Orchestrator
  Orchestrator -.->|"reads_config"| Config1
  Orchestrator -.->|"reads_config"| Config2
  Orchestrator -.->|"loads_face_photos"| PhotosDir
  Orchestrator -.->|"loads_model_weights"| YoloWeights
  Orchestrator -.->|"opens_camera"| Webcam

  LaunchDashBat -.->|"launches"| StreamlitUI
  Teacher -.->|"views_reports"| StreamlitUI

  %% Setup flows
  InstallBat -.->|"installs_deps"| Req
  FixFR -.->|"uses"| DlibWhl
  CheckSetupBat -.->|"runs"| CheckSetup
  SetupTest -.->|"validates_runtime"| Orchestrator
  CheckSetup -.->|"checks_deps"| Req
  CheckSetup -.->|"may_repair"| FixFR

  %% =========================
  %% Data Flows (solid)
  %% =========================
  Student -->|"appears_in"| Webcam
  Webcam -->|"frames"| FrameCap
  FrameCap -->|"raw_frame"| Preproc

  Preproc -->|"frame"| FaceDetect
  FaceDetect -->|"face_regions"| FaceRecog
  PhotosDir -->|"source_photos"| FaceRecog
  FaceRecog -->|"builds/updates"| FaceDB
  FaceDB -->|"encodings"| FaceRecog
  FaceRecog -->|"student_identity"| Agg

  Preproc -->|"face/eye_region"| FocusDet
  FocusDet -->|"focus_signal"| Policy

  Preproc -->|"full_frame"| MobileDet
  YoloWeights -->|"weights"| MobileDet
  MobileDet -->|"mobile_incident_signal"| Policy

  Policy -->|"decisions/flags"| Agg
  Agg -->|"overlay_state + alerts"| Overlay
  Overlay -->|"rendered_frame"| Display

  Agg -->|"session_stats + timeline"| ReportGen
  ReportGen -->|"writes"| Reports
  Reports -->|"saved_in"| OSFS
  ReportGen -->|"prints_summary"| Console

  StreamlitUI -->|"reads_reports"| Reports
  StreamlitUI -->|"reads_from"| OSFS

  %% Demo/example runners (optional)
  subgraph "Optional Runners"
    Demo["demo.py (alternative runner)"]:::support
    Examples["examples.py (examples)"]:::support
  end
  Teacher -.->|"runs_optional"| Demo
  Teacher -.->|"runs_optional"| Examples
  Demo -.->|"invokes_pipeline"| Orchestrator
  Examples -.->|"invokes_pipeline"| Orchestrator

  %% Tests to reporting path
  TestReport -.->|"verifies_reports"| Reports
  TestEnd -.->|"end_to_end"| Orchestrator

  %% =========================
  %% Click Events (component_mapping)
  %% =========================
  click Orchestrator "https://github.com/vasikumar/classai/blob/main/student_monitor.py"
  click StreamlitUI "https://github.com/vasikumar/classai/blob/main/streamlit_app.py"
  click Demo "https://github.com/vasikumar/classai/blob/main/demo.py"
  click Examples "https://github.com/vasikumar/classai/blob/main/examples.py"

  click Config1 "https://github.com/vasikumar/classai/blob/main/config.json"
  click Config2 "https://github.com/vasikumar/classai/blob/main/monitor_config.json"

  click YoloWeights "https://github.com/vasikumar/classai/blob/main/yolov8l.pt"
  click PhotosDir "https://github.com/vasikumar/classai/tree/main/sample_student_photos/"
  click PhotosReadme "https://github.com/vasikumar/classai/blob/main/sample_student_photos/README.txt"

  click CheckSetup "https://github.com/vasikumar/classai/blob/main/check_setup.py"
  click SetupTest "https://github.com/vasikumar/classai/blob/main/setup_test.py"
  click FixFR "https://github.com/vasikumar/classai/blob/main/fix_face_recognition.py"
  click DlibWhl "https://github.com/vasikumar/classai/blob/main/dlib-19.24.1-cp311-cp311-win_amd64.whl"
  click Req "https://github.com/vasikumar/classai/blob/main/requirements.txt"
  click InstallBat "https://github.com/vasikumar/classai/blob/main/install.bat"
  click CheckSetupBat "https://github.com/vasikumar/classai/blob/main/check_setup.bat"
  click LaunchDashBat "https://github.com/vasikumar/classai/blob/main/launch_dashboard.bat"

  click TestReport "https://github.com/vasikumar/classai/blob/main/test_report.py"
  click TestEnd "https://github.com/vasikumar/classai/blob/main/test_end_session.py"

  click StreamlitGuide "https://github.com/vasikumar/classai/blob/main/STREAMLIT_GUIDE.md"
  click SetupGuide "https://github.com/vasikumar/classai/blob/main/SETUP_GUIDE.md"
  click ReportsTrouble "https://github.com/vasikumar/classai/blob/main/REPORTS_TROUBLESHOOTING.md"
  click ReportFix "https://github.com/vasikumar/classai/blob/main/REPORT_FIX_GUIDE.md"
  click MobileInfo "https://github.com/vasikumar/classai/blob/main/MOBILE_DETECTION_INFO.md"
  click Readme "https://github.com/vasikumar/classai/blob/main/README.md"
  click Quickstart1 "https://github.com/vasikumar/classai/blob/main/QUICKSTART.md"
  click Quickstart2 "https://github.com/vasikumar/classai/blob/main/QUICK_START.md"
  click ProjectSummary "https://github.com/vasikumar/classai/blob/main/PROJECT_SUMMARY.md"
  click CompleteGuide "https://github.com/vasikumar/classai/blob/main/COMPLETE_GUIDE.md"
  click UsageGuide "https://github.com/vasikumar/classai/blob/main/USAGE_GUIDE.md"
  click UpdateNotes "https://github.com/vasikumar/classai/blob/main/UPDATE_NOTES.md"

  click AudioRec "https://github.com/vasikumar/classai/blob/main/audio_recorder.py"

  %% =========================
  %% Styles
  %% =========================
  classDef actor fill:#f3f4f6,stroke:#6b7280,color:#111827,stroke-width:1px
  classDef external fill:#e5e7eb,stroke:#4b5563,color:#111827,stroke-width:1px
  classDef storage fill:#d1d5db,stroke:#374151,color:#111827,stroke-width:1.2px

  classDef runtime fill:#dbeafe,stroke:#1d4ed8,color:#0b1b3a,stroke-width:1.2px
  classDef vision fill:#bfdbfe,stroke:#2563eb,color:#0b1b3a,stroke-width:1px
  classDef policy fill:#fed7aa,stroke:#c2410c,color:#3a1a00,stroke-width:1.2px
  classDef output fill:#bbf7d0,stroke:#15803d,color:#052e12,stroke-width:1.2px
  classDef ui fill:#c7d2fe,stroke:#4338ca,color:#111827,stroke-width:1.2px

  classDef artifact fill:#fef3c7,stroke:#b45309,color:#3a2400,stroke-width:1px
  classDef artifactOut fill:#dcfce7,stroke:#16a34a,color:#052e12,stroke-width:1px
  classDef data fill:#e0e7ff,stroke:#3730a3,color:#111827,stroke-width:1px

  classDef support fill:#f5f5f4,stroke:#78716c,color:#1c1917,stroke-width:1px
  classDef doc fill:#fff7ed,stroke:#9a3412,color:#3a1a00,stroke-width:1px
  classDef test fill:#ffe4e6,stroke:#be123c,color:#3a0a14,stroke-width:1px
```
