# inbasperu/visionguard architecture

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

- Interactive diagram: https://gitdiagram.com/inbasperu/visionguard
- Repository: https://github.com/inbasperu/visionguard

## Overview

##### Project type and purpose
- VisionGuard is a native desktop application (full-stack in the sense of UI + compute pipeline) written in C++ using Qt6 for the front end, OpenCV for camera capture and image processing, and OpenVINO for model inference.
- Its goal is real-time gaze tracking and eye-state estimation to remind users to take breaks, while monitoring system resources and keeping all data local.

##### File structure
- Top-level directories:
- src/ & include/  → core application logic and headers
- omz_models/     → pretrained inference models in multiple precisions (FP32, FP16, INT8)
- third_party/    → embedded libs (gflags, monitors, nlohmann/json, utils)
- docs/           → architecture, installation, usage, benchmarks
- Build & deployment:
- CMakeLists.txt & build scripts (build.sh/ps1) for cross-platform build
- VisionGuardInstaller.nsi for Windows installer
- Configuration:
- config.json for default settings
- gflags for CLI/GUI flags parsing
- Patterns & modules:
- Pipeline of estimators (face detection → landmarks → head pose → gaze → eye state) behind an IEWrapper
- MVC-like: mainwindow UI handling events and displaying results; vision_guard core implements the logic; results_marker overlays on frames

##### README for additional insights
- Mentions “Architecture” doc in docs/ARCHITECTURE.md that describes backend processes and model pipeline
- Lists key components: UI (Qt6), CV (OpenCV), Inference (OpenVINO), Resource Monitoring

a. Main components:
1. UI Layer (Qt6 MainWindow & System Tray)
2. Camera Capture (OpenCV VideoCapture)
3. Inference Pipeline:
- IEWrapper (OpenVINO Runtime)
- FaceDetector
- LandmarksEstimator
- HeadPoseEstimator
- GazeEstimator
- EyeStateEstimator
4. Resource Monitor (CPU/Memory via monitors lib)
5. Configuration & Flags (gflags + config.json + nlohmann::json)
6. Persistence (screen_time_stats.json)
7. External Models (omz_models folder)
b. Relationships & interactions:
- UI triggers start/stop capture and device selection (CPU/GPU/NPU).
- Camera Capture feeds frames into the Inference Pipeline.
- Each estimator module passes its results downstream; IEWrapper abstracts loading/executing models.
- Results go back to UI for overlay (ResultsMarker) and notifications.
- Resource Monitor runs in parallel, streaming stats to UI.
- Usage statistics are accumulated and periodically written to JSON.
c. Architectural patterns:
- Pipeline pattern for sequential model execution.
- Observer/Publisher-Subscriber for UI updates (e.g., new gaze data, resource stats).
- MVC-style separation: MainWindow (View+Controller) vs. vision_guard core (Model).
- Plugin-like support for multiple inference devices via IEWrapper abstraction.
d. Relevant technologies:
- Qt6 (GUI event loop, signals/slots)
- OpenCV (frame capture & basic processing)
- OpenVINO Runtime (model inference)
- gflags (CLI/GUI flags management)
- nlohmann/json (config & stats serialization)
- monitors lib (resource usage)

##### Key advice
- Every component and its role (no shortcuts).
- Use layers: Presentation (Qt), Processing (OpenCV + Inference), Infrastructure (Monitoring, Config, Persistence).
- Keep it simple but detailed: show threading boundaries if possible (e.g., main GUI thread vs. inference thread).
- Validate against docs/ARCHITECTURE.md to ensure alignment with existing textual architecture.
- Iterate with developers to fill in missing details (e.g., exact class names or interactions).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        MainWindow["MainWindow UI"]:::ui
        SystemTray["System Tray"]:::ui
    end

    %% Processing Layer
    subgraph "Processing Layer"
        direction TB
        CoreLogic["VisionGuard Core"]:::core
        CameraCapture["Camera Capture"]:::core
        subgraph "Inference Pipeline"
            direction TB
            IEWrapper["IEWrapper"]:::core
            FaceDetector["FaceDetector"]:::core
            LandmarksEstimator["LandmarksEstimator"]:::core
            HeadPoseEstimator["HeadPoseEstimator"]:::core
            GazeEstimator["GazeEstimator"]:::core
            EyeStateEstimator["EyeStateEstimator"]:::core
        end
        ResultsMarker["ResultsMarker (Overlay)"]:::core
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        direction TB
        ResourceMonitor["Resource Monitor"]:::infra
        ConfigFlags["Config & Flags"]:::infra
        Persistence["Stats Persistence"]:::infra
        ModelStore["Model Store (omz_models)"]:::assets
    end

    %% Connections
    MainWindow -->|"start/stop, device selection"| CoreLogic
    SystemTray -->|"notifications"| MainWindow
    CoreLogic --> CameraCapture
    CameraCapture -->|"frames"| IEWrapper
    IEWrapper --> FaceDetector
    FaceDetector --> LandmarksEstimator
    LandmarksEstimator --> HeadPoseEstimator
    HeadPoseEstimator --> GazeEstimator
    GazeEstimator --> EyeStateEstimator
    EyeStateEstimator --> ResultsMarker
    ResultsMarker --> MainWindow
    ResourceMonitor -->|"stats"| MainWindow
    MainWindow -->|"<--> settings"| ConfigFlags
    CoreLogic -->|"load models"| ModelStore
    CoreLogic -->|"write stats"| Persistence

    %% Click Events
    click MainWindow "https://github.com/inbasperu/visionguard/blob/main/include/mainwindow.hpp"
    click MainWindow "https://github.com/inbasperu/visionguard/blob/main/src/mainwindow.cpp"
    click MainWindow "https://github.com/inbasperu/visionguard/blob/main/src/mainwindow.ui"
    click MainWindow "https://github.com/inbasperu/visionguard/blob/main/resources/resources.qrc"
    click MainWindow "https://github.com/inbasperu/visionguard/blob/main/resources/vision-guard-removebg.icns"
    click MainWindow "https://github.com/inbasperu/visionguard/blob/main/resources/windows_resource.rc"
    click CameraCapture "https://github.com/inbasperu/visionguard/blob/main/src/vision_guard.cpp"
    click CameraCapture "https://github.com/inbasperu/visionguard/blob/main/third_party/utils/include/utils/images_capture.h"
    click CameraCapture "https://github.com/inbasperu/visionguard/blob/main/third_party/utils/src/images_capture.cpp"
    click IEWrapper "https://github.com/inbasperu/visionguard/blob/main/include/ie_wrapper.hpp"
    click IEWrapper "https://github.com/inbasperu/visionguard/blob/main/src/ie_wrapper.cpp"
    click FaceDetector "https://github.com/inbasperu/visionguard/blob/main/include/face_detector.hpp"
    click FaceDetector "https://github.com/inbasperu/visionguard/blob/main/src/face_detector.cpp"
    click LandmarksEstimator "https://github.com/inbasperu/visionguard/blob/main/include/landmarks_estimator.hpp"
    click LandmarksEstimator "https://github.com/inbasperu/visionguard/blob/main/src/landmarks_estimator.cpp"
    click HeadPoseEstimator "https://github.com/inbasperu/visionguard/blob/main/include/head_pose_estimator.hpp"
    click HeadPoseEstimator "https://github.com/inbasperu/visionguard/blob/main/src/head_pose_estimator.cpp"
    click GazeEstimator "https://github.com/inbasperu/visionguard/blob/main/include/gaze_estimator.hpp"
    click GazeEstimator "https://github.com/inbasperu/visionguard/blob/main/src/gaze_estimator.cpp"
    click EyeStateEstimator "https://github.com/inbasperu/visionguard/blob/main/include/eye_state_estimator.hpp"
    click EyeStateEstimator "https://github.com/inbasperu/visionguard/blob/main/src/eye_state_estimator.cpp"
    click ResultsMarker "https://github.com/inbasperu/visionguard/blob/main/include/results_marker.hpp"
    click ResultsMarker "https://github.com/inbasperu/visionguard/blob/main/src/results_marker.cpp"
    click CoreLogic "https://github.com/inbasperu/visionguard/blob/main/include/vision_guard.hpp"
    click CoreLogic "https://github.com/inbasperu/visionguard/blob/main/src/vision_guard.cpp"
    click ResourceMonitor "https://github.com/inbasperu/visionguard/blob/main/third_party/monitors/include/monitors/cpu_monitor.h"
    click ResourceMonitor "https://github.com/inbasperu/visionguard/blob/main/third_party/monitors/include/monitors/memory_monitor.h"
    click ResourceMonitor "https://github.com/inbasperu/visionguard/blob/main/third_party/monitors/src/cpu_monitor.cpp"
    click ResourceMonitor "https://github.com/inbasperu/visionguard/blob/main/third_party/monitors/src/memory_monitor.cpp"
    click ConfigFlags "https://github.com/inbasperu/visionguard/blob/main/config.json"
    click ConfigFlags "https://github.com/inbasperu/visionguard/tree/main/third_party/gflags"
    click ConfigFlags "https://github.com/inbasperu/visionguard/blob/main/third_party/nlohmann/json.hpp"
    click Persistence "https://github.com/inbasperu/visionguard/blob/main/screen_time_stats.json"
    click Persistence "https://github.com/inbasperu/visionguard/blob/main/third_party/utils/include/utils/config_factory.h"
    click Persistence "https://github.com/inbasperu/visionguard/blob/main/third_party/utils/src/config_factory.cpp"
    click ModelStore "https://github.com/inbasperu/visionguard/tree/main/omz_models/"

    %% Styles
    classDef ui fill:#d4f4dd,stroke:#333,stroke-width:1px
    classDef core fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef infra fill:#ffe5b4,stroke:#333,stroke-width:1px
    classDef assets fill:#d3d3d3,stroke:#333,stroke-width:1px
```
