Skip to content

README.md

Latest commit

 

History

History
368 lines (286 loc) · 12.1 KB

README.md

File metadata and controls

368 lines (286 loc) · 12.1 KB

Typing SVG


   

🧠 What Problem Does This Solve?

❌ Before FocusForge

  • Students plan randomly with no priority logic
  • Hard subjects get equal time as easy ones
  • No tracking → no accountability
  • Phone distractions silently kill study sessions
  • Exam panic from poor time management

✅ After FocusForge

  • AI generates a priority-weighted timetable
  • Difficult subjects automatically get more time
  • Real-time progress tracking with visual charts
  • AI detects phone usage and alerts you instantly
  • Calm, structured, deadline-aware scheduling

💡 Core Insight: Students don't fail from lack of knowledge — they fail from poor planning and constant distractions. FocusForge solves both.

🖼️ Screenshots

🏠 Dashboard — Add Subjects & Track Progress

Dashboard

🔴 Deep Focus Mode — AI Phone Detection Live

Deep.Focus.Mode.mp4

📅 Generated Timetable — Priority-Weighted Sessions

Generated Timetable

✨ Features

📅 Smart Scheduling Engine

Generates a full study timetable based on subject difficulty, exam dates, and your available hours. Every session includes a specific time slot, study approach, and step-by-step actions.

🔴 Deep Focus Mode (Most Unique Feature)

A dedicated focus page powered by TensorFlow.js + COCO-SSD. The AI watches through your webcam and detects phone usage in real time. Get caught → instant alert. A distraction counter tracks every lapse.

⚡ Priority-Weighted Algorithm

Not all subjects deserve equal time. The engine computes a priority_score per subject and allocates sessions accordingly — urgent + difficult subjects always come first.

📊 Progress Dashboard

Visual doughnut chart with per-subject completion bars. See your overall progress percentage, completed sessions, and remaining workload at a glance.

🔔 Smart Study Reminders

Browser push notifications scheduled to fire at 30 min, 10 min, 5 min, and the exact moment your session starts — so you never miss a slot.

🧠 Study Strategy Engine

Detects whether a subject is Coding, Mathematics, or Theory and generates a tailored learning approach — not just hours allocated, but how to use them effectively.

⚡ Core Algorithm

The heart of FocusForge is its priority-weighted scheduling engine:

priority_score = difficulty_weight × time_sensitivity_factor

📊 Difficulty Weights

Level Weight Effect
🟢 Easy 1.0× Fewer, lighter sessions
🟡 Medium 2.0× Balanced allocation
🔴 Hard 3.5× More, intensive sessions

⏳ Time Sensitivity

Days to Exam Multiplier Label
≤ 3 days 1.5× 🚨 Critical
≤ 7 days 1.2× 🔥 High
> 7 days 1.0× 📅 Normal

Result: A Hard subject with 3 days left gets 3.5 × 1.5 = 5.25× the weight of an Easy subject with plenty of time — automatically pushed to earlier, longer, higher-priority sessions.

🛠️ Tech Stack


Python 3.11
Django 6.0
JavaScript
HTML5
CSS3
SQLite
TensorFlow.js

🏗️ System Architecture

┌─────────────────────────────────────────────┐
│           Browser  (HTML / CSS / JS)        │
│    Chart.js  ·  TensorFlow.js  ·  Fetch API │
└────────────────────┬────────────────────────┘
                     │  REST API calls
┌────────────────────▼────────────────────────┐
│          Django REST Framework              │
│   Authentication  ·  Serializers  ·  Views  │
└────────────────────┬────────────────────────┘
                     │
┌────────────────────▼────────────────────────┐
│              Service Layer                  │
│   services.py  —  Scheduling Algorithm      │
│   Priority score  ·  Time allocation        │
└────────────────────┬────────────────────────┘
                     │
┌────────────────────▼────────────────────────┐
│             SQLite Database                 │
│         Subject  ·  StudySession            │
└─────────────────────────────────────────────┘

Clean separation of concerns — the frontend is fully decoupled from the backend via REST API. Any layer can be swapped independently.

📡 API Reference

Method Endpoint Description
GET /api/subjects/ List all subjects
POST /api/subjects/ Create a subject
PUT /api/subjects/<id>/ Update subject details
DELETE /api/subjects/<id>/ Delete a subject
POST /api/generate/ Generate full timetable
GET /api/sessions/ Get all study sessions
PATCH /api/sessions/<id>/complete/ Mark session complete
GET /api/progress/ Overall progress stats
GET /api/timetable/export_pdf/ Export plan as PDF

🗃️ Data Model

User
 └── Subject
      ├── name
      ├── exam_date
      ├── difficulty              (1=Easy · 2=Medium · 3=Hard)
      ├── selected_topics         (JSON array)
      ├── study_start_time
      └── study_end_time
           │
           ▼
      StudySession
        ├── date
        ├── start_time / end_time
        ├── hours_allocated
        ├── priority_label        (Critical · High · Medium · Low)
        ├── approach
        ├── technique
        ├── steps                 (JSON array)
        └── completed             (Boolean)

⚙️ Quick Start

# 1. Clone the repository
git clone https://github.com/yashtaksale/focusforge.git
cd focusforge/studyplanner

# 2. Create and activate virtual environment
python -m venv venv
source venv/bin/activate        # Mac / Linux
venv\Scripts\activate           # Windows

# 3. Install dependencies
pip install -r requirements.txt

# 4. Environment setup
echo "SECRET_KEY=your-secret-key-here" > .env
echo "DEBUG=True" >> .env

# 5. Run migrations and start server
python manage.py migrate
python manage.py runserver

Open http://localhost:8000 — register an account and generate your first plan in under a minute.

📁 Project Structure

focusforge/
├── manage.py
├── requirements.txt
├── .env
│
├── planner/                    ← main application
│   ├── models.py               ← Subject, StudySession models
│   ├── serializers.py          ← DRF serializers
│   ├── views.py                ← API endpoints
│   ├── services.py             ← 🧠 scheduling algorithm
│   ├── urls.py
│   └── tests.py
│
├── studyplanner/               ← project configuration
│   ├── settings.py
│   └── urls.py
│
├── templates/
│   ├── index.html              ← main dashboard
│   ├── focus.html              ← deep focus mode
│   └── login.html
│
└── static/
    ├── css/style.css
    └── js/script.js

🗺️ Roadmap

Status Feature
✅ Shipped Priority-weighted timetable generation
✅ Shipped Deep Focus Mode with AI phone detection
✅ Shipped Progress dashboard with Chart.js
✅ Shipped Smart browser push notifications
✅ Shipped PDF timetable export
✅ Shipped Topic-based session scheduling
🔄 Planned Mobile app (React Native)
🔄 Planned Cloud deployment (Render / AWS)
🔄 Planned AI-powered topic recommendations
🔄 Planned Predicted exam readiness score
🔄 Planned Collaborative study rooms

👨‍💻 Author

Yash Taksale
Computer Science Engineering

 

⭐ If FocusForge impressed you, drop a star — it takes 2 seconds and means everything.


"Discipline beats motivation. Motivation is fleeting. Systems are permanent."