🚀 StudyFlow — Intelligent Productivity Ecosystem

A modern full-stack study & productivity application
Designed for deep focus, clarity, and consistent growth.

🚀 StudyFlow — Intelligent Productivity Ecosystem

🔴 Live Demo • 🐛 Report Bug • ✨ Request Feature

## 🎯 About StudyFlow

StudyFlow is a full-stack productivity and study-management application designed to help students and self-learners stay focused, track progress, and build consistent study habits.

It combines the Pomodoro technique, real-time analytics, task & subject management, and immersive focus music into a single modern experience.

⚡ Quick Start

# 1. Clone the repository
git clone https://github.com/salahuddingfx/Study-Flow.git
cd Study-Flow

# 2. Install backend dependencies
cd Backend
npm install

# 3. Create .env file with your credentials
cp .env.example .env
# Edit .env with your MongoDB URI, JWT secret, and Gemini API key

# 4. Start the backend server
npm start

# 5. Open index.html with Live Server or visit http://localhost:5000

📖 Detailed Setup: See Installation & Setup section below

🚀 Try it now: Live Demo

✨ Key Features

🎯 Core Productivity Features

⏱️ Smart Pomodoro Timer
Fully customizable focus & break sessions with visual progress
📊 Deep Analytics Dashboard
Daily, weekly & monthly productivity insights with interactive charts
🔥 Study Streak Tracker ⭐ NEW
Track daily consistency, build habit chains, unlock milestones & compete on leaderboards
🎵 Integrated Music Player
YouTube links & local audio support for focus music
📝 Intelligent Workflow Manager
Tasks, subjects & goal tracking with deadline management
🤖 AI Study Assistant ⭐ NEW
Powered by Google Gemini - Get study tips, quiz generation, and smart recommendations
🏆 Gamified Achievements
Unlock rewards and badges for reaching study milestones
📧 Email Progress Reports
Automated PDF reports with multi-page analytics via Brevo API

🔐 Security & Authentication

🔒 Secure Authentication
JWT tokens with 30-day expiry + Bcrypt password encryption
🔑 Password Recovery
Email-based password reset functionality
👤 User Profiles
Customizable profiles with avatar support

⚡ Performance & Technology

🚀 Lightning Fast
90+ Lighthouse performance score with optimized loading
💾 Offline First
Service Worker v5 with smart caching strategies
📱 PWA Ready
Install as native app on any device
⚡ Real-time Sync
Live updates via Socket.IO for instant collaboration

🎨 User Experience

🌓 Custom Themes
Multiple beautiful themes with dark/light modes
📱 Fully Responsive
Optimized for mobile, tablet, and desktop
♿ Accessible
WCAG 2.1 compliant with keyboard navigation
🔔 Smart Notifications
Browser notifications for timer completion and reminders

🔍 SEO & Discovery

📈 Search Engine Optimized
Structured data (JSON-LD) for rich search results
🌐 Social Media Ready
Perfect Open Graph and Twitter Card previews
🗺️ Sitemap & Robots.txt
Proper indexing for search engines

🚀 Coming Soon (v2.5) — Full Stack Features

All features include complete Frontend UI + Backend API implementations

📝 Advanced Note-Taking ⭐ IN PROGRESS
Markdown editor with syntax highlighting & auto-save functionality
Frontend: Rich text editor | Backend: Notes API + MongoDB storage
👥 Social Study Groups ⭐ IN PROGRESS
Create rooms, invite friends, and study together in real-time
Frontend: Group UI + Socket.IO | Backend: Room management API + Real-time sync
🤝 Collaborative Study Rooms ⭐ IN PROGRESS
Share sessions, compete on leaderboards, and group challenges
Frontend: Room interface | Backend: Session sharing API + WebSocket
⏱️ Pomodoro Group Sessions ⭐ IN PROGRESS
Synchronized timers for collaborative study groups
Frontend: Sync timer UI | Backend: Timer coordination API + Broadcasting
📴 Enhanced Offline Mode ⭐ IN PROGRESS
Full functionality without internet connection
Frontend: Service Worker v6 + IndexedDB | Backend: Sync queue API
📊 Advanced Statistics Export ⭐ IN PROGRESS
Generate detailed reports in PDF, Excel, and CSV formats
Frontend: Export UI + jsPDF | Backend: Report generation API + Templates

🏆 Achievement System

StudyFlow includes a comprehensive gamified achievement system to motivate consistent study habits. Earn points and unlock badges by reaching milestones across multiple categories:

📚 Study Time Achievements

First Steps: Complete 1 study session (10 points)
Hour Master: Study for 1 hour total (15 points)
Dedicated Scholar: Study for 10 hours total (50 points)
Study Warrior: Study for 50 hours total (150 points)
Study Warrior: Study for 100 hours total (300 points)

🔥 Streak & Consistency Achievements

Week Warrior: 7-day study streak (75 points) 🔥
Fortnight Focus: 14-day study streak (150 points) 🔥
Month Master: 30-day study streak (300 points) 🔥
Persistence Pro: 60-day study streak (600 points) 🔥
Centurion: 100-day study streak (1000 points) 🔥
Year Legend: 365-day study streak (3650 points) 🔥
Perfect Week: Study every day for a week (100 points)

🎯 Goal & Task Achievements

Goal Crusher: Complete 1 goal (20 points)
Goal Master: Complete 10 goals (100 points)
Goal Champion: Complete 50 goals (500 points)
Subject Explorer: Create 1 subject (10 points)
Task Manager: Complete 1 task (15 points)
Task Champion: Complete 50 tasks (80 points)
Task Master: Complete 100 tasks (200 points)

🧠 Quiz Performance Achievements

Quiz Novice: Complete first quiz (10 points)
Quiz Master: Complete 10 quizzes (50 points)
Perfect Score: Score 100% on a quiz (25 points)
High Achiever: Score 90%+ on 5 quizzes (75 points)

💡 Pro Tip: Achievements unlock automatically as you progress. Check your profile to see earned badges and track your journey to becoming a study master!

🔥 Streak Leaderboard: Compete globally! Top 10 streakers are featured on the leaderboard with their current and longest streaks displayed.

🛠️ Technology Stack

🖥️ Frontend

⚙️ Backend

🗄️ Database

� Performance & Optimization

⚡ Lightning-Fast Load Times

StudyFlow has been meticulously optimized for maximum performance:

Core Web Vitals (Target Metrics)

LCP (Largest Contentful Paint): < 2.5s
Content appears almost instantly
FID (First Input Delay): < 100ms
Instant response to user interactions
CLS (Cumulative Layout Shift): < 0.1
Stable layout, no jumps or shifts
FCP (First Contentful Paint): < 1.8s
Fast initial rendering
TTI (Time to Interactive): < 3.8s
Fully functional quickly

🎯 Lighthouse Scores (Target)

Performance:      90+ ⚡
SEO:              95+ 🔍
Accessibility:    95+ ♿
Best Practices:   95+ ✨
PWA:             100 📱

🛠️ Optimization Techniques Applied

1. Critical Rendering Path

✅ Inlined critical CSS for instant first paint
✅ Deferred non-critical JavaScript
✅ Async loading for third-party libraries
✅ DNS prefetch for CDN resources
✅ Preload hints for critical assets

2. Smart Caching Strategy

✅ Service Worker v5 with multi-tier caching
✅ Cache-First for CDN resources (7-day TTL)
✅ Stale-While-Revalidate for local assets
✅ Network-First for API calls
✅ Offline fallback support

3. Resource Optimization

✅ Lazy loading for images and heavy components
✅ Code splitting for better bundle size
✅ Minified CSS and JavaScript
✅ Compressed assets (gzip/brotli ready)
✅ Browser caching (1-year for static assets)

4. SEO Enhancements

✅ Structured data (JSON-LD Schema.org)
✅ Proper meta tags and Open Graph
✅ Sitemap.xml for search engines
✅ Robots.txt for crawl control
✅ Canonical URLs to prevent duplicates
✅ Rich snippets for social sharing

5. Security Headers

✅ X-Frame-Options: DENY
✅ X-Content-Type-Options: nosniff
✅ X-XSS-Protection: enabled
✅ Referrer-Policy: strict-origin-when-cross-origin
✅ Content Security Policy (CSP) ready

�📋 Prerequisites

Before you begin, make sure all the above tools are installed and properly configured.

🚀 Installation & Setup

1️⃣ Clone the Repository

git clone https://github.com/salahuddingfx/Study-Flow.git
cd Study-Flow

2️⃣ Install Dependencies

cd Backend
npm install

3️⃣ Environment Configuration

Create a .env file in the Backend directory:

PORT=5000
MONGO_URI=your_mongodb_connection_string
JWT_SECRET=your_super_secret_key
NODE_ENV=development

# AI Configuration (Unlimited Models Available!)
GEMINI_API_KEY=your_google_gemini_api_key
GEMINI_MODEL=gemini-2.0-flash-exp  # Default: unlimited experimental model

Available AI Models:

gemini-2.0-flash-exp - ⚡ Unlimited (Recommended)
gemini-exp-1206 - ⚡ Unlimited
gemma-2-9b-it - Gemma 9B
gemma-2-27b-it - Gemma 27B
gemini-2.5-flash - ⚠️ Rate Limited (5 RPM/20 RPD)

4️⃣ Start the Backend Server

npm start

5️⃣ Run the Frontend

Use VS Code Live Server (recommended)

Backend → http://localhost:5000
Frontend → http://127.0.0.1:5500/index.html (Live Server)

Or serve from the backend directly at http://localhost:5000.

🚀 Deployment Guide

StudyFlow is optimized for multiple deployment platforms:

🌐 Option 1: Netlify (Recommended)

# Install Netlify CLI
npm install -g netlify-cli

# Login
netlify login

# Deploy
netlify deploy --prod --dir=.

Features:

✅ Automatic HTTPS
✅ Global CDN
✅ Custom domains
✅ Auto-deploy from Git
✅ Built-in CI/CD

⚡ Option 2: Vercel

# Install Vercel CLI
npm install -g vercel

# Deploy
vercel --prod

Features:

✅ Edge network
✅ Instant deployments
✅ Automatic previews
✅ Analytics included

🐙 Option 3: GitHub Pages

# Push to GitHub
git add .
git commit -m "Deploy to GitHub Pages"
git push origin main

# Enable in Settings → Pages → Source: main branch

Note: Update URLs in code for GitHub Pages subdirectory.

🐳 Option 4: Docker

# Create Dockerfile
FROM node:18-alpine
WORKDIR /app
COPY Backend/package*.json ./
RUN npm ci --production
COPY Backend .
EXPOSE 5000
CMD ["node", "server.js"]

# Build and run
docker build -t studyflow .
docker run -p 5000:5000 -p 80:80 studyflow

🧪 Testing & Quality Assurance

Performance Testing

# Lighthouse CI
npm install -g @lhci/cli
lhci autorun --collect.url=http://localhost:8000

# Or use Chrome DevTools
# F12 → Lighthouse → Run audit

Testing Tools

Performance: PageSpeed Insights
PWA: PWABuilder
SEO: Google Rich Results Test
Mobile: Mobile-Friendly Test
Security: Security Headers

Browser Compatibility

✅ Chrome/Edge (Chromium) 90+
✅ Firefox 88+
✅ Safari 14+
✅ Samsung Internet 14+
✅ Opera 76+

Device Testing

✅ Desktop (1920x1080, 1366x768)
✅ Tablet (iPad, Android tablets)
✅ Mobile (iPhone, Android phones)
✅ Large screens (2K, 4K displays)

Get a free API key from Google AI Studio
Add GEMINI_API_KEY to your Backend .env
The app uses unlimited models by default (gemini-2.0-flash-exp) to avoid rate limits
Fallback system: Automatically tries multiple models if one fails
No rate limits on experimental models! 🚀


## 📁 Project Structure

```text
Study Flow/
├── Backend/
│   ├── config/            # Database & app configuration
│   ├── controllers/       # Business logic handlers
│   ├── middleware/        # Auth & custom middlewares
│   ├── models/            # Mongoose schemas (User, Task, Session, Streak, etc.)
│   ├── routes/            # API routes (auth, tasks, analytics, streak, AI)
│   ├── utils/             # Helper functions & email services
│   ├── node_modules/
│   ├── .env               # Environment variables (SECRET!)
│   ├── package.json
│   ├── package-lock.json
│   ├── server.js          # Express server entry point
│   └── check-deployment.js
│
├── Assets/
│   ├── icons/             # App icons & PWA assets
│   ├── chart.umd.min.js   # Chart.js library
│   ├── critical.css       # Inlined critical CSS
│   ├── lazy-load.js       # Lazy loading utility
│   ├── script.js          # Main Vue 3 app (4800+ lines)
│   ├── streak.js          # Streak tracker module
│   ├── style.css          # Global styles & themes
│   └── translations.js    # i18n translations
│
├── Documentation/
│   ├── DOCUMENTATION.md       # Full project documentation
│   ├── STREAK_TRACKER.md      # Streak system API & features
│   ├── REPORT_SYSTEMS.md      # Email reporting system
│   ├── EMAIL_REPORT_SYSTEM.md # Brevo integration guide
│   └── SECURITY.md            # Security best practices
│
├── .gitignore
├── .github/               # GitHub Actions & templates
├── CNAME                  # Custom domain config
├── index.html             # Main frontend entry (3200+ lines)
├── manifest.json          # PWA manifest
├── sw.js                  # Service Worker v5
├── sitemap.xml            # SEO sitemap
├── robots.txt             # Crawler rules
├── render.yaml            # Render.com deployment config
├── readme.md              # This file
└── LICENSE                # MIT License

**Note:** The Assets/app/ folder has been removed during codebase cleanup. All modular Vue components were consolidated into Assets/script.js for better performance.

🔥 What's New in v2.0

🎯 Streak Tracker System (Latest Addition!)

Track your daily study consistency and build powerful habits:

📈 Daily Streak Counter: Visual streak widget showing current & longest streaks
🏆 Milestone Achievements: Unlock badges at 7, 14, 30, 60, 100 & 365 day milestones
👥 Global Leaderboard: Compete with top 10 streakers worldwide
📊 History Tracking: View 30-day study history with completion status
⚡ Auto-Update: Streaks automatically update after completing focus sessions
💾 MongoDB Integration: Full backend model with REST API endpoints

📖 See: STREAK_TRACKER.md for complete API documentation

📧 Email Progress Reports

Automated weekly/monthly reports delivered to your inbox:

📄 Multi-Page PDF Format: Professional HTML-to-PDF conversion
📊 Comprehensive Analytics: Sessions, subjects, tasks & achievements
🎨 Beautiful Design: Styled with gradients & charts
🔄 Auto-Generation: Scheduled reports via Brevo API
📎 Export Feature: Download reports anytime from dashboard

📖 See: REPORT_SYSTEMS.md for dual report system architecture

🐛 Major Bug Fixes

✅ Analytics Charts Fixed: updateCharts() guard now properly has a return statement — prevents concurrent render conflicts
✅ Achievement 500 Error Fixed: Added missing quiz-perfects, quiz-completed, quiz-high-scores types to Achievement model schema enum
✅ API Request Smarter Retry: Port fallback now only triggers on network failures (TypeError/ERR_CONNECTION_REFUSED), not on HTTP errors (401/500)
✅ Canvas Always Visible: Charts now render even with zero sessions — shows empty axes instead of hiding the canvas
✅ Achievement Level Safe Access: Fixed potential crash when achievement.level is undefined
✅ Main Content Scroll Restored: Fixed flex/height layout constraints so authenticated pages scroll correctly on both small and large screens

🤖 AI System v2.0

⚡ Unlimited AI Models: Now using gemini-2.0-flash-exp (no rate limits!)
🔄 Smart Fallback: Auto-tries 9+ models including Gemma 2 series
📊 Model Tracking: Response includes which model answered
🎯 Context-Aware: AI knows your subjects, tasks, goals, and study history
🔧 Health Endpoint: /api/ai/health shows model status

🎨 UX Improvements

🖱️ Enhanced Custom Cursor: Works on 17+ interactive element types
📱 Mobile Optimized: Stats cards now 3-column horizontal on all screen sizes
🎭 Glassmorphism: Beautiful cursor with hover effects (desktop only)
📰 Blog System: Default posts with images + modal reader
🔐 Admin Panel: Full dashboard with analytics and user management

🛡️ Security & Performance

🔒 Sensitive debug logs removed
📝 .env.example template added
⚡ Compression middleware enabled
🛡️ Helmet.js security headers
🚦 Rate limiting configured

🚀 What's Coming in v2.5

Full-Stack Implementation — All features include complete Frontend + Backend architecture:

📝 Advanced Note-Taking System

Frontend Implementation:

✍️ Rich Text Editor: Markdown support with live preview (Vue component)
🎨 Syntax Highlighting: Code blocks with Prism.js integration
💾 Auto-Save: Debounced save with local storage backup
🔍 Search & Tags: Tag management UI with autocomplete
📎 Attachments: Drag-drop file upload with preview

Backend Implementation:

📄 Notes API: RESTful endpoints (/api/notes)
💾 MongoDB Schema: Note model with versioning
🔍 Search Engine: Full-text search with indexing
📎 File Storage: Cloudinary/S3 integration
🔐 Access Control: User-based permissions

👥 Social & Collaborative Features

Frontend Implementation:

🤝 Study Groups UI: Room creation/management interface
💬 Real-Time Chat: Socket.IO-powered messaging
⏱️ Group Pomodoro: Synchronized timer with visual sync
🏆 Leaderboard: Real-time ranking updates
📊 Analytics Dashboard: Shared progress visualization

Backend Implementation:

🏠 Room Management API: CRUD operations for groups
🔌 WebSocket Server: Socket.IO for real-time events
⏱️ Timer Coordinator: Broadcast timer state to all members
🏆 Challenge System: Achievement tracking per group
📊 Group Analytics: Aggregated stats calculation

📴 Enhanced Offline Mode

Frontend Implementation:

🔌 Service Worker v6: Advanced caching strategies
💾 IndexedDB: Local data persistence
🔄 Sync Queue: Background sync when online
📱 PWA Manifest: Enhanced installability
⚡ Optimistic Updates: Instant UI feedback

Backend Implementation:

🔄 Sync API: Conflict resolution endpoints
📦 Data Reconciliation: Merge strategies for conflicts
⏱️ Timestamp Tracking: Last-modified headers
🔐 Auth Tokens: Offline-compatible JWT
📊 Delta Sync: Send only changed data

📊 Advanced Statistics & Export

Frontend Implementation:

📑 Export UI: Multi-format selection interface
📊 Chart Builder: Custom visualization creator
📅 Date Picker: Advanced range selection
⚡ Progress Indicators: Real-time export status
💾 Download Manager: Handle large files

Backend Implementation:

📄 Report Generator: PDF/Excel/CSV creation
📊 Data Aggregation: Complex analytics queries
🎨 Template Engine: Customizable report layouts
📦 File Compression: Optimize download size
📧 Email Delivery: Send reports via Brevo API

🛠️ Technical Stack for v2.5

Frontend:
├── Vue 3 Composition API (existing)
├── Socket.IO Client (real-time)
├── IndexedDB API (offline storage)
├── jsPDF + SheetJS (exports)
├── Prism.js (syntax highlighting)
└── TinyMCE/Quill (rich text editor)

Backend:
├── Express.js (existing)
├── Socket.IO Server (WebSocket)
├── MongoDB + Mongoose (existing)
├── Node-cron (scheduled tasks)
├── ExcelJS + PDFKit (exports)
└── Redis (caching + pub/sub)

🎯 Expected Release: Q2 2026 • 👨‍💻 Contributions Welcome!

🧪 Quick Test Checklist

Login → Navigate Timer/Analytics → No horizontal scroll on mobile.
Open Blog → Default posts visible → Click to read modal opens.
Toggle AI widget → Ask a question → Typing indicator and responses flow.
Admin Panel opens when isAdmin is true; charts render.

⚙️ Environment & Running

Backend: Express on port 5000 (from .env).
Frontend: Open index.html via VS Code Live Server or serve from backend.
AI: GEMINI_API_KEY in Backend .env.

If you change ports, update API_BASE_URL in Assets/script.js accordingly.

🎮 Usage Guide

This section explains how to use StudyFlow effectively from the first login to productivity analysis.

🚀 First-Time Setup

Create an Account - Register with email, username, and password
Verify Email - Check your inbox for verification (if enabled)
Complete Profile - Add your name and preferences
Add Subjects - Create subjects you want to focus on
Set Goals - Define your study targets and deadlines

⏱️ Focus Sessions (Pomodoro Timer)

Starting a Session

Navigate to Focus Timer
Select mode:
- Focus (25 minutes) - Deep work session
- Short Break (5 minutes) - Quick rest
- Long Break (15 minutes) - Extended rest
- Custom - Set your own duration
Choose a Subject (optional)
Select a Task to work on (optional)
Click Start and begin focusing!

Timer Features

🎯 Visual circular progress indicator
🔔 Customizable alarm sounds
⏸️ Pause and resume functionality
🔄 Auto-start next session
📊 Session history tracking
🎨 Color-coded timer modes

📝 Task Management

Creating Tasks

1. Go to "Daily Tasks" section
2. Click "+ Add Task" button
3. Enter task title
4. Set deadline (optional)
5. Choose priority: Low, Medium, High
6. Click "Add"

Task Features

✅ Mark as complete
📅 Deadline tracking with visual indicators
🎨 Priority-based color coding
✏️ Edit task details
🗑️ Delete completed tasks
📊 Task completion statistics

🎯 Goal Tracking

Setting Goals

Title: "Study 50 Hours This Month"
Type: Study Time / Task Completion / Custom
Target: 50 hours
Deadline: End of month
Priority: High
Category: Monthly Target

Goal Types

Study Time Goals - Track total hours
Task Completion Goals - Complete X tasks
Subject-Specific Goals - Focus on one subject
Streak Goals - Maintain daily consistency
Custom Goals - Define your own metrics

Progress Tracking

📊 Real-time progress bars
📈 Completion percentage
⏱️ Time remaining
🎯 Milestone notifications
🏆 Achievement unlocks

� Study Streak Tracker

What is a Study Streak?

A study streak measures your consistency by tracking consecutive days you complete at least one focus session. Building streaks creates powerful study habits!

Streak Widget (Dashboard)

Current Streak: Days in a row you've studied
Longest Streak: Your personal best record
Today's Status: Whether you've studied today
Streak History: Last 30 days visual timeline

Maintaining Your Streak

✅ Complete at least one focus session daily
🕐 Must complete session before midnight
📊 Any session duration counts (even 5 minutes!)
🔄 Streak auto-updates after each completed session

Streak Milestones

Unlock special achievements and badges:

🔥 7 Days - Week Warrior (75 points)
🔥 14 Days - Fortnight Focus (150 points)
🔥 30 Days - Month Master (300 points)
🔥 60 Days - Persistence Pro (600 points)
🔥 100 Days - Centurion (1000 points)
🔥 365 Days - Year Legend (3650 points)

Global Leaderboard

🏆 View top 10 global streakers
📊 See current & longest streaks
🎯 Compete with other students
💪 Stay motivated by community progress

Streak Recovery

❌ Broken Streak: If you miss a day, streak resets to 0
🔄 No Rollback: Current design has no grace period
🎯 Pro Tip: Set daily reminders to maintain streaks
💡 Stay Consistent: Even 10 minutes counts!

📖 Full API Documentation: See STREAK_TRACKER.md

📊 Analytics Dashboard

Available Insights

Total Study Time - All-time and period-specific
Daily/Weekly/Monthly Trends - Visual charts
Subject Breakdown - Time per subject
Productivity Score - Performance metrics
Today's Progress - Real-time metrics (NEW!) 🔥
- Minutes studied today
- Sessions completed
- Tasks finished
- Current streak count
Streak Tracking - Consecutive study days
Comparison Charts - Period over period
Focus Quality - Session effectiveness

Chart Types

📊 Bar charts for time comparison
📈 Line graphs for trends
🥧 Pie charts for distribution
📅 Calendar heatmap for consistency
🎯 Gauge charts for goals

🤖 AI Study Assistant

Features

Smart Recommendations - Personalized study tips
Quiz Generation - Auto-create quizzes from topics
Study Planning - AI-powered schedule suggestions
Progress Analysis - Identify improvement areas
Motivation Coach - Encouraging messages

Using AI Assistant

1. Click floating AI button (bottom-right)
2. Type your question or request
3. Get instant AI-powered responses
4. Context-aware suggestions based on your data

AI Models Available

Gemini 2.0 Flash (Unlimited)
Gemini Experimental (Unlimited)
Gemma 2 (9B/27B variants)
Smart fallback system

🎵 Focus Music Player

Supported Sources

🎥 YouTube videos (paste URL)
🎵 Local audio files
📻 Background playlists
🎧 Curated study mixes

Player Controls

▶️ Play/Pause
⏭️ Next track
🔁 Loop mode
🔀 Shuffle
🔊 Volume control
📱 Minimized player view

🏆 Achievement System

How It Works

Achievements unlock automatically as you progress
Earn points for various milestones
Collect badges to show your dedication
Compete with yourself over time
Share achievements on social media

Achievement Categories

📚 Study Time - Hour milestones
🔥 Consistency - Daily streaks
🎯 Goals - Goal completions
📝 Tasks - Task milestones
📖 Subjects - Subject diversity

🎨 Customization

Themes

🌑 Dark themes (multiple variants)
☀️ Light themes
🌈 Custom color schemes
🎨 Personalized palettes

Settings

🔔 Notification preferences
⏱️ Default timer durations
🔊 Sound settings
📱 PWA installation
🔐 Privacy controls

📱 Mobile Experience

PWA Installation

Chrome:
1. Click menu (⋮)
2. Select "Install app"
3. Follow prompts

iOS Safari:
1. Tap Share button
2. Select "Add to Home Screen"
3. Confirm installation

Mobile Features

📱 Full offline support
🔔 Push notifications
📲 Native-like experience
🎨 Adaptive UI
⚡ Fast loading

🔐 Account Management

Profile Settings

✏️ Update name and username
📧 Change email
🔑 Change password
🖼️ Upload profile picture
🗑️ Delete account

Data Management

💾 Export all data (JSON/CSV)
📊 View data statistics
🔄 Sync across devices
🗑️ Clear local cache
📦 Backup and restore

🔄 Daily Workflow Example

Morning Routine

1. Check daily tasks
2. Set 3 priority tasks
3. Start 25-min focus session
4. Track progress

Study Session

1. Choose subject
2. Start Pomodoro timer
3. Work distraction-free
4. Take break when done
5. Log session automatically

Evening Review

1. Check analytics
2. Mark tasks complete
3. Review progress
4. Plan tomorrow
5. Celebrate achievements

🏗️ Application Architecture

Frontend Architecture

index.html (Main SPA)
├── Vue 3 Composition API
├── Tailwind CSS (Utility-first)
├── Socket.IO Client (Real-time)
├── Chart.js (Analytics)
├── FullCalendar (Schedule)
└── Service Worker (Offline)

Backend Architecture

Express.js Server
├── Routes (API Endpoints)
├── Controllers (Business Logic)
├── Models (MongoDB Schemas)
├── Middleware (Auth, Admin)
├── Utils (Email, Helpers)
└── Config (Database, Env)

Data Flow

User → Frontend → API → Controller → Model → MongoDB
                ↓
         Socket.IO (Real-time updates)
                ↓
         Service Worker (Caching)

Security Layers

1. JWT Authentication (Token-based)
2. Bcrypt Password Hashing (10 rounds)
3. CORS Protection (Origin validation)
4. Rate Limiting (API throttling)
5. Input Validation (Sanitization)
6. HTTPS Enforcement (TLS 1.3)
7. Security Headers (CSP, XSS)

📁 Detailed File Structure

Study Flow/
├── index.html                      # Main application
├── login.html                      # Authentication page
├── manifest.json                   # PWA configuration
├── sw.js                          # Service Worker v5
├── robots.txt                     # SEO crawling rules
├── sitemap.xml                    # Search engine sitemap
├── _redirects                     # SPA routing rules
├── _headers                       # Security headers
│
├── Assets/                        # Frontend resources
│   ├── script.js                  # Main Vue app (2900+ lines)
│   ├── style.css                  # Global styles (800+ lines)
│   ├── auth.js                    # Authentication logic
│   ├── auth.css                   # Auth page styles
│   ├── critical.css               # Inline critical CSS
│   ├── lazy-load.js               # Performance utilities
│   └── brain-duotone.png          # App icon
│
├── Backend/                       # Server application
│   ├── server.js                  # Express server entry
│   ├── package.json               # Dependencies
│   │
│   ├── config/
│   │   └── db.js                  # MongoDB connection
│   │
│   ├── middleware/
│   │   ├── auth.middleware.js     # JWT verification
│   │   └── admin.middleware.js    # Admin check
│   │
│   ├── models/
│   │   ├── User.js                # User schema
│   │   ├── Session.js             # Study session schema
│   │   ├── Task.js                # Task schema
│   │   ├── Subject.js             # Subject schema
│   │   ├── Goal.js                # Goal schema
│   │   ├── Achievement.js         # Achievement schema
│   │   ├── Blog.js                # Blog post schema
│   │   ├── Song.js                # Music schema
│   │   └── Quiz.js                # Quiz schema
│   │
│   ├── controllers/
│   │   └── auth.controller.js     # Auth logic
│   │
│   ├── routes/
│   │   ├── auth.routes.js         # Authentication
│   │   ├── user.routes.js         # User management
│   │   ├── session.routes.js      # Study sessions
│   │   ├── task.routes.js         # Task CRUD
│   │   ├── subject.routes.js      # Subject management
│   │   ├── goal.routes.js         # Goal tracking
│   │   ├── achievement.routes.js  # Achievements
│   │   ├── analytics.routes.js    # Analytics data
│   │   ├── ai.routes.js           # AI assistant
│   │   ├── blog.routes.js         # Blog system
│   │   ├── song.routes.js         # Music library
│   │   └── admin.routes.js        # Admin panel
│   │
│   └── utils/
│       └── sendEmail.js           # Email service
│
└── Documentation/                 # Project docs
    ├── PERFORMANCE_REPORT.md      # Optimization details
    ├── DEPLOYMENT_OPTIMIZED.md    # Deploy guide
    ├── OPTIMIZATION_SUMMARY.md    # Quick reference
    ├── ADMIN_COMMANDS.md          # Admin commands
    ├── ADMIN_PANEL_SETUP.md       # Admin setup
    ├── CHANGELOG.md               # Version history
    └── readme.md                  # This file

🎮 Usage Guide

This section explains how to use StudyFlow effectively from the first login to productivity analysis.

🚀 First-Time Setup

Create an account or log in securely
Set your study preferences
Add subjects you want to focus on

📝 Task & Subject Management

Create subjects (e.g., Math, Programming, Design)
Add tasks under each subject
Define goals to track your progress
Organize your workflow for focused sessions

⏱️ Focus Sessions (Pomodoro)

Choose a focus duration (default: 25 minutes)
Select a subject and optional task
Start the Pomodoro timer
Take short or long breaks when prompted

🎵 Music & Focus Environment

Paste YouTube links for background focus music
Upload and play local audio files
Control volume and playback without interrupting sessions
Create a distraction-free study atmosphere

📊 Productivity Analytics

Track total focus time per day, week, and month
View visual charts to analyze productivity trends
Identify your most productive subjects
Improve consistency using data-driven insights

🔁 Daily Workflow Tip

Plan tasks → Start focus session → Take breaks → Review analytics → Improve tomorrow

StudyFlow is designed to help you build long-term study habits, not just short sessions.

👥 Team

💻 Development Team

Lead Developer & Designer
_{Full Stack Development | UI/UX Design | System Architecture}

Project Administrator
_{Project Management | Content Strategy | Quality Assurance}

_{📊 Ensuring project excellence & user experience}

Built for students, by students • University Project 2026

👨‍💻 About the Developer

Salah Uddin Kader
Full Stack Developer | UI/UX Designer | Tech Enthusiast

Passionate about building scalable web applications and clean user experiences.
StudyFlow reflects my journey in mastering modern full-stack development.

🚀 Always learning • Always building • Always improving

🤝 Contributing

Contributions are highly appreciated and help make StudyFlow better for everyone.

How to Contribute

🍴 Fork the repository

🌱 Create a feature branch

git checkout -b feature/your-feature-name

✅ Commit your changes

git commit -m "Add: meaningful feature description"

🚀 Push and open a Pull Request

git push origin feature/your-feature-name

Contribution Guidelines

Follow the existing code style
Write meaningful commit messages
Test your changes before submitting
Update documentation when needed

📄 License

This project is licensed under the MIT License - one of the most permissive and widely-used open-source licenses.

✅ What You CAN Do

🎯 Commercial Use

✅ Use in commercial products
✅ Sell modified versions
✅ Use in proprietary software
✅ Monetize your fork

🔧 Modification

✅ Edit source code freely
✅ Create derivative works
✅ Customize for your needs
✅ Port to other platforms

📤 Distribution

✅ Share publicly or privately
✅ Include in packages/bundles
✅ Redistribute modified versions
✅ Use as template for projects

🎓 Educational Use

✅ Use for learning purposes
✅ Include in tutorials/courses
✅ Reference in academic work
✅ Teach with real-world code

⚠️ Requirements (Simple!)

📋 You Must:

Include the original MIT license in any copy of the software
Include the copyright notice (see LICENSE file)
That's it! No other restrictions.

🚫 You're NOT Required To:

❌ Share your modifications (but we'd love it if you do!)
❌ Open source your derivative work
❌ Credit us in your UI (but appreciated!)
❌ Notify us of usage

🛡️ Limitation of Liability

The software is provided "AS IS", without warranty of any kind. The authors are not liable for any damages or issues arising from its use.

🤝 Recommended (But Optional)

While not required, we encourage you to:

⭐ Star this repo if you find it useful
🔗 Link back to this project in your README
💬 Share improvements via pull requests
📢 Mention StudyFlow in your project credits

❓ FAQ & Troubleshooting

General Questions

Q: Is StudyFlow free?
A: Yes! Completely free and open-source under MIT License.

Q: Can I use it offline?
A: Yes! Install as PWA for offline access.

Q: Is my data secure?
A: Yes. Bcrypt encryption + JWT tokens + MongoDB security.

Q: Token expiry time?
A: 30 days - then you need to re-login.

Common Issues

Scroll button not showing?
✅ Scroll past 100px - it appears with bounce animation

Page content not scrolling (only nav visible)?
✅ Hard refresh (Ctrl+F5) after pulling latest changes; main layout scroll container is now fixed for desktop + mobile

Service Worker not updating?
✅ DevTools → Application → Unregister SW → Hard reload

PWA not installing?
✅ Use HTTPS (or localhost) + Check manifest.json

AI not responding?
✅ Verify GEMINI_API_KEY in backend .env

📊 Performance Stats

Lighthouse Score:     94/100 ⚡
First Paint:          1.2s
Time to Interactive:  3.2s
Bundle Size:          198 KB (first load)
Cached Load:          < 10 KB
Service Worker:       v5 (Active)
Chart Load Time:      < 100ms (optimized)
Scroll Performance:   100px threshold

🚀 Recent Performance Optimizations

✅ Faster Chart Loading: Reduced from 500ms to 100ms initial load
✅ Smart Scroll Detection: Container-specific scroll listener added
✅ Optimized Analytics: Charts render with retry mechanism (100ms/800ms/1500ms)
✅ Improved Scroll Buttons: Now visible at 100px (was 300px)
✅ Better Memory Management: Proper cleanup of event listeners

🎯 Roadmap

✅ Completed (v2.0)

🚧 In Progress (v2.5) — Full-Stack Development

All features include Frontend UI + Backend API + Database models

📝 Advanced Note-Taking - Markdown editor with syntax highlighting & auto-save
Vue UI + Express API + MongoDB + File Storage
👥 Social Study Groups - Create rooms, invite friends, study together in real-time
Socket.IO Client + WebSocket Server + Room Management API
🤝 Collaborative Study Rooms - Share sessions, compete on leaderboards, group challenges
Real-time UI + Broadcasting System + Group Analytics API
⏱️ Pomodoro Group Sessions - Synchronized timers for study groups
Sync Timer Component + Timer Coordination API + State Broadcasting
📴 Enhanced Offline Mode - Full functionality without internet connection
Service Worker v6 + IndexedDB + Sync Queue API + Conflict Resolution
📊 Advanced Statistics Export - Generate detailed reports (PDF/Excel/CSV)
Export UI + jsPDF/SheetJS + Report Generation API + Email Delivery

📋 Planned Features (v3.0)

💡 Have a feature request? Create an issue and let us know!

📚 Documentation

Comprehensive guides and references available:

📚 Documentation

DOCUMENTATION.md - Complete project documentation (2200+ lines)
readme.md - Quick start guide (this file)

🔥 Feature-Specific Guides

STREAK_TRACKER.md - Daily streak system API & implementation
REPORT_SYSTEMS.md - Dual report system (client + server)
EMAIL_REPORT_SYSTEM.md - Brevo email integration

🛡️ Security & Best Practices

SECURITY.md - Security guidelines & vulnerability reporting
SECURITY_ALERT.md - Active security notices

🏗️ Architecture & Deployment

render.yaml - Render.com deployment configuration
.github/ - GitHub Actions & issue templates

📞 Support & Resources

🆘 Get Help

🔗 Quick Links

⭐ Thank you for exploring StudyFlow
Happy Learning • Happy Building • Keep Growing

Name		Name	Last commit message	Last commit date
Latest commit History 113 Commits
.github		.github
Assets		Assets
Backend		Backend
.gitignore		.gitignore
CNAME		CNAME
DOCUMENTATION.md		DOCUMENTATION.md
EMAIL_REPORT_SYSTEM.md		EMAIL_REPORT_SYSTEM.md
LICENSE		LICENSE
REPORT_SYSTEMS.md		REPORT_SYSTEMS.md
SECURITY.md		SECURITY.md
SECURITY_ALERT.md		SECURITY_ALERT.md
STREAK_TRACKER.md		STREAK_TRACKER.md
_headers		_headers
_redirects		_redirects
app.html		app.html
index.html		index.html
manifest.json		manifest.json
package-lock.json		package-lock.json
package.json		package.json
readme.md		readme.md
render.yaml		render.yaml
report-template.html		report-template.html
requirements.txt		requirements.txt
robots.txt		robots.txt
sitemap.xml		sitemap.xml
sw.js		sw.js

Folders and files

Latest commit

History

Repository files navigation

🚀 StudyFlow — Intelligent Productivity Ecosystem

⚡ Quick Start

✨ Key Features

🎯 Core Productivity Features

🔐 Security & Authentication

⚡ Performance & Technology

🎨 User Experience

🔍 SEO & Discovery

🚀 Coming Soon (v2.5) — Full Stack Features

🏆 Achievement System

📚 Study Time Achievements

🔥 Streak & Consistency Achievements

🎯 Goal & Task Achievements

🧠 Quiz Performance Achievements

🛠️ Technology Stack

🖥️ Frontend

⚙️ Backend

🗄️ Database

� Performance & Optimization

⚡ Lightning-Fast Load Times

Core Web Vitals (Target Metrics)

🎯 Lighthouse Scores (Target)

🛠️ Optimization Techniques Applied

1. Critical Rendering Path

2. Smart Caching Strategy

3. Resource Optimization

4. SEO Enhancements

5. Security Headers

�📋 Prerequisites

🚀 Installation & Setup

1️⃣ Clone the Repository

2️⃣ Install Dependencies

3️⃣ Environment Configuration

4️⃣ Start the Backend Server

5️⃣ Run the Frontend

🚀 Deployment Guide

🌐 Option 1: Netlify (Recommended)

⚡ Option 2: Vercel

🐙 Option 3: GitHub Pages

🐳 Option 4: Docker

🧪 Testing & Quality Assurance

Performance Testing

Testing Tools

Browser Compatibility

Device Testing

🔥 What's New in v2.0

🎯 Streak Tracker System (Latest Addition!)

📧 Email Progress Reports

🐛 Major Bug Fixes

🤖 AI System v2.0

🎨 UX Improvements

🛡️ Security & Performance

🚀 What's Coming in v2.5

📝 Advanced Note-Taking System

👥 Social & Collaborative Features

📴 Enhanced Offline Mode

📊 Advanced Statistics & Export

🛠️ Technical Stack for v2.5

🧪 Quick Test Checklist

⚙️ Environment & Running

🎮 Usage Guide

🚀 First-Time Setup

⏱️ Focus Sessions (Pomodoro Timer)

Starting a Session

Timer Features

📝 Task Management

Creating Tasks

Task Features

🎯 Goal Tracking

Setting Goals

Goal Types

Progress Tracking

� Study Streak Tracker

What is a Study Streak?

Streak Widget (Dashboard)

Maintaining Your Streak