All metrics are logged to an SQLite database for historical analysis and dashboard visualization.

✨ Features

User Authentication

• Secure signup and login system with PBKDF2-HMAC SHA-256 password hashing
• Multi-user support — each user has their own sessions, metrics, and history
• Clean login/signup UI with form validation and error feedback

Real-Time Posture Detection

• Continuous webcam monitoring using MediaPipe Pose
• Classifies posture into 4 categories: Good, Slightly Bad, Bad, Very Bad
• Angle-based classification (back and neck deviation from vertical, based on ISO 11226)
• Real-time posture metrics displayed in the monitoring window

Screen Time & Break Management

• Tracks continuous and cumulative screen time per session
• Automatically detects breaks when user is not visible for a configurable period
• Logs break duration and frequency to the database
• Configurable screen time limits

Burnout Prediction

• Pre-trained scikit-learn classifier loaded from data/burnout_model.pkl
• Generates burnout probability score (0.0–1.0)
• Risk classification: Low Risk (<0.7) and High Risk (≥0.7)
• Periodic predictive evaluations at configurable intervals

Desktop Notification Popups

• Custom PyQt5 notification popups that slide in from the bottom-right corner
• Color-coded by alert type (posture, screen time, burnout, break, user detection)
• Auto-dismiss with fade-out animation; stackable when multiple alerts arrive
• System tray icon integration for persistent background presence

Analytics Dashboard

• Fully implemented PyQt5 dashboard accessible from the monitoring window
• Posture distribution charts, screen time trends, burnout assessment history
• Session-level analytics with aggregated metrics
• Auto-refreshing data at configurable intervals

Comprehensive Logging

• Application-wide logging to console and file (data/deskguardian.log)
• All posture, break, and alert events logged to the SQLite database
• Full session history with metrics and timestamps

🏗 System Architecture

┌─────────────────────────────────────────────────────────────┐
│                    DeskGuardianApp (main.py)                  │
│          Application controller: Login → Monitoring           │
└──────────────────┬──────────────────────────────┬────────────┘
                   │                              │
          ┌────────▼────────┐           ┌─────────▼──────────┐
          │  LoginSignupPage│           │ MonitoringWindow    │
          │  (modules/gui/) │           │ (modules/gui/)      │
          └────────┬────────┘           └───┬─────────┬──────┘
                   │                        │         │
          ┌────────▼────────┐               │    ┌────▼───────┐
          │  AuthService    │               │    │DashboardUI │
          │  (modules/auth/)│               │    │(modules/   │
          └─────────────────┘               │    │ dashboard/)│
                                            │    └────────────┘
           ┌────────────────────────────────┘
           │
    ┌──────▼──────────────────────────────────────────────┐
    │            Core Components (per session)              │
    ├──────────┬──────────┬───────────┬───────────────────┤
    │PoseDetect│SessionMgr│BurnoutMdl │NotificationEngine │
    │(MediaPipe│(Behavior │(ML Model) │(Popups + DB Log)  │
    │ + OpenCV)│ Tracking)│           │                   │
    └────┬─────┴────┬─────┴─────┬─────┴─────┬─────────────┘
         │          │           │           │
         └──────────┴───────────┴───────────┘
                         │
                    ┌────▼────┐
                    │DBManager│
                    │(SQLite) │
                    └┬────────┘
                     │
           ┌─────────▼──────────┐
           │    Database File   │
           │(data/deskguardian) │
           └────────────────────┘

🛠 Tech Stack

📁 Project Structure

DeskGuardian/
├── main.py                          # Application entry point (QApplication + tray icon)
├── requirements.txt                 # Python dependencies
├── DeskGuardian.spec                # PyInstaller spec for building .exe
├── README.md                        # This file
│
├── config/
│   ├── constants.py                 # Thresholds, limits, timings, alert types
│   └── settings.py                  # Feature toggles (logging, alerts)
│
├── core/
│   ├── system_controller.py         # Central orchestrator (headless/CLI mode)
│   ├── state_manager.py             # System state machine
│   └── background_timer.py          # Screen time and burnout check timers
│
├── database/
│   ├── db_manager.py                # SQLite CRUD operations
│   ├── models.py                    # Data models / schemas
│   └── schema.sql                   # Database schema definition (6 tables)
│
├── modules/
│   ├── auth/
│   │   └── auth_service.py          # User registration & login (password hashing)
│   │
│   ├── gui/
│   │   ├── login_page.py            # Login / Signup PyQt5 window
│   │   ├── monitoring_window.py     # Live camera feed + metrics + dashboard access
│   │   └── notification_popup.py    # Slide-in desktop notification popups
│   │
│   ├── behavior_tracking/
│   │   ├── session_manager.py       # Session lifecycle & integration layer
│   │   ├── screen_time_tracker.py   # Screen time metrics
│   │   └── break_detector.py        # Break event detection
│   │
│   ├── burnout_prediction/
│   │   ├── burnout_model.py         # ML model inference
│   │   └── feature_engineering.py   # Feature extraction for ML
│   │
│   ├── posture_detection/
│   │   ├── pose_detector.py         # Webcam & pose landmark extraction
│   │   ├── posture_classifier.py    # Angle-based posture classification
│   │   └── posture_metrics.py       # Angle computation (back, neck, shoulder)
│   │
│   ├── notification/
│   │   └── notification_engine.py   # Alert generation, popup dispatch, DB logging
│   │
│   └── dashboard/
│       ├── dashboard_ui.py          # PyQt5 analytics dashboard
│       └── analytics_engine.py      # Data aggregation for dashboard
│
├── tests/
│   ├── conftest.py                  # Pytest configuration
│   ├── test_analytics_engine.py     # Dashboard analytics tests
│   ├── test_auth_service.py         # Authentication tests
│   ├── test_break_detector.py       # Break detection tests
│   ├── test_helpers.py              # Utility function tests
│   ├── test_login_page_gui.py       # Login page GUI tests
│   ├── test_notification_engine.py  # Notification engine tests
│   └── test_posture_classifier.py   # Posture classification tests
│
├── utils/
│   ├── enums.py                     # PostureClass, AlertType, SystemState
│   ├── helpers.py                   # Utility functions
│   └── logger.py                    # Centralized logging
│
├── data/                            # Runtime data directory
│   ├── deskguardian.db              # SQLite database
│   ├── deskguardian.log             # Application log file
│   ├── burnout_model.pkl            # Pre-trained burnout classifier
│   └── burnout_scaler.pkl           # Feature scaler for burnout model
│
├── dist/                            # PyInstaller output (built executable)
├── build/                           # PyInstaller build artifacts
└── venv/                            # Python virtual environment

🚀 Installation & Setup

Prerequisites

• Python 3.10 or higher
• Webcam (required for pose detection)
• 20MB+ disk space (for database, logs, and ML models)
• Windows (primary target; macOS/Linux compatible with minor adjustments)

Step 1: Clone Repository

git clone https://github.com/7vik2005/DeskGuardian.git
cd DeskGuardian

Step 2: Create Virtual Environment

# On Windows
python -m venv venv
venv\Scripts\activate

# On macOS/Linux
python3 -m venv venv
source venv/bin/activate

Step 3: Install Dependencies

pip install -r requirements.txt

Step 4: Run the Application

python main.py

You should see:

1. The Login / Signup window appears
2. After logging in, the Monitoring Window opens with live camera feed
3. Real-time posture classification and metrics displayed in the bottom bar
4. Desktop notification popups appear for alerts

📦 Building a Standalone Executable

DeskGuardian can be packaged as a standalone Windows executable using PyInstaller:

# Install PyInstaller (if not already installed)
pip install pyinstaller

# Build using the included spec file
pyinstaller DeskGuardian.spec

The built application will be available in dist/DeskGuardian/. Run DeskGuardian.exe to launch without needing a Python installation.

⚙️ Configuration

All configuration is centralized in the config/ directory:

config/constants.py

Contains system-wide thresholds:

# Posture angle thresholds (degrees deviation from vertical, based on ISO 11226)
GOOD_POSTURE_MAX_BACK_ANGLE = 15
GOOD_POSTURE_MAX_NECK_ANGLE = 15
SLIGHT_BAD_POSTURE_MAX_BACK_ANGLE = 25
SLIGHT_BAD_POSTURE_MAX_NECK_ANGLE = 25
BAD_POSTURE_MAX_BACK_ANGLE = 40
BAD_POSTURE_MAX_NECK_ANGLE = 40

# Screen