🚀 RoutineFlow

Daily Routine & Study Tracker for Students

A fully featured, modern, open-source productivity web app built with React + TypeScript

Created by Sudhir Kumar • @SudhirDevOps1

📋 Table of Contents

About
Who Is This For?
Features Overview
Page-by-Page Feature Details
- 🏠 Dashboard
- 📋 Routine Builder
- 📖 Study Tracking
- 🔥 Streaks & Attendance
- 📊 Smart Analytics
- 🎯 Goals System
- 📁 Routine Templates
- 🧘 Focus & Timer Mode
- 📝 Weekly Review
- 💾 Data Manager
Advanced Features
Gamification System (XP & Levels)
Smart Insights & AI Suggestions
PiP (Picture-in-Picture) Timer
Keyboard Shortcuts
JSON Data System
UI/UX Design System
Technical Architecture
Performance Optimizations
How to Use — Complete Guide
Rules & Behavior
Project Structure
Tech Stack
Getting Started
Browser Support
FAQ

📖 About

RoutineFlow is a frontend-only, open-source daily routine and study tracking web application designed specifically for students. It helps you:

📅 Plan daily routines with time blocks
📚 Track study sessions subject-wise
🔥 Maintain streaks like school attendance
🎯 Set goals and track progress
🧘 Focus with Pomodoro timer
📊 Analyze your productivity patterns
💾 Export/import all data as JSON

No backend. No login. No server. No internet required.

Everything runs in your browser. All data is stored in localStorage — your data stays on YOUR device.

👥 Who Is This For?

Target User	Why RoutineFlow
🎓 BTech / BCA / MCA Students	Track college study hours, manage subjects, maintain consistency
💻 Self-Learners & Coders	DSA practice tracking, project time logging, coding routine
📝 Exam Preparation Students	Intensive study schedules, subject-wise time tracking
🏋️ Anyone Wanting Routine	Track any daily routine with categories

✨ Features Overview

#	Feature	Description
1	🏠 Dashboard	Hero stats, daily overview, mood tracking, habit tracker
2	📋 Routine Builder	Create/edit daily routine blocks with time, category, color
3	📖 Study Tracking	Log sessions with subject, time, status, rating, notes
4	🔥 Streaks	School-style attendance, calendar heatmap, streak counter
5	📊 Smart Analytics	Charts, best focus time, subject difficulty, weekly change
6	🎯 Goals	Weekly/monthly/custom goals with progress tracking
7	📁 Templates	Pre-built routines (Student, Coding, Exam, Library)
8	🧘 Focus Timer	Normal + Pomodoro timer, Deep Focus mode, PiP floating
9	📝 Weekly Review	7-day performance review with export
10	💾 Data Manager	JSON export/import, backup, reset
11	⚡ XP & Levels	Gamification with 8 levels
12	🧠 Smart Insights	AI-like suggestions based on your patterns
13	📺 PiP Timer	Floating timer window — works outside browser
14	⌨️ Command Palette	Ctrl+K quick commands
15	🌓 Dark/Light Mode	Toggle anytime
16	↩️ Undo System	Undo deleted items
17	👤 Multiple Profiles	Study/Coding/Exam profiles
18	🔄 Habit Tracker	Track daily habits
19	⏰ Time Conflict Detection	Warns overlapping tasks
20	📱 Mobile Responsive	Works on phone, tablet, desktop

📄 Page-by-Page Feature Details

🏠 1. Dashboard

The home screen shows everything at a glance.

Hero Section (Gradient Banner)

App branding: RoutineFlow by Sudhir Kumar
Current date displayed in full format
Streak badge with fire animation (🔥)
Best streak displayed

4 Stat Cards

Card	What it shows
📅 Planned	Total planned study hours for today
✅ Completed	How many hours you've completed today
⏳ Pending	Number of tasks not yet done
💪 Score	Productivity percentage (0–100%)

XP & Level System

Shows current Level (1–8) with level name
XP progress bar towards next level
XP remaining to next level

Today's Log

Field	Description
⏰ Wake Up	Set what time you woke up today
🌙 Sleep Time	Set what time you plan to sleep
😊 Mood	Pick from 5 emojis: 😢 😐 🙂 😊 🤩

Smart Insights Panel

Shows AI-like suggestions based on your data
4 types: Warning 🚨, Suggestion 💡, Achievement 🏆, Info 🧠
Examples:
- "Your best focus time is around 7:00 PM"
- "Math completion rate is only 45%"
- "No break between DSA and OS. Add a short break!"
- "🔥 Amazing! 7 day streak!"

Today's Task List

For each task today:

Shows task name, time slot, category emoji, duration
Color bar on left matching task color
3 status buttons:
- ✅ = Completed
- ⚡ = Partial
- ❌ = Missed
Completed tasks show strikethrough

Progress Bar

Visual bar showing % of tasks done
Changes color: 🟢 Green (80%+), 🟡 Yellow (50%+), 🔴 Red (<50%)
Motivational message based on score:
- 90%+ → "🎉 Outstanding! You crushed it!"
- 70%+ → "💪 Great work! Keep pushing!"
- 40%+ → "👍 Good progress, keep going!"
- <40% → "🏃 Just getting started!"
- 0% → "⏳ Start your tasks to see progress!"

Habit Tracker

Add daily habits with emoji icons (💧🏃📚🧘💊🍎✍️🎵😴🚿)
Click to toggle done/not done for today
Shows total days completed
Green highlight when done today

📋 2. Routine Builder

Build your daily schedule block by block.

Add Task Form

Field	Type	Description
Task Name	Text	e.g., "DSA Practice"
Start Time	Time picker	When task starts
End Time	Time picker	When task ends
Category	Dropdown	Study 📚 / Coding 💻 / Exercise 💪 / Personal 🧘 / Break ☕
Color Label	Color picker	8 colors to choose from
Subject Link	Dropdown	Link to a subject (only for Study/Coding)
Notes	Text	Optional notes
Recurring	Checkbox	Repeat weekly
Days	Day buttons	Sun–Sat, select which days

Auto-Calculated

Duration is auto-calculated from start/end time
Time conflict detection — warns if new task overlaps existing ones

Task Actions

Action	Icon	Description
Deep Focus	🔲	Opens task in full-screen focus mode
Duplicate	📋	Creates a copy of the task
Edit	✏️	Opens edit form with pre-filled data
Delete	🗑️	Deletes task (with undo support)

Subject Manager (Built-in)

Add subjects with: Name, Color (12 options), Icon (15 emoji options)
View all subjects as tags
Delete subjects inline
Subject icons: 📘📗📕📙💻🔬🧮📐🧪📊🌍⚡🎨📝🏛️

Day Filter

Filter tasks by day: All / Sun / Mon / Tue / Wed / Thu / Fri / Sat

Profile Switching

Multiple profiles: Study 📚, Coding 💻, Exam 🎯
Switch between profiles to see different task sets
Create new profiles with custom name and emoji
Each profile can have different routine tasks

📖 3. Study Tracking

Log and review your study sessions.

Log New Session

Field	Description
Subject	Select from your subjects list
Date	Date picker (defaults to today)
Start Time	Session start
End Time	Session end
Status	✅ Completed / ⚡ Partial / ❌ Missed
Rating	1–5 stars (⭐⭐⭐⭐⭐)
Notes	What you studied (chapter, topic, etc.)

Session List

Filterable by date and subject
Shows: Subject icon/name, status badge, time range, duration, rating stars, notes
Total time calculated at top
Delete sessions (with undo)

Status Badge Colors

Status	Color	Badge
Completed	🟢 Green	✅ completed
Partial	🟡 Yellow	⚡ partial
Missed	🔴 Red	❌ missed

🔥 4. Streaks & Attendance

Track consistency like school attendance.

4 Stat Cards

Stat	Description
🔥 Current Streak	How many consecutive days you've been active
🏆 Longest Streak	Your all-time best streak
📊 Weekly Consistency	Percentage of active days in last 7 days
📅 Total Active Days	Total number of days with activity

Calendar Heatmap

Monthly calendar view with color-coded cells
Navigate months with ◀ ▶ arrows
Each cell shows:
- Day number
- Mood emoji (if set)

Color Legend

Color	Meaning
🟢 Green	Completed — at least one task completed
🟡 Yellow	Partial — partial tasks but no completed
🔴 Red	Missed — only missed tasks
⬜ Gray	No data recorded
🔵 Blue ring	Today's date

How Streaks Work

A day counts as "active" if you have completed tasks OR completed sessions
Streak = consecutive active days counting backwards from today (or yesterday)
If today has no data, streak counts from yesterday
Missing a single day resets the current streak
Longest streak remembers your all-time best
Weekly consistency = (active days in last 7) ÷ 7 × 100%

📊 5. Smart Analytics

Deep analysis of your study patterns.

4 Summary Cards

Stat	Description
⏱️ Total Study	All-time total study minutes
📈 Avg Daily	Average study time per active day
⏳ Avg Session	Average length of one session
⚡ Weekly Change	% improvement vs previous week

Best Focus Time Detection

Analyzes all completed sessions by hour
Tells you: "You study best around 7:00 PM"
Based on which hour has the most completed study minutes

7-Day Bar Chart

Visual bar chart showing last 7 days of study
Each bar shows:
- Day name (Mon, Tue, etc.)
- Study minutes on top
- Height proportional to study time
Gradient colored bars (indigo → purple)

Subject-wise Analysis

For each subject:

Completion rate (completed ÷ total sessions × 100%)
Total time spent
Progress bar colored with subject's color
Acts as a difficulty indicator — low completion rate = harder subject

How Weekly Change is Calculated

Weekly Change = ((This week total - Last week total) / Last week total) × 100%

Positive = improvement 📈
Negative = decline 📉

🎯 6. Goals System

Set and track short-term and long-term goals.

Create Goal

Field	Options
Title	Free text
Description	Free text (optional)
Type	Weekly / Monthly / Custom
Category	Study / Fitness / Coding / Career / Personal
Target Date	Date picker
Target Hours	Number (for hour-based goals)

Goal Card Shows

✅ Completion toggle (circle checkbox)
Title (strikethrough when done)
Description
Tags: type, category
Days remaining countdown (or "Overdue!" in red)
Progress bar if target hours set (current/target)
Delete button

Filters

All — show everything
Active — only incomplete goals
Completed — only finished goals

Stats Cards

Stat	Description
🎯 Total	Total number of goals
🏆 Done	Completed goals count
🔥 Active	Goals still in progress

📁 7. Routine Templates

Pre-built routine schedules you can load with one click.

Available Templates

📚 Student Routine

"BTech / BCA / MCA students ke liye perfect"

Time	Task
6:00–6:30	🌅 Morning Exercise
6:30–6:45	🧘 Meditation
7:00–9:00	📚 Subject 1 Study
9:00–9:30	☕ Breakfast Break
9:30–11:30	📖 Subject 2 Study
12:00–13:00	🍽️ Lunch Break
14:00–16:00	📝 Assignment Work
17:00–17:30	🏃 Evening Walk
20:00–22:00	📚 Revision

💻 Coding Routine

"Coders & developers ke liye"

Time	Task
7:00–7:30	☀️ Wake Up + Stretch
8:00–10:00	💻 DSA Practice
10:00–10:30	☕ Break
10:30–13:00	🔧 Project Work
13:00–14:00	🍽️ Lunch
14:00–16:00	📖 Tech Learning
17:00–19:00	💻 Open Source / Side Project
21:00–22:00	📝 Blog / Notes

🎯 Exam Mode

"Exam preparation ke liye intensive schedule"

Time	Task
5:30–8:00	📚 Subject 1 - Deep Study
8:00–8:30	☕ Quick Break
8:30–11:00	📖 Subject 2 - Theory
11:00–12:00	🍽️ Lunch
12:00–14:30	📝 Subject 3 - Practice
14:30–15:00	🧘 Power Nap
15:00–17:00	📚 Subject 4 - MCQs
17:00–17:30	🏃 Short Walk
18:00–20:00	📖 Revision & Notes
20:30–22:30	📝 Previous Year Papers

📖 Library Schedule

"Library mein padhai ke liye"

Time	Task
8:00–8:30	🚶 Go to Library
8:30–11:00	📚 Session 1 - Focus Study
11:00–11:15	☕ Tea Break
11:15–13:00	📖 Session 2 - Practice
13:00–14:00	🍽️ Lunch Break
14:00–16:30	📝 Session 3 - Notes
16:30–16:45	☕ Short Break
16:45–18:30	📚 Session 4 - Revision

How Templates Work

Click "Load Template" on any template
All tasks from that template are ADDED to your existing routine
Tasks are set as recurring Mon–Fri by default
You can edit/delete individual tasks after loading
Templates don't overwrite — they add on top

🧘 8. Focus & Timer Mode

A dedicated focus page with timer, Pomodoro, and distraction-free modes.

Timer Modes

⏱️ Normal Mode

Simple count-up timer
Start → Pause → Resume → Reset
No time limit — runs until you stop

🍅 Pomodoro Mode

Work phase → Break phase → Work phase → ...
Default: 25 minutes work, 5 minutes break
Configurable in settings (5–120 min work, 1–30 min break)
Shows current phase: 🔥 FOCUS TIME / ☕ BREAK TIME
Progress bar for current phase
Pomodoro count (how many completed)
Browser notification when phase changes (if permissions granted)

Timer Display

Large monospace digits: 00:00
Animated pulse glow when running
Direct DOM updates (no React re-renders)

Task Linking

Link timer to any today's task from dropdown
When you reset timer with >1 minute elapsed, linked task auto-marks as ✅ completed

Deep Focus Mode 🔲

Full-screen black overlay (z-index: 9999)
Only shows: current task, timer, play/pause/reset
No distractions — all other UI hidden
Press ESC or click exit to leave
PiP button also available in deep focus

PiP (Picture-in-Picture) Timer 📺

See PiP Timer section for full details.

Pomodoro Settings

Setting	Range	Default
Work duration	5–120 minutes	25 min
Break duration	1–30 minutes	5 min

📝 9. Weekly Review

Automatic weekly performance analysis.

6 Summary Cards

Stat	Description
📚 Total Study	Study minutes in last 7 days
✅ Tasks Done	Completed tasks this week
❌ Missed	Missed tasks this week
😊 Avg Mood	Average mood emoji
📖 Sessions	Total study sessions
📊 Consistency	Weekly consistency percentage

Best Subject This Week

Shows which subject had the most study time
Subject icon, name, and total time

Day-by-Day Breakdown

For each of the last 7 days:

Day name (Mon 15 Jan)
Progress bar (filled based on study time vs planned)
Total study time
✅/❌ status
Mood emoji

Export Weekly Report

Click "Export Weekly Report" button

Downloads a .txt file with:

ROUTINEFLOW WEEKLY REPORT
========================================
by Sudhir Kumar (@SudhirDevOps1)
Week: 2025-01-13 to 2025-01-19

Total Study: 14h 30m
Tasks Completed: 28
Tasks Missed: 5
Consistency: 85%
Streak: 12 days
Avg Mood: 😊
Best Subject: Data Structures (4h 20m)

💾 10. Data Manager

Complete control over your data.

Data Summary

6 cards showing counts:

Subjects, Sessions, Tasks, Logs, Goals, Habits
Total items stored

Export (Download JSON)

Click "Download JSON"
Downloads routineflow-backup-YYYY-MM-DD.json
Contains ALL app data

Import (Upload JSON)

Click "Upload JSON"
Select a previously exported .json file
All data is restored/overwritten
Shows success/error alert

Danger Zone — Reset All

Double confirmation required:
1. First confirm: "⚠️ Delete ALL data?"
2. Second confirm: "🚨 LAST CHANCE!"
Clears everything permanently

About Section

Developer info
Storage type: 100% localStorage
Keyboard shortcut reminder

🚀 Advanced Features

↩️ Undo / Redo System

When you delete a task, session, or goal, it goes to undo stack
Last 20 deletions are stored
Undo via:
- Command palette (Ctrl+K → "↩️ Undo Last Action")
- Restores the deleted item

👤 Multiple Profiles

Default profiles: Study 📚
Create custom: Coding 💻, Exam 🎯, etc.
Each profile can filter which routine tasks are shown
Switch profiles from Routine page
All profiles stored locally

🔄 Habit Tracker

Add habits with custom emoji icons
10 pre-set icons: 💧🏃📚🧘💊🍎✍️🎵😴🚿
Toggle completion per day
Track total days completed
Visible on Dashboard

⏰ Time Conflict Detection

When adding/editing a routine task
If the new time overlaps with existing task:
- Shows: "⚠️ Time conflict detected!"
- Still allows saving (warning only)
Checks: newStart < existingEnd AND newEnd > existingStart

🌓 Dark / Light Mode

Toggle from sidebar (desktop) or header (mobile)
Keyboard: Ctrl+K → "🌙 Toggle Dark Mode"
Persisted in localStorage
Applies to entire UI including forms, cards, calendar

🔔 Browser Notifications

Pomodoro phase changes trigger notifications:
- Work → Break: "🍅 Break time! Great focus session!"
- Break → Work: "🔥 Focus time! Get back to work!"
PiP popup also sends notifications
Requires browser notification permission

🎮 Gamification System (XP & Levels)

How XP is Earned

Action	XP Earned
Complete a task	10 XP per task
Study 5 minutes	2 XP
Each streak day	5 XP bonus

XP Formula

Total XP = (Completed Tasks × 10) + (Study Minutes ÷ 5 × 2) + (Streak × 5)

Level System (8 Levels)

Level	XP Required	Title
1	0 XP	🌱 Beginner
2	100 XP	📗 Learner
3	300 XP	📘 Consistent
4	600 XP	⚡ Focused
5	1000 XP	🔥 Dedicated
6	1500 XP	💎 Expert
7	2500 XP	🏆 Master
8	4000 XP	👑 Legend

Level Display

Sidebar (desktop): Level badge + XP bar + XP count
Dashboard: Dedicated XP card with progress bar
Mobile sidebar: Level and name

XP Progress Bar

Each level requires 500 XP to progress
Progress = (XP % 500) / 5 → percentage

🧠 Smart Insights & AI Suggestions

The app analyzes your data and generates intelligent insights.

Insight Types

Type	Color	Example
🧠 Info	Blue	"Your best focus time is around 7:00 PM"
⚠️ Warning	Red	"Math completion rate is only 45%"
💡 Suggestion	Blue	"You missed 'Java' 3 times. Try a different time slot"
🏆 Achievement	Green	"🔥 Amazing! 7 day streak!"

What It Analyzes

Best Focus Time Detection
- Groups completed sessions by hour
- Finds the hour with most productive minutes
- Tells you when you study best
Subject Difficulty Score
- Calculates completion rate per subject
- If <50% completion with 3+ sessions → warns you
- Suggests breaking into smaller sessions
Missed Task Pattern Detection
- Checks last 7 days for repeatedly missed tasks
- If same task missed 3+ times → suggests time change
Streak Achievements
- 7+ days → "🔥 Amazing!"
- 30+ days → "👑 Legendary!"
Overload Warning
- If study/coding tasks total >8 hours → warns about burnout
- Suggests adding more breaks
No-Break Detection
- If two study tasks are back-to-back (<5 min gap)
- Suggests adding a short break

Maximum Insights Shown: 6

📺 PiP (Picture-in-Picture) Timer

The most unique feature — float your timer outside the browser!

How It Works

Click "📺 PiP Mode" button on Focus page
A popup window opens with the timer
Popup is small (380×320px), positioned top-right
You can drag, resize, and move the popup
Switch to VS Code, YouTube, anything — timer stays visible!

Popup Window Features

Feature	Description
▶ Start / ⏸ Pause	Control timer from popup
↺ Reset	Reset timer from popup
Timer Display	Large monospace digits with glow animation
Status Indicator	Green dot = running, Red dot = paused
Phase Display	Shows 🔥 FOCUS or ☕ BREAK in Pomodoro
Progress Bar	Pomodoro phase progress
Pomodoro Count	Shows "🍅 3 pomodoros"
Task Name	Shows linked task name
Title Bar	Timer shown in window title (00:00 — RoutineFlow)

Visual Themes

Mode	Background
Normal (Dark)	Indigo gradient
Normal (Light)	Light blue gradient
Pomodoro Work	Dark red gradient
Pomodoro Break	Dark green gradient

Two-Way Sync

Main App → Popup: Timer state syncs in real-time
Popup → Main App: Play/pause/reset actions sync back via postMessage()
On popup close: Final state synced to main app

Where PiP Button Appears

✅ Focus page — main PiP button
✅ Deep Focus overlay — "Float Timer (PiP)" button
✅ Command palette — "📺 Toggle PiP Timer" command
✅ Desktop sidebar — PiP active indicator with close button
✅ Mobile header — PiP badge when active

Browser Support

Browser	Support
Chrome	✅ Works
Edge	✅ Works
Brave	✅ Works (popup approach)
Firefox	✅ Works (popup approach)
Safari	✅ Works (popup approach)
Opera	✅ Works

Note: If popups are blocked, you'll see a warning. Allow popups for the site.

PiP Active Indicators

Purple glowing badge in mobile header
Purple button in desktop sidebar
Active status banner on Focus page with "Close PiP" button

⌨️ Keyboard Shortcuts

Shortcut	Action
`Ctrl + K`	Open Command Palette
`ESC`	Close Command Palette / Exit Deep Focus

Command Palette Commands

Command	Action
🏠 Go to Dashboard	Switch to Dashboard tab
📋 Go to Routine	Switch to Routine tab
📖 Go to Study	Switch to Study tab
🔥 Go to Streaks	Switch to Streaks tab
📊 Go to Analytics	Switch to Analytics tab
🎯 Go to Goals	Switch to Goals tab
🧘 Go to Focus Mode	Switch to Focus tab
💾 Export Data	Download JSON backup
🌙 Toggle Dark Mode	Switch dark/light
↩️ Undo Last Action	Restore last deleted item
📺 Toggle PiP Timer	Open/close PiP window

Command Palette Features

Fuzzy search — type to filter commands
Keyboard accessible
Click outside to close
ESC to close

💾 JSON Data System

Data Structure

{
  "subjects": [
    {
      "id": "unique-id",
      "name": "Data Structures",
      "color": "#3B82F6",
      "icon": "📘"
    }
  ],
  "sessions": [
    {
      "id": "unique-id",
      "subjectId": "subject-id",
      "date": "2025-01-15",
      "startTime": "09:00",
      "endTime": "10:30",
      "status": "completed",
      "notes": "Binary Trees chapter completed",
      "rating": 4
    }
  ],
  "routineTasks": [
    {
      "id": "unique-id",
      "title": "DSA Practice",
      "startTime": "08:00",
      "endTime": "10:00",
      "duration": 120,
      "category": "coding",
      "subjectId": "subject-id",
      "colorLabel": "#8B5CF6",
      "isRecurring": true,
      "recurringDays": [1, 2, 3, 4, 5],
      "notes": "Focus on graphs",
      "order": 0
    }
  ],
  "dailyLogs": [
    {
      "date": "2025-01-15",
      "completedTasks": ["task-id-1", "task-id-2"],
      "partialTasks": ["task-id-3"],
      "missedTasks": [],
      "completedSessions": ["session-id-1"],
      "mood": 4,
      "notes": "",
      "wakeUpTime": "06:30",
      "sleepTime": "22:30",
      "totalStudyMinutes": 240,
      "productivityScore": 85,
      "distractionMinutes": 15
    }
  ],
  "goals": [
    {
      "id": "unique-id",
      "title": "Complete DSA in 30 days",
      "description": "All topics from arrays to DP",
      "targetDate": "2025-02-15",
      "completed": false,
      "createdAt": "2025-01-15",
      "category": "Coding",
      "type": "monthly",
      "targetHours": 60,
      "currentHours": 12
    }
  ],
  "habits": [
    {
      "id": "unique-id",
      "name": "Drink Water",
      "icon": "💧",
      "streak": 5,
      "completedDates": ["2025-01-13", "2025-01-14", "2025-01-15"],
      "createdAt": "2025-01-10"
    }
  ],
  "profiles": [
    {
      "id": "default",
      "name": "Study",
      "icon": "📚",
      "routineTaskIds": []
    }
  ],
  "activeProfileId": "default",
  "streakData": {
    "currentStreak": 7,
    "longestStreak": 15,
    "totalActiveDays": 23,
    "lastActiveDate": "2025-01-15",
    "weeklyConsistency": 85
  },
  "xpData": {
    "totalXP": 1250,
    "level": 6,
    "levelName": "💎 Expert",
    "todayXP": 1250,
    "streakBonus": 35
  },
  "settings": {
    "darkMode": false,
    "theme": "indigo",
    "pomodoroWork": 25,
    "pomodoroBreak": 5,
    "notificationsEnabled": false
  }
}

localStorage Keys

Key	Data
`rf-subjects`	Subjects array
`rf-sessions`	Study sessions array
`rf-tasks`	Routine tasks array
`rf-logs`	Daily logs array
`rf-goals`	Goals array
`rf-habits`	Habits array
`rf-profiles`	Profiles array
`rf-profile`	Active profile ID
`rf-settings`	App settings
`rf-undo`	Undo stack

Import/Export Rules

Export downloads the complete state of the app
Import overwrites existing data with imported data
Partial imports work — missing keys are kept as-is
Invalid JSON shows error alert
File must be .json extension
File input resets after each import

🎨 UI/UX Design System

Glassmorphism Cards

Semi-transparent background (rgba(255, 255, 255, 0.85))
Backdrop blur (blur(12px))
Subtle border (rgba(255, 255, 255, 0.4))
Soft shadow (0 8px 32px rgba(0, 0, 0, 0.06))
Hover: lift up 2px + indigo glow shadow

Animations

Animation	Used For
`fadeInUp`	Page transitions (0.5s)
`fadeIn`	Modal appearances
`scaleIn`	Card appearances
`float`	Floating elements (3s loop)
`pulse-glow`	Timer when running
`streak-fire`	🔥 streak badge (1s loop)
`shimmer`	Loading/shimmer effects
`pip-glow`	PiP active indicator

Color Palette

Element	Light	Dark
Background	`#F9FAFB`	`#0F0F23`
Card BG	`rgba(255,255,255,0.85)`	`rgba(30,41,59,0.85)`
Text	`#111827`	`#E2E8F0`
Primary	`#6366F1` (Indigo)	`#6366F1`
Success	`#10B981`	`#10B981`
Warning	`#F59E0B`	`#F59E0B`
Error	`#EF4444`	`#EF4444`

Gradient Text

App name "RoutineFlow" uses gradient: Indigo → Purple → Pink
CSS: linear-gradient(135deg, #6366f1, #8b5cf6, #ec4899)

Responsive Design

Screen	Layout
Desktop (≥1024px)	Fixed left sidebar (256px) + content area
Mobile (<1024px)	Hamburger menu + bottom tab bar

Mobile Bottom Tab Bar

Shows 5 quick tabs + "More" button:

🏠 Dashboard
📋 Routine
📖 Study
🔥 Streaks
📊 Analytics
⋯ More (opens sidebar drawer)

Scrollbar

Thin (5px)
Indigo gradient thumb
Transparent track

🔧 Technical Architecture

Component Architecture

App (Main Container)
├── State Management (useLocalStorage hooks)
├── Timer Engine (useTimerEngine — ref-based)
├── Deep Focus Overlay
├── Command Palette
├── Mobile Header
├── Mobile Sidebar Drawer
├── Desktop Sidebar
├── Page Router (switch/case)
│   ├── DashboardPage (memo)
│   │   └── HabitAddButton
│   ├── RoutinePage (memo)
│   ├── StudyPage (memo)
│   ├── StreakPage (memo)
│   ├── AnalyticsPage (memo)
│   ├── GoalsPage (memo)
│   ├── TemplatesPage (memo)
│   ├── FocusPage (memo)
│   │   └── TimerDisplay (memo)
│   ├── ReviewPage (memo)
│   └── DataPage (memo)
└── Mobile Bottom Nav

State Management

No Redux, no Zustand, no Context API
Pure useState + useLocalStorage (custom hook)
Timer uses useRef for zero-render updates
useMemo for expensive calculations
useCallback for stable function references
React.memo() on all page components

Timer Engine Architecture

useTimerEngine (custom hook)
├── stateRef (useRef) — NO useState for elapsed
├── intervalRef (useRef) — setInterval handle
├── listenersRef (useRef) — pub-sub subscribers
├── toggle() — play/pause
├── reset() — reset to 0
├── setMode() — normal/pomodoro
├── setTaskId() — link to task
├── subscribe() — register listener (for TimerDisplay)
├── syncFromPip() — receive state from popup
└── getState() — read current state

Why Ref-Based Timer?

setInterval + setState every second = entire app re-renders
With 10+ pages defined inside App, each re-render recreates all components
This causes blinking/flickering
Solution: Store elapsed in useRef, update DOM directly via subscription
React state only updates on meaningful events (play/pause/reset/phase-change)

TimerDisplay Component

Subscribes to timer engine's pub-sub
Updates textContent directly on DOM element via ref
Zero React re-renders for digit updates
React.memo() prevents parent re-renders from affecting it

⚡ Performance Optimizations

Optimization	Description
Ref-based timer	Timer elapsed stored in `useRef`, not `useState` — zero re-renders per second
Direct DOM updates	Timer digits updated via `ref.textContent`, not React state
React.memo()	All 10 page components wrapped in `memo()`
useMemo()	Heavy calculations (streak, XP, insights, tasks) memoized
useCallback()	Event handlers have stable references
Lazy filtering	Data filtered only when dependencies change
External page components	Defined outside App to prevent recreation
Pub-sub pattern	Timer uses subscription pattern instead of React state propagation
No external state library	Zero bundle size overhead from state management
Single file architecture	No unnecessary module boundaries for hot code

📖 How to Use — Complete Guide

Step 1: Set Up Your Subjects (Routine → Subjects)

Go to 📋 Routine tab
Click "📚 Subjects" button
Add your subjects: Name, Color, Icon
Examples: Data Structures (📘 Blue), OS (📗 Green), DBMS (📕 Red)

Step 2: Create Your Daily Routine (Routine → Add Task)

Click "+ Add Task"
Fill in: Name, Start Time, End Time, Category
Link to a subject if it's Study/Coding
Choose colors and recurring days
OR use 📁 Templates to load a pre-built routine

Step 3: Track Your Day (Dashboard)

Go to 🏠 Dashboard
Set your Wake Up time and Mood
For each task:
- ✅ if completed
- ⚡ if partially done
- ❌ if missed
Watch your progress bar fill up!

Step 4: Log Study Sessions (Study)

Go to 📖 Study tab
Click "+ Log Session"
Select subject, set times, rate yourself
Add notes about what you studied

Step 5: Use Focus Timer (Focus)

Go to 🧘 Focus tab
Choose Normal or Pomodoro mode
Link a task from dropdown
Click Start — timer begins
Use Deep Focus for distraction-free mode
Use PiP to float timer while coding

Step 6: Check Your Streaks (Streaks)

Go to 🔥 Streaks tab
See your calendar heatmap
Green = great day, Yellow = partial, Red = missed
Keep the streak alive!

Step 7: Review & Improve (Analytics + Review)

📊 Analytics — see your patterns and weak areas
📝 Review — weekly summary of your performance
Follow Smart Insights on Dashboard

Step 8: Backup Your Data (Data)

Go to 💾 Data tab
Click "Download JSON" regularly
Keep backups safe — all data is local only!

📏 Rules & Behavior

Task Status Rules

Status	Meaning	Dashboard Color	Calendar Color
✅ Completed	Task fully done	Green bg	Green cell
⚡ Partial	Task partially done	Yellow bg	Yellow cell
❌ Missed	Task not done	Red bg	Red cell
— No status	Not marked yet	Default bg	Gray cell

Streak Rules

A day is "active" if it has ANY completed tasks or completed sessions
Current streak counts consecutive active days backwards from today
If today is not active, streak counts from yesterday
Missing one day breaks the current streak (but longest streak is preserved)
Streak resets to 0 after a gap
You can rebuild by being active again

Productivity Score Formula

Score = ((completed_count + partial_count × 0.5) / total_tasks) × 100%

Completed tasks = 1.0 weight
Partial tasks = 0.5 weight
Missed tasks = 0 weight
No tasks = 0%

Time Calculations

Duration = End Time − Start Time (in minutes)
Negative durations are treated as 0
Times are in 24-hour format internally, displayed as 12-hour AM/PM

Data Persistence Rules

All data auto-saves to localStorage on every change
No manual save button needed
Data persists across page refreshes
Data is cleared only by:
- Browser clear site data
- App reset (Data → Danger Zone)
- Manual localStorage clearing
Data is device-specific — won't sync across devices
Use JSON export/import to transfer between devices

Template Loading Rules

Templates ADD tasks — they don't replace existing ones
Each loaded task gets a unique ID
All template tasks default to Mon–Fri recurring
Template tasks can be edited/deleted individually after loading

Undo Rules

Only deletions are undoable (tasks, sessions, goals)
Last 20 deletions stored
Edits are NOT undoable
Undo stack is persisted in localStorage
Each undo restores one item at a time

Profile Rules

Default profile "Study" always exists
New profiles start with empty task filter
Switching profiles changes which tasks are visible
Tasks themselves are shared — profiles only filter view
Deleting a profile doesn't delete tasks

📂 Project Structure

routineflow/
├── index.html              # Entry HTML with meta tags
├── package.json            # Dependencies
├── tsconfig.json           # TypeScript config
├── vite.config.ts          # Vite + Tailwind + SingleFile config
├── README.md               # This file
└── src/
    ├── main.tsx            # React root mount
    ├── index.css           # Global CSS, animations, glassmorphism
    ├── App.tsx             # Main app component + all pages
    ├── types.ts            # TypeScript interfaces
    ├── hooks/
    │   └── useLocalStorage.ts  # localStorage persistence hook
    └── utils/
        ├── helpers.ts      # All utility functions
        └── cn.ts           # Tailwind class merger

File Sizes (Approximate)

File	Purpose	Lines
`App.tsx`	All components + logic	~1200
`helpers.ts`	Utilities + templates	~350
`types.ts`	TypeScript types	~110
`index.css`	Styles + animations	~250
`useLocalStorage.ts`	Hook	~25

🛠️ Tech Stack

Technology	Version	Purpose
React	19.2	UI framework
TypeScript	5.9	Type safety
Vite	7.2	Build tool (fast!)
Tailwind CSS	4.1	Utility-first CSS
Lucide React	0.563	Icon library (30+ icons used)
clsx	2.1	Conditional classnames
tailwind-merge	3.4	Tailwind class deduplication
vite-plugin-singlefile	2.3	Bundle into single HTML

Icons Used (Lucide React)

BookOpen, Clock, Menu, X, Plus, Trash2, Edit2, Check, Copy, ChevronLeft, ChevronRight, Sun, Moon, Play, Pause, RotateCcw, Download, Upload, AlertTriangle, Search, Zap, Trophy, Flame, TrendingUp, Timer, Brain, Command, Maximize2, FileText, Target, MonitorSmartphone, Minimize2, ExternalLink

🚀 Getting Started

Prerequisites

Node.js 18+ installed
npm or yarn

Installation

# Clone the repository
git clone https://github.com/SudhirDevOps1/routineflow.git
cd routineflow

# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

Development

npm run dev
# Opens at http://localhost:5173

Production Build

npm run build
# Output: dist/index.html (single file!)

The build uses vite-plugin-singlefile to bundle everything into a single index.html file that you can:

Host on any static server
Open directly in a browser
Share as a single file
Deploy to GitHub Pages

🌐 Browser Support

Browser	Version	Status
Chrome	90+	✅ Full support
Edge	90+	✅ Full support
Firefox	90+	✅ Full support
Brave	Latest	✅ Full support
Safari	15+	✅ Full support
Opera	Latest	✅ Full support
Mobile Chrome	Latest	✅ Full support
Mobile Safari	Latest	✅ Full support

PiP Timer uses popup windows — works in ALL browsers. May need popup permission.

❓ FAQ

Q: Where is my data stored? A: Everything is in your browser's localStorage. Nothing is sent to any server.

Q: Will I lose data if I clear browser cache? A: Yes! Always export JSON backups regularly.

Q: Can I use this on mobile? A: Yes! Fully responsive with bottom navigation on mobile.

Q: Can I transfer data between devices? A: Yes — Export JSON on one device, Import on another.

Q: Does it work offline? A: Yes! Once loaded, it works completely offline. All data is local.

Q: Is there a login/signup? A: No. No authentication needed. Open and use.

Q: Can multiple people use it? A: Use multiple profiles on the same device, or export/import between devices.

Q: The PiP timer popup is blocked? A: Allow popups for the site in your browser settings.

Q: How do I reset everything? A: Data tab → Danger Zone → Reset All (requires double confirmation).

Q: Can I contribute? A: Yes! This is open-source. Fork, improve, and submit PRs.

📝 License

Open-source. Free to use, modify, and distribute.

👨‍💻 Author

Sudhir Kumar

GitHub: @SudhirDevOps1
Project: RoutineFlow

Built with ❤️ for students who want to track their routine and study consistently.

🚀 RoutineFlow — Plan. Track. Grow.

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
src		src
LICENSE		LICENSE
README.md		README.md
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vite.config.ts		vite.config.ts

Folders and files

Latest commit

History

Repository files navigation

🚀 RoutineFlow

Daily Routine & Study Tracker for Students

📋 Table of Contents

📖 About

👥 Who Is This For?

✨ Features Overview

📄 Page-by-Page Feature Details

🏠 1. Dashboard

Hero Section (Gradient Banner)

4 Stat Cards

XP & Level System

Today's Log

Smart Insights Panel

Today's Task List

Progress Bar

Habit Tracker

📋 2. Routine Builder

Add Task Form

Auto-Calculated

Task Actions

Subject Manager (Built-in)

Day Filter

Profile Switching

📖 3. Study Tracking

Log New Session

Session List

Status Badge Colors

🔥 4. Streaks & Attendance

4 Stat Cards

Calendar Heatmap

Color Legend

How Streaks Work

📊 5. Smart Analytics

4 Summary Cards

Best Focus Time Detection

7-Day Bar Chart

Subject-wise Analysis

How Weekly Change is Calculated

🎯 6. Goals System

Create Goal

Goal Card Shows

Filters

Stats Cards

📁 7. Routine Templates

Available Templates

📚 Student Routine

💻 Coding Routine

🎯 Exam Mode

📖 Library Schedule

How Templates Work

🧘 8. Focus & Timer Mode

Timer Modes

⏱️ Normal Mode

🍅 Pomodoro Mode

Timer Display

Task Linking

Deep Focus Mode 🔲

PiP (Picture-in-Picture) Timer 📺

Pomodoro Settings

📝 9. Weekly Review

6 Summary Cards

Best Subject This Week

Day-by-Day Breakdown

Export Weekly Report

💾 10. Data Manager

Data Summary

Export (Download JSON)

Import (Upload JSON)

Danger Zone — Reset All

About Section

🚀 Advanced Features

↩️ Undo / Redo System

👤 Multiple Profiles

🔄 Habit Tracker

⏰ Time Conflict Detection

🌓 Dark / Light Mode