NeuroFlow

NeuroFlow is an AI-assisted cognitive scheduler that helps users turn goals into actionable tasks, organize work around mental energy patterns, and build consistent deep-work habits.

The app combines:

• Natural-language task capture with Groq-powered parsing
• Energy-aware scheduling and fatigue checks
• Deep-work tracking and recovery prompts
• Gamified progress (XP, levels, streaks, daily challenges)
• Supabase-backed auth and data persistence

Tech Stack

• React 19 + TypeScript
• Vite 7
• Tailwind CSS 4
• Zustand (global state)
• Supabase (Auth + Postgres)
• Groq API (LLM task parsing and scheduling)
• Framer Motion + Lucide icons

Features

• Chat-first task creation
  • Users can type tasks in natural language.
  • The assistant classifies category, priority, cognitive load, and estimated effort.
• Smart scheduling
  • Tasks can be sequenced into focus blocks with breaks/recovery blocks.
  • Scheduling is shaped by profile data such as peak hours and energy.
• Deep work mode
  • Start/stop focused sessions tied to tasks.
  • Track focused minutes and related profile metrics.
• Recovery support
  • Fatigue checks suggest quick interventions (movement, breathing, hydration, etc.).
• Gamification
  • XP rewards, level progression, streak tracking, and daily challenge completion.
• Persistent user workspace
  • Supabase Auth for sign-in.
  • Tasks, schedule blocks, profile, messages, and challenges stored per user with RLS.

Project Structure

NeuroFlow/
  src/
    components/         # UI views and widgets (Dashboard, Chat, Schedule, Stats, etc.)
    engine/             # AI logic wrappers (task parse, scheduling, fatigue)
    lib/                # API clients and utility modules (Groq, Supabase, helpers)
    store/              # Zustand app store and business actions
    types/              # Shared TypeScript types
  supabase/
    schema.sql          # Database schema + RLS policies

Prerequisites

• Node.js 20+
• npm 10+
• A Supabase project
• A Groq API key

Environment Variables

Create a .env file in the project root with:

VITE_SUPABASE_URL=your_supabase_project_url
VITE_SUPABASE_ANON_KEY=your_supabase_anon_key
VITE_GROQ_API_KEY=your_groq_api_key
VITE_GROQ_MODEL=llama-3.1-8b-instant
VITE_GROQ_BASE_URL=https://api.groq.com/openai/v1

Notes:

• VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY are required for auth and persistence.
• VITE_GROQ_API_KEY is required for AI parsing/scheduling features.
• If model/base URL are omitted, defaults are used in code.

Database Setup (Supabase)

1. Open your Supabase project.
2. Go to SQL Editor.
3. Run the SQL in supabase/schema.sql.

This creates tables for:

• tasks
• chat_messages
• user_profile
• daily_challenges
• schedule_blocks

It also enables row-level security (RLS) and user-scoped policies.

Installation

npm install

Run Locally

npm run dev

Vite will start a local dev server (typically at http://localhost:5173).

Available Scripts

• npm run dev - Start development server
• npm run build - Type-check and build production bundle
• npm run preview - Preview production build locally
• npm run lint - Run ESLint

Core App Flow

1. User authenticates via Supabase Auth.
2. App initializes state from Supabase (tasks, messages, profile, etc.).
3. User adds tasks through chat or direct task actions.
4. AI helpers convert text into structured tasks and schedule blocks.
5. Deep-work sessions and completion events update profile/XP/challenges.
6. Store actions sync updates back to Supabase.

Troubleshooting

• Blank or limited functionality after launch:
  • Verify .env values are present and valid.
• Auth/data not loading:
  • Confirm Supabase URL/key and that schema.sql has been applied.
  • Check RLS policies are enabled and user-scoped.
• AI responses failing:
  • Confirm VITE_GROQ_API_KEY is set.
  • Verify network access to the configured Groq base URL.
• Build issues:
  • Use Node.js 20+.
  • Run npm install again and then npm run build.

Future Improvements

• Add automated tests for store actions and scheduling logic.
• Add offline queue/sync strategy.
• Add calendar export integrations.
• Add role-based profiles for different study/work styles.

Acknowledgements

• Supabase for auth and persistence
• Groq for low-latency model inference
• React, Vite, Tailwind, Zustand, and Framer Motion ecosystems