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

• ⏱️ Smart Pomodoro Timer
  Fully customizable focus & break sessions

• 📊 Deep Analytics Dashboard
  Daily, weekly & monthly productivity insights

• 🎵 Integrated Music Player
  YouTube links & local audio support

• 📝 Workflow Manager
  Tasks, subjects & goal tracking

• 🔐 Secure Authentication
  JWT + Bcrypt encryption

• ⚡ Real-time Sync
  Live updates via Socket.IO

• 🎨 Modern UI/UX
  Responsive, dark-friendly interface

• 📱 Cross-Device Ready
  Works on desktop & mobile

• 🏆 Gamified Achievements
  Unlock rewards for study milestones

---

🏆 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

---

📋 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.

AI Setup (Gemini)

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

---

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