MindGuard AI Study Focus Tracker by Lingaraj PatilMindGuard AI Study Focus Tracker by Lingaraj Patil

MindGuard AI Study Focus Tracker

Lingaraj Patil

Completed work

Fullstack Engineer

Node.js

React

Electronics

🧠 MindGuard AI

AI-powered study focus tracker with on-device computer vision

Monitor attention · Detect phone distractions · Gamify study sessions — all privacy-first, running entirely in your browser.

Built for students, by students. Zero video leaves your device — ever.

🌐 Frontend mindguard-ai-tan.vercel.app ⚡ Backend API ai-study-tracker.vercel.app 📧 Demo Email demo@mindguard.ai 🔑 Demo Password demo1234

📑 Table of Contents

Vision System Deep Dive

Environment Variables

Roadmap

Contributing

License

✨ Features

🎯 Core Capabilities

Feature Description On-Device Face Tracking MediaPipe FaceLandmarker detects gaze direction & face presence — no cloud, no latency Phone Detection YOLOv8-nano ONNX model identifies phone usage in real-time at ~2 FPS Smart Timer Configurable focus sessions (15 / 30 / 45 / 60 / 90 min) with auto-pause on distraction XP & Leveling Earn 10 XP/min with streak multipliers (×1.5 at 3 days, ×2 at 7, ×3 at 30) Streak System Daily streak tracking with automatic reset at midnight UTC Site Blocking Chrome extension blocks distracting sites during active sessions

📊 Intelligence & Analytics

Feature Description Cognitive Profile AI-generated study behaviour analysis — Consistency Index, Flow State Detection, Fatigue Curve Focus Heatmap Visual timeline showing focused vs distracted periods throughout a session Session Analytics Detailed breakdown per session — focus %, phone events, duration, XP earned Burnout Detection Multi-signal burnout risk score (0–100) with LOW / MODERATE / HIGH / CRITICAL levels Phone Correlation Measures how phone presence impacts your focus score and recovery time Leaderboard Compete with other users on focus score, XP, and streaks

🏆 Gamification

Feature Description 16 Achievements Unlock badges like Marathon Mind, Laser Focus, Phone-Free Champion, Unstoppable Level Progression XP-based leveling (formula: level = floor(sqrt(xp / 100)) + 1) with visual progress bar Confetti Celebration Canvas-confetti burst on session completion 🎉 Streak Multipliers 1.5× at 3 days · 2× at 7 days · 3× at 30 days

🔒 Privacy-First Design

Guarantee How Zero cloud video All vision processing runs in-browser via WebAssembly No frames stored Camera feed is processed and immediately discarded Boolean signals only Backend receives { focused: true/false }, never pixels or images Webcam optional App works without camera (manual tracking mode) No biometrics Face landmarks are used locally for gaze math, never stored or transmitted

🏗 System Architecture

Data Flow — Study Session Lifecycle

🛡 Tech Stack

Layer Technology Purpose Frontend React 18, React Router v6 SPA with protected routes Styling Tailwind CSS 3, Lucide Icons Utility-first CSS, icon library Vision (Face) MediaPipe FaceLandmarker (WASM) 478-landmark face tracking via WebAssembly Vision (Phone) YOLOv8-nano, ONNX Runtime Web Object detection in browser (6 MB model) State Custom createStore() + useSyncExternalStore Zero-dependency pub/sub state management Backend Node.js 18+, Express 4 REST API server Security Helmet, express-rate-limit HTTP hardening, brute-force protection Database MongoDB + Mongoose 8 Document database with schema validation Auth JWT (jsonwebtoken) + bcryptjs Stateless authentication, password hashing Extension Chrome MV3 (Service Worker) Distraction blocking during sessions Scheduling node-cron Streak resets, zombie session cleanup Effects canvas-confetti Session completion celebrations

🚀 Getting Started

Prerequisites

Requirement Version Notes Node.js ≥ 18 Required for backend and frontend tooling MongoDB ≥ 6.0 Local install or MongoDB Atlas (free tier works) Google Chrome Latest Required for the site-blocking extension Webcam Any Optional — app works without camera

Installation

Configuration

Create .env files in both backend/ and frontend/ directories:

Backend backend/.env

Frontend frontend/.env

Running the App

Chrome Extension (Optional)

Navigate to chrome://extensions in Chrome

Enable Developer mode (toggle in top-right)

Click Load unpacked → select the extension/ folder

Pin the MindGuard AI icon in the toolbar

📁 Project Structure

📡 API Reference

Base URL: http://localhost:5000/api

All authenticated endpoints require the header:

Standard error response format:

Authentication

Rate limited: 20 requests per 15-minute window on all auth routes.

`POST /api/auth/register`

Create a new user account.

Field Type Required Constraints name string ✅ 2–100 characters, trimmed email string ✅ Must contain @, lowercased, unique password string ✅ 6–128 characters Example Request & Response

Request:

Response (201):

`POST /api/auth/login`

Authenticate and receive a JWT token.

Field Type Required email string ✅ password string ✅ Example Request & Response

Request:

Response (200):

Token expires in 30 days. Payload: { userId }.

`GET /api/auth/profile` 🔒

Get the authenticated user's profile.

Example Response

Sessions

All session endpoints require authentication 🔒

`POST /api/sessions/start`

Start a new focus session.

Field Type Required Default Constraints plannedDuration number No 3600 60–28800 seconds notes string No — Max 1000 characters Example Response

`POST /api/sessions/focus/:id`

Log a focus/distraction event during a session.

Field Type Required Description focused boolean ✅ true = focused, false = distracted

`POST /api/sessions/phone/:id`

Log a phone detection event during a session.

Field Type Required Description detected boolean ✅ true = phone visible, false = phone gone

`POST /api/sessions/end/:id`

End an active session. Automatically calculates:

Duration — actual seconds elapsed

Focus score — percentage of focused events (defaults to 100% if no events)

XP earned — floor(durationMinutes) × 10 × streakMultiplier

Streak update — increments or maintains current/longest streak

Example Response

XP Multiplier Table:

Streak Multiplier < 3 days 1× ≥ 3 days 1.5× ≥ 7 days 2× ≥ 30 days 3×

`POST /api/sessions/pause/:id`

Pause an active session.

`PATCH /api/sessions/notes/:id`

Update session notes.

Field Type Required Constraints notes string ✅ Max 1000 characters

`GET /api/sessions/active` 🔒

Returns the currently active session (if any), or null.

`GET /api/sessions/history` 🔒

Get paginated session history.

Query Param Type Default Constraints limit number 50 Max results per page offset number 0 Skip N records

`GET /api/sessions/:id` 🔒

Get full details for a specific session, including all focus and phone events.

Todos

All todo endpoints require authentication 🔒

Method Endpoint Description GET /api/todos List all todos (sorted by creation date, newest first) POST /api/todos Create a new todo PATCH /api/todos/:id/toggle Toggle completion status PATCH /api/todos/:id Update todo text/priority DELETE /api/todos/:id Delete a todo

`POST /api/todos` — Create Todo

Field Type Required Default Constraints text string ✅ — 1–500 characters, trimmed sessionId ObjectId No — Links todo to a specific session priority string No "medium" "low" | "medium" | "high"

Blocked Sites

All blocked site endpoints require authentication 🔒

Method Endpoint Description GET /api/blocked-sites List all blocked domains POST /api/blocked-sites Add a domain to blocklist DELETE /api/blocked-sites/:id Remove a domain from blocklist

`POST /api/blocked-sites` — Add Domain

Field Type Required Constraints url string ✅ 3–255 chars. Auto-sanitized: strips http(s)://, www., path segments. Lowercased. Duplicate check per user. Example

Request:

Stored as: reddit.com

Cognitive Analytics

All cognitive endpoints require authentication 🔒

`GET /api/cognitive/cognitive-profile`

Alias: GET /api/analytics/cognitive-profile

Returns a comprehensive AI-generated cognitive profile based on all historical sessions.

Full Response Schema

`GET /api/cognitive/session/:id`

Returns per-minute focus analysis for a single session.

Returns 422 if session is too short (< 60s) or has fewer than 2 focus events.

Response Schema

Leaderboard

`GET /api/leaderboard` 🔒

Query Param Type Default Options period string "all" "all" | "week" | "month" limit number 20 Max 50 Example Response

Sorting: "all" → by XP descending; "week" / "month" → by total minutes descending.

Health Check

`GET /api/health`

No authentication required.

📦 Data Models

User

Field Type Default Description name String — Display name (2–100 chars) email String — Unique, lowercased, trimmed password String — bcrypt hashed xp Number 0 Total experience points level Number 1 Current level currentStreak Number 0 Consecutive study days longestStreak Number 0 All-time best streak lastStudyDate Date — Last session end date createdAt Date now Account creation

Session

Field Type Default Description userId ObjectId → User — Session owner startTime Date now Session start endTime Date — Session end duration Number 0 Actual duration (seconds) focusScore Number 100 Focus percentage (0–100) xpEarned Number 0 XP awarded notes String — User notes (max 1000 chars) plannedDuration Number 3600 Target duration (seconds) focusEvents Array [] [{ focused: bool, timestamp: Date }] phoneEvents Array [] [{ detected: bool, timestamp: Date }] todos ObjectId[] → Todo [] Linked tasks isActive Boolean true Session in progress?

Indexes: userId, { userId, isActive }

Todo

Field Type Default Description userId ObjectId → User — Task owner sessionId ObjectId → Session — Linked session (optional) text String — Task description (1–500 chars) completed Boolean false Completion status priority String "medium" "low" / "medium" / "high" createdAt Date now Creation timestamp

BlockedSite

Field Type Default Description userId ObjectId → User — Site owner domain String — Blocked domain (3–255 chars) createdAt Date now When blocked

Index: { userId, domain } (unique compound)

👁 Vision System Deep Dive

The Vision System (VisionSystem.jsx — 897 lines) is the most complex component, running two parallel detection loops entirely in-browser.

Two-Loop Architecture

Loop Technology Interval Effective FPS Purpose Face/Gaze MediaPipe FaceLandmarker 350ms ~2.86 Face presence + iris-based gaze direction Phone YOLOv8-nano (ONNX Runtime) 500ms ~2 Cell phone object detection

Face & Gaze Detection (Loop 1)

Model: MediaPipe FaceLandmarker (float16), loaded from CDN via dynamic ESM import().

Pipeline:

getUserMedia captures webcam at native resolution

MediaPipe extracts 478 face landmarks (468 base + 10 iris)

Custom gaze algorithm (calculateGazeDirection):

Computes horizontal iris offset (landmarks 468, 473, 33, 133, 263, 362)

Computes vertical iris offset (landmarks 159, 145, 386, 374)

Thresholds: horizontal > 0.38 OR vertical > 0.35 → "looking away"

Consecutive-frame state machine:

No Face: 8 consecutive frames (~2.8s) + 2s grace window

Looking Away: 3 consecutive frames (~1.05s)

Focused: 2 consecutive frames (~0.7s) to regain focus

Phone Detection (Loop 2)

Model: YOLOv8-nano (yolov8n.onnx, ~6 MB), loaded as a module-level singleton — survives component re-mounts.

Pipeline:

Video frame drawn to hidden <canvas> at 640×640

RGB normalized to [0, 1] float32, transposed HWC → CHW

ONNX inference: input [1, 3, 640, 640] → output [1, 84, 8400]

Post-processing checks two COCO classes:

Class 67: "cell phone" (weight 1.0)

Class 65: "remote" (weight 0.85 — catches phone backs)

Confidence threshold: 0.25, min bbox area: 0.8% of frame

Greedy NMS with IoU threshold 0.45

Sliding Window Persistence (Anti-Flicker):

Window: 12 frames (~6 seconds)

Appear: ≥ 3 of last 12 frames → phone confirmed (~1.5s lag)

Dismiss: ≤ 1 of last 12 frames → phone gone (~6s to dismiss)

Hysteresis between thresholds retains current state

Enforcement Chain:

Phone stable → onPhoneDetected callback fires

Enforcement timer starts (1s interval)

After 15s continuous detection → auto-pause session

Phone gone → enforcement stops

Privacy Architecture

🧬 Cognitive Engine

The Cognitive Engine (cognitiveEngine.js + cognitiveHelpers.js) performs pure server-side computation on boolean focus/phone event data to generate rich analytics.

Session-Level Analysis

Metric Description Per-minute Bucketing Groups focus events into 1-minute buckets with carry-forward for empty minutes Phase Scoring Splits session into early (first 5 min), mid, and late (last 5 min) phases Distraction Frequency Distraction events per minute Recovery Time Average seconds from distraction start to focus regain Focus Volatility Standard deviation of per-minute focus percentages Strongest Window Sliding 5-minute window with highest average focus score

Pattern Classification

Each session receives one or more labels:

Pattern Condition WarmUpPattern Early focus ≪ Late focus (≥ 20% gap) FatiguePattern Late focus ≪ Early focus (≥ 20% gap) FragmentedAttention Distraction frequency > 3/min StableFocus Volatility < 10 AND focus ≥ 70% SlowRecovery Average recovery > 30 seconds Normal Fallback when no other pattern matches

Burnout Risk Score (0–100)

Weighted multi-signal formula:

Signal Weight Declining focus slope (weekly) 30% Duration drop (trend) 20% Increasing distraction trend 20% Focus volatility 15% Streak instability 15% Phone correlation bonus Up to +7.5

Score Range Risk Level 0–30 🟢 LOW 31–60 🟡 MODERATE 61–80 🟠 HIGH 81–100 🔴 CRITICAL

Cognitive Health Score (0–100)

Component Weight Average focus score (all-time) 30% Consistency (inverse of focus stddev) 20% Recovery efficiency 15% Session regularity 20% Task completion rate 15%

Phone-Distraction Correlation

Splits sessions into phone-present vs phone-absent groups and computes:

Signal Weight Ratio of focus-loss events temporally near phone events 40% Focus score delta between groups 30% Volatility increase with phone present 30%

Scalability Strategy

The cognitive profile uses a two-query approach:

Query 1: ALL completed sessions (lightweight projection, no focusEvents) → aggregate stats

Query 2: Last 30 days (full documents) → detailed per-minute analysis

This keeps response times fast even with thousands of sessions.

🔌 Chrome Extension

Architecture

The Chrome MV3 extension uses a Service Worker background script with these capabilities:

Feature Mechanism Site Blocking Redirects matching navigations to blocked.html Session Awareness Polls /api/sessions/active every 15 seconds Blocklist Sync Fetches /api/blocked-sites every 5 minutes Domain Matching Strips www., checks exact match + subdomain Active-Only Blocking Sites are only blocked during active study sessions

Blocking Triggers

Trigger Chrome API Navigation attempt chrome.webNavigation.onBeforeNavigate (main frame only) Tab URL update chrome.tabs.onUpdated (on "complete" status) Tab switch chrome.tabs.onActivated Session start Scans ALL open tabs immediately

Extension ↔ Popup Communication

Action Direction Purpose toggleExtension Popup → Background Enable/disable blocking setToken Popup → Background Set/clear auth token syncSites Popup → Background Manual sync trigger getStatus Popup → Background Get full status snapshot sessionUpdate Popup → Background Notify of session start/stop checkSession Popup → Background Force session status check

🏆 Achievement System

16 unlockable achievements stored in localStorage under key mindguard_achievements:

Badge Title Condition 🎓 First Steps Complete 1 session 📚 Getting Started Complete 5 sessions ⚔️ Study Warrior Complete 20 sessions 🏆 Knowledge Seeker Complete 50 sessions 🧘 Deep Focus Complete a 60-minute session 🏃 Marathon Mind Complete a 120-minute session 🔥 On a Roll Reach a 3-day streak 💪 Weekly Champion Reach a 7-day streak 👑 Unstoppable Reach a 30-day streak 🎯 Laser Focus Achieve 90%+ focus score 💎 Perfect Focus 100% focus in a 10+ min session ⭐ Rising Star Earn 1,000 XP 🌟 Bright Mind Earn 5,000 XP 📖 Scholar Reach level 5 🎓 Master Reach level 10 📵 Phone Free Complete a session with zero phone detections

⏰ Background Jobs

Two cron jobs run on the backend:

Job Schedule Description Zombie Session Cleanup Every 30 minutes Finds sessions with isActive: true and startTime > 6 hours ago. Auto-ends them with calculated duration, marks isActive: false, appends "[Auto-closed]" to notes. Streak Reset Daily at midnight UTC Iterates all users. If lastStudyDate is neither yesterday nor today, resets currentStreak to 0.

🔐 Security

Measure Implementation Helmet Sets security HTTP headers (X-Frame-Options, CSP, etc.) CORS Whitelist: localhost:3000/3001 (dev), FRONTEND_URL (prod), chrome-extension://* Rate Limiting 20 requests / 15 min on /api/auth/* routes JWT 30-day expiry, HS256 signing, userId payload only Password Hashing bcryptjs with auto-generated salt Input Validation Length limits, type checks, email format validation on all routes No Pixel Data Backend never receives, processes, or stores any image/video data

🔧 Environment Variables

Backend (`backend/.env`)

Variable Required Default Description MONGODB_URI ✅ — MongoDB connection string JWT_SECRET ✅ — Secret for signing JWT tokens PORT No 5000 Server port NODE_ENV No development development | production FRONTEND_URL Production only — Frontend URL for CORS in production

Frontend (`frontend/.env`)

Variable Required Default Description REACT_APP_API_URL No http://localhost:5000/api Backend API base URL

🗺 Roadmap

Pomodoro Mode — structured work/break intervals with configurable cycles

Study Groups — collaborative focus rooms with real-time presence

Weekly Reports — email digest with focus trends and insights

Mobile App — React Native companion for on-the-go tracking

Dark Mode — system-aware theme switching (foundation already built)

Export Data — CSV/PDF session reports and analytics

Custom Achievements — user-defined goals and milestones

Browser Extension v2 — Firefox + Edge support

Spaced Repetition — integrated flashcard system linked to study sessions

Focus Music — ambient soundscapes that adapt to focus state

🤝 Contributing

Contributions are welcome! Here's how to get started:

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

Development Tips

Backend hot-reload: cd backend && npm run dev (uses nodemon)

Frontend hot-reload: cd frontend && npm start (Create React App)

The YOLO model singleton persists across React hot reloads — no repeated loading

Vision system throttles React state updates to ≤ 1/s to prevent render storms

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

⭐ Star this repo if MindGuard AI helps you study better!

MindGuard AI — Focus smarter, not harder. 🧠✨

Made with ❤️ by Lingaraj Patil

Like this project

Completed work

Posted Aug 6, 2026

Developed an AI-powered study focus tracker running entirely in the browser.

Likes

Views

MindGuard AI Study Focus Tracker

🧠 MindGuard AI

📑 Table of Contents

✨ Features

🎯 Core Capabilities

📊 Intelligence & Analytics

🏆 Gamification

🔒 Privacy-First Design

🏗 System Architecture

Data Flow — Study Session Lifecycle

🛡 Tech Stack

🚀 Getting Started

Prerequisites

Installation

Configuration

Running the App

Chrome Extension (Optional)

📁 Project Structure

📡 API Reference

Authentication

POST /api/auth/register

POST /api/auth/login

GET /api/auth/profile 🔒

Sessions

POST /api/sessions/start

POST /api/sessions/focus/:id

POST /api/sessions/phone/:id

POST /api/sessions/end/:id

POST /api/sessions/pause/:id

PATCH /api/sessions/notes/:id

GET /api/sessions/active 🔒

GET /api/sessions/history 🔒

GET /api/sessions/:id 🔒

Todos

POST /api/todos — Create Todo

Blocked Sites

POST /api/blocked-sites — Add Domain

Cognitive Analytics

GET /api/cognitive/cognitive-profile

GET /api/cognitive/session/:id

Leaderboard

GET /api/leaderboard 🔒

Health Check

GET /api/health

📦 Data Models

User

Session

Todo

BlockedSite

👁 Vision System Deep Dive

Two-Loop Architecture

Face & Gaze Detection (Loop 1)

Phone Detection (Loop 2)

Privacy Architecture

🧬 Cognitive Engine

Session-Level Analysis

Pattern Classification

Burnout Risk Score (0–100)

Cognitive Health Score (0–100)

Phone-Distraction Correlation

Scalability Strategy

🔌 Chrome Extension

Architecture

Blocking Triggers

Extension ↔ Popup Communication

🏆 Achievement System

⏰ Background Jobs

🔐 Security

🔧 Environment Variables

Backend (backend/.env)

Frontend (frontend/.env)

🗺 Roadmap

🤝 Contributing

Development Tips

📄 License

⭐ Star this repo if MindGuard AI helps you study better!

`POST /api/auth/register`

`POST /api/auth/login`

`GET /api/auth/profile` 🔒

`POST /api/sessions/start`

`POST /api/sessions/focus/:id`

`POST /api/sessions/phone/:id`

`POST /api/sessions/end/:id`

`POST /api/sessions/pause/:id`

`PATCH /api/sessions/notes/:id`

`GET /api/sessions/active` 🔒

`GET /api/sessions/history` 🔒

`GET /api/sessions/:id` 🔒

`POST /api/todos` — Create Todo

`POST /api/blocked-sites` — Add Domain

`GET /api/cognitive/cognitive-profile`

`GET /api/cognitive/session/:id`

`GET /api/leaderboard` 🔒

`GET /api/health`

Backend (`backend/.env`)

Frontend (`frontend/.env`)