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.

---

✨ 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

• 🎵 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

🔐 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

---

🏆 Achievement System

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

📚 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)

🔥 Consistency Achievements

• Consistency King: Maintain a 7-day study streak (75 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)
• Subject Explorer: Create 1 subject (10 points)
• Task Manager: Complete 1 task (15 points)
• Task Champion: Complete 50 tasks (80 points)

Note: Achievements are automatically unlocked as you progress. Check your profile to see earned badges!

---

🛠️ 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:

```env
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 any static server of your choice.

---

🚀 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
│   ├── middleware/        # Auth & custom middlewares
│   ├── models/            # Mongoose schemas
│   ├── routes/            # API routes
│   ├── node_modules/
│   ├── .env               # Environment variables
│   ├── package.json
│   ├── package-lock.json
│   ├── server.js          # Express server entry point
│   └── check-deployment.js
│
├── Frontend/
│   ├── Assets/
│   │   ├── script.js      # Frontend logic
│   │   └── style.css     # UI styles
│   └── index.html        # Main frontend entry
│
├── .gitignore
├── DEPLOYMENT.md
├── readme.md
└── render.yaml

---

## 🔄 Recent Upgrades

### 🤖 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**: Full-screen menu, no overflow, touch-friendly
- 🎭 **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

---

## 🧪 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.
- 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

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

---

⏱️ Focus Sessions (Pomodoro Timer)

Starting a Session

1. Navigate to Focus Timer
2. 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
3. Choose a Subject (optional)
4. Select a Task to work on (optional)
5. 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

---

📊 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
• 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

1. Create an account or log in securely
2. Set your study preferences
3. 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.

👨‍💻 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

1. 🍴 Fork the repository
2. 🌱 Create a feature branch

   git checkout -b feature/your-feature-name
   git commit -m "Add: meaningful feature description"
   git push origin feature/your-feature-name
   
   

---

📄 License

This project is licensed under the MIT License, a permissive open-source license that allows you to:

• ✅ Use the software freely
• ✅ Modify and adapt it for your needs
• ✅ Distribute and share it
• ✅ Use it for personal or commercial projects

As long as the original copyright and license notice are included.

---

© Copyright

All rights reserved under the MIT License.

---

---

❓ 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 300px - it appears with bounce animation

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

---

🎯 Roadmap

• Mobile native apps
• Browser extensions
• Flashcard system
• Note-taking
• Calendar sync
• Social features

---

📞 Support

• 📖 Performance Report
• 🚀 Deployment Guide
• 🐛 Issue Tracker
• 📧 salauddinkaderappy@gmail.com

---

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