FocusFlow AI — Adaptive Study Planner

💡 Inspiration

As college students, we frequently juggle 4 to 6 rigorous courses, competing assignment deadlines, and unpredictable workloads with only 2 to 3 hours of focused study time each day.

Traditional study apps fall into two failure modes:

1. Endless To-Do Lists: They lack time-budgeting and overwhelm students with unchecked backlogs.
2. Rigid Calendar Blocks: The schedule breaks down the moment you get sick, have an emergency, or miss a single study session.

We built FocusFlow AI to fix this broken cycle with Adaptive Rebalancing: an intelligent, guilt-free planner that turns course syllabi into realistic daily study blocks and smoothly recalculates future workloads whenever life happens.

🎯 What It Does

FocusFlow AI is an end-to-end adaptive study planner and focus companion:

1. High-Precision Syllabus Ingestion: Drag-and-drop course syllabi in PDF, TXT, or Markdown format. Our dual-engine parser strips administrative boilerplate (office hours, grading weight percentages, academic honesty statements) and extracts exam dates and lecture modules.
2. Gemini AI Zero-Shot Extraction: With one click, Google Gemini Flash parses unformatted or multi-column schedules into structured topics with cognitive difficulty ratings (easy, medium, hard) and estimated study hours.
3. Deterministic Priority Scheduling: Workload allocation is governed by a transparent mathematical priority formula: $$\text{Priority} = \frac{\text{Difficulty Weight}}{\text{Days Until Exam} + 0.1} \times \text{Workload Hours}$$ It fills study days strictly up to your chosen daily capacity (e.g., 3.0 hours/day) and prevents tasks from being scheduled on or after an exam date.
4. One-Click Adaptive Rebalance: If you miss a study session, the Capacity Warning banner triggers. One click on "Rebalance Plan" recalculates future days and redistributes pending topics forward.
5. Integrated Pomodoro Focus Companion: Built-in 25-minute work and 5-minute break intervals with SVG circular progress rings, ambient harmonic Web Audio chimes, and automatic session logging.

🛠️ How We Built It

We developed FocusFlow AI following the official Devpost Learn Skill Pack (1-start through 6-ship), practicing strict planning before code:

• devpost/scope.md: Defined the proof-of-concept boundary and adaptive rebalancing kernel.
• devpost/prd.md: Mapped the core student journey, acceptance criteria, and edge cases.
• devpost/spec.md: Architected the data schema, scheduling algorithms, and component hierarchy.

Tech Stack:

• Frontend & Architecture: React 18, TypeScript 5, Vite 6
• Styling & UI/UX: Tailwind CSS with a PayRevive-inspired command center aesthetic, DM Mono telemetry badges, and dynamic high-contrast Day & Night themes.
• AI Integration: Google Gemini API (gemini-1.5-flash) for zero-shot syllabus extraction and conceptual study coaching, with a 100% offline heuristic fallback.
• Audio & Audio Synthesis: Native HTML5 Web Audio API (zero external audio file dependencies).
• Data Persistence: Browser localStorage with typed JSON serialization for instant reload recovery.

🧗 Challenges We Faced

1. Messy Real-World Syllabi: University syllabi are 70% noise—containing grading policies, Zoom links, and textbook ISBNs. We engineered a multi-stage regex filter and integrated Gemini's structured JSON schema to eliminate noise and accurately capture ordinal exam dates (e.g., "Dec 18th at 2:00 PM").
2. Non-Trivial Rebalancing Edge Cases: When a student misses a session close to an exam, naive algorithms easily overflow daily capacity limits. We implemented a priority-weighted sorting queue that strictly enforces daily maximum hours while surfacing capacity warnings when a deadline is impossible without increasing study time.
3. Seamless Day/Night Readability: Achieving crisp typography in both dark mode and light mode required decoupling theme styles from hardcoded OS media queries and implementing dynamic CSS tokens.

🏆 Accomplishments We're Proud Of

• Zero Broken Days: Our automated test verification suite (npm test) mathematically proves that no day ever exceeds the student's daily study limit and zero topics are scheduled on or after their exam date.
• Frictionless Experience: Evaluators can test the entire app in under 30 seconds using the preloaded "Load Demo Data" and "Simulate Miss" buttons.
• Dual-Engine Flexibility: FocusFlow AI is fully functional 100% offline, yet harnesses Gemini AI for supercharged extraction when available.

📚 What We Learned

• Plan Before You Code: Using the Devpost Learn skills taught us to interview ourselves, specify edge cases in the PRD, and architect data models in the Spec before writing a single line of frontend code. This prevented feature creep and debugging loops.
• Flipped Interaction: Collaborating with an AI coding agent as an intentional co-pilot rather than just asking for raw code resulted in a significantly cleaner codebase.

🚀 What's Next for FocusFlow AI

• Calendar Sync: One-click export to Google Calendar and Apple Calendar (.ics).
• Spaced Repetition Integration: Automatic review scheduling following the Ebbinghaus forgetting curve.
• Study Group Sync: Collaborative rebalancing for study groups preparing for shared exams.

Built With

• canvas-confetti
• client-side
• edtech
• gemini-api
• google-ai
• localstorage
• lucide-react
• react
• tailwindcss
• typescript
• vite
• web-audio-api