Real-Time Posture Detection and Active Break Reminders for Desktop
ActiveBreak is a cross-platform Electron desktop application that helps users maintain healthy posture and stay active during computer work. Powered by TensorFlow.js and the MoveNet Lightning model, it performs real-time posture analysis, active break management, challenge progression, and event tracking — all executed locally for full privacy. The system includes break timers, guided micro-exercises, reward progression, persistent per-user settings, and a complete history of posture, alerts, breaks, and challenge achievements.
The application includes a built-in rewards and challenges system that tracks the user’s posture consistency, break compliance, and daily activity. Challenge progress is computed from posture_events and break_events, and users can review their active challenges, historical completions, and progress percentage for each period.
- Role-based access control (Admin/Client)
- SQLite3 database with bcrypt password hashing (10 salt rounds)
- Admin dashboard for user management
- Session-based authentication with route protection
- The authentication system includes a persistent session layer and an AuthGuard that validates every IPC request based on user role and active session. All privileged routes (stats, events, settings, rewards, breaks) are protected, and the renderer has no direct database access other than through the sanitized API exposed in preload.js.
- AI-powered pose detection using MoveNet Lightning (TensorFlow.js)
- Military-grade classification algorithm with 3 strict rules:
- Horizontal centering (15% tolerance)
- Upright spine analysis (50% height requirement)
- Shoulder symmetry (10% tilt tolerance)
- Visual skeleton overlay (17 keypoints)
- Intelligent feedback with specific correction messages
- Internally, the posture engine stabilizes predictions by consolidating classification once per second, applying confidence filters to each of the 17 keypoints, and requiring consecutive frames of consistent misalignment before triggering a state change.
- Notifications use a cooldown system that prevents repeated alerts during sustained bad posture periods, and posture_events are logged once per second to enable precise analytics and challenge tracking.
- Cumulative statistics tracking (correct/incorrect posture time)
- Interactive Chart.js visualizations (daily posture breakdown)
- Event history with timestamps (session start/end, posture changes)
- Date-range filtering for historical data analysis
- Trend analysis with period-over-period comparison
- CSV export functionality
- Analytics are powered by four event streams stored in the database: posture_events, alert_events, break_events, and challenge_events. Each event is timestamped and normalized to daily, weekly, and monthly aggregates, enabling comparative analytics across multiple periods. The engine supports period-type queries (day/week/month) and returns both absolute metrics and deltas for trend analysis.
- Native OS desktop notifications with sound
- Configurable alert threshold (1-60 seconds of bad posture)
- Automatic break reminders with countdown timer (5-120 minutes)
- Random stretching exercise suggestions
- Spam prevention logic
- The break reminder system includes a dedicated timer that tracks the remaining time until the next active break. When triggered, the app displays a guided micro-exercise suggestion and records a break_event for analytics and reward progression. Break reminders include their own cooldown to avoid repeated prompts when the user is switching windows or temporarily inactive.
ActiveBreak includes a full active-break module that schedules guided micro-exercises, tracks the duration and completion of each break, and records break events for progress analytics. The system manages countdowns, exercise suggestions, cooldown periods, and streak preservation. These breaks contribute directly to the challenge and reward progression system.
- Detection sensitivity adjustment (1-10 scale)
- Toggle notifications on/off
- Configurable alert threshold and break intervals
- Persistent settings across sessions
- Accessible to both admin and client users
- Each user manages their own personal settings
- Each setting is applied immediately to the detection engine without restarting the application. Sensitivity maps directly to the minimum keypoint confidence for MoveNet, and alert/break thresholds update the internal timers and cooldown logic in real time.
- Modern dark theme with Inter font and Feather Icons
- CSS variable design system
- Smooth micro-interactions and hover effects
- Responsive layout with gradient backgrounds
- Node.js (v16 or higher)
- npm (v7 or higher)
- Webcam access
- Clone the repository and navigate to the project folder:
cd ActiveBreakApp- Install dependencies:
npm install- Start the application:
npm startThe application will automatically load the camera, AI model (MoveNet Lightning), and begin real-time posture detection.
To package the application for your current platform:
npm run buildDistributable files (.exe, .dmg, or .AppImage) will be located in the dist/ folder.
Supported Platforms:
- Windows (NSIS Installer + Portable EXE)
- macOS (DMG)
- Linux (AppImage)
Known Build Notes:
- The build process may show symbolic link errors on Windows during code-signing tool extraction. This is cosmetic and does not affect functionality.
- Executable size: ~210MB (includes Electron + TensorFlow.js + dependencies)
For detailed technical documentation, see:
- AI_AGENT_GUIDE.md: Comprehensive technical guide for AI agents and developers (IPC API, business logic, authentication flow)
- architecture.mmd: Mermaid diagram showing application architecture and data flow
- database.mmd: Entity-relationship diagram (ERD) for SQLite3 database schema
- tree.txt: Complete project file structure
Quick Architecture Overview:
- Main Process (
main.js): Database operations, IPC handlers, window management - Renderer Processes: Posture detection (
script.js), admin dashboard, settings - IPC Bridge (
preload.js): Secure communication via contextBridge - Database: SQLite3 with 5 tables (users, user_settings, user_stats, posture_events, alert_events)
- Security: bcrypt password hashing, role-based access control, context isolation
- Electron 38.4.0 - Cross-platform desktop framework
- TensorFlow.js 4.22.0 - Machine learning inference
- MoveNet Lightning - Ultra-fast pose detection model
- SQLite3 5.1.7 - Embedded database
- bcrypt 6.0.0 - Password hashing
- Chart.js - Data visualization
- ES6 Modules - Modern JavaScript
- Inter Font - Professional typography
- Feather Icons - Modern iconography
- Landing Page: Choose between Admin or Client access
- Login/Registration:
- Admins: Can self-register from the landing page
- Clients: Login only (accounts created by admins)
- Security: Passwords hashed with bcrypt (10 salt rounds)
- Database: Users stored in
data/users.sqlite - Role-Based Access:
- Admins: Full access (posture detection, settings, user management)
- Clients: Access to posture detection and personal settings
- Navigation bar with quick access to:
- Dashboard home
- Client registration
- Settings
- Logout
- View all registered users (email, role, creation date)
- Create new client accounts
- Delete user accounts with confirmation
- Self-deletion detection with automatic logout
- Accessible to both admin and client users
- Each user manages their own personal settings
- Dynamic navigation: Home button adapts based on role
- Admins: Returns to admin dashboard
- Clients: Returns to main app
- Settings include sensitivity, notifications, thresholds, and break intervals
- Camera Initialization: Requests webcam access
- AI Model Loading: Loads MoveNet Lightning model
- Real-Time Detection: Analyzes each video frame for 17 body keypoints
- Posture Classification: Applies 3 strict rules simultaneously:
- Rule 1: Horizontal centering (15% tolerance)
- Rule 2: Upright spine angle (±15° from vertical using Math.atan2)
- Rule 3: Shoulder symmetry (10% tilt tolerance)
- Intelligent Feedback: Displays specific correction messages:
- ✅ Green: "Postura Correcta"
⚠️ Red: "Centra tu cabeza" / "Endereza tu espalda" / "Nivela tus hombros"
- Desktop Notifications: Triggers after configurable threshold (default: 3 seconds of bad posture)
- Automatic Tracking: Records time in each posture state (1-second intervals)
- Session Management: Logs session start/end events, cumulative statistics
- Break Reminders: Periodic notifications with exercise suggestions
- Cumulative Stats: Total time in correct/incorrect posture across all sessions
- Interactive Charts: Daily posture breakdown with Chart.js visualizations
- Event History: Timestamped log of posture changes, sessions, alerts (pagination: 20 events per page)
- Date Filtering: Analyze specific time ranges
- Trend Analysis: Period-over-period comparison with percentage changes
- CSV Export: Download historical data for external analysis
- Rewards System:
- Sensitivity (1-10): Adjusts AI confidence threshold
- Notifications: Toggle on/off
- Alert Threshold (1-60 seconds): Time before bad posture notification
- Break Interval (5-120 minutes): Time between break reminders
- Persistence: All settings saved to database
Login
Posture Detection
Active Break
Statistics
Rewards System
Settings Panel
Contributions are welcome! Please follow these guidelines:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
For AI agents: Please review AI_AGENT_GUIDE.md for technical context and development guidelines.
This project is open-source and available under the MIT License.
Josh Sebastián López Murcia Franklin Julián González Pérez
- Real-time posture detection with military-grade classification
- Production authentication system (SQLite3 + bcrypt)
- Role-based access control (admin/client)
- Admin dashboard with user management
- Statistics tracking with persistence
- Interactive charts and analytics
- Desktop notifications and break reminders
- Date-range filtering and trend analysis
- CSV export functionality
- Visual posture correction guides
- Build and distribution configuration
- Multi-user session management with JWT tokens
- Cloud backup for statistics
- Mobile companion app
- Posture calibration for different body types
- Weekly/monthly progress reports via email
- Integration with fitness trackers
For questions, issues, or feature requests, please open an issue on GitHub.
Project Status: Production Ready 🎉
Version: 12.0
Last Updated: January 2025
Note: This application requires webcam access to function. All posture detection happens locally on your device - no data is sent to external servers.