📚 StudyFlow

AI-Powered Study Planner & Productivity Platform

StudyFlow transforms how students plan, track, and optimize their study sessions using AI-generated schedules, an intelligent study assistant, and deep productivity analytics.

Live Demo · Report Bug · Request Feature

📋 Table of Contents

Features
Tech Stack
Architecture
Prerequisites
Getting Started
Environment Variables
Database Setup
Development
Deployment
Project Structure
API Reference
Troubleshooting
Contributing
License

✨ Features

Category	Feature	Description
🤖 AI Schedule Generation	Smart Scheduling	Generates optimized daily study plans using Gemini AI based on subject priority, weekly targets, and syllabus content
💬 AI Study Assistant	Chat Interface	Context-aware AI chatbot that knows your subjects, tasks, and progress to provide personalized study advice
📊 Analytics Dashboard	Progress Tracking	Visual charts and statistics showing study hours, weekly progress, completion rates, and study streaks
⏱️ Pomodoro Timer	Focus Sessions	Integrated Pomodoro timer with subject/task linking, automatic session tracking, and break management
📝 Task Management	Smart Tasks	Create, prioritize, and track study tasks with due dates, estimated durations, and subject associations
📚 Subject Management	Course Organizer	Manage subjects with color coding, priority levels, weekly hour targets, and PDF syllabus upload
📄 Syllabus Parsing	PDF Intelligence	Upload PDF syllabi for automatic text extraction — AI uses this context to generate topic-specific study sessions
📓 Notes Management	Document Store	Upload and manage study notes with PDF support and text extraction
🌓 Dark/Light Mode	Theme System	Full dark mode support with system preference detection
🔐 Authentication	Secure Auth	Email/password authentication with Supabase Auth, including signup confirmation flow
📱 Responsive Design	Mobile Ready	Fully responsive layout optimized for desktop, tablet, and mobile viewports

🛠 Tech Stack

Core Framework

Technology	Version	Purpose
Next.js	16.2	React framework with App Router, RSC, and API routes
React	19	UI library with Server Components
TypeScript	5.7	Type-safe development

Backend & Data

Technology	Purpose
Supabase	PostgreSQL database, Auth, Row Level Security, Storage
Google Gemini AI	`gemini-2.5-flash` for schedule generation, `gemini-2.5-flash-lite` for chat
Vercel AI SDK	Structured AI output generation (`generateText`, `generateObject`)
Zod	Runtime schema validation for AI responses

UI & Styling

Technology	Purpose
Tailwind CSS 4	Utility-first CSS framework
Radix UI	Accessible headless UI primitives
shadcn/ui	Pre-built component library
Framer Motion	Animations and transitions
Recharts	Data visualization and analytics charts
Lucide React	Icon library
Geist Font	Typography (Sans + Mono)

Utilities

Technology	Purpose
pdf-parse	PDF text extraction for syllabus processing
react-markdown	Markdown rendering in AI assistant
date-fns	Date manipulation and formatting
SWR	Data fetching and caching
Sonner	Toast notifications
React Hook Form	Form state management

🏗 Architecture

The platform architecture follows a modern, decoupled structure utilizing Next.js as the core application engine, Supabase as the backend/database layer, and Google Gemini AI for advanced intelligent services.

📐 View PlantUML / PlantText Code

@startuml StudyFlow_Architecture
!theme slate
skinparam linetype ortho
skinparam PackageStyle rectangle
skinparam shadowing false
skinparam ArrowThickness 2
skinparam ArrowColor #4285F4

package "Client Layer (Frontend)" {
  [Landing Page\n(SSR)] as Landing
  [Dashboard\n(SSR + CSR)] as Dashboard
  [Auth Pages\n(SSR)] as AuthPages
}

package "Next.js App Router (Middleware & API)" {
  [Middleware\n(Session Guard)] as Middleware
  [API Routes\n(/api/*)] as APIRoutes
  [Server Components\n(Data Fetching)] as RSC
}

package "Supabase (Backend-as-a-Service)" {
  [Supabase Auth\n(JWT Tokens)] as SupaAuth
  [PostgreSQL DB\n(RLS Policies)] as DB
  [Storage\n(Syllabi & Notes PDFs)] as Storage
}

package "AI Engine (Google Gemini)" {
  [gemini-2.5-flash\n(Smart Schedule Gen)] as GeminiFlash
  [gemini-2.5-flash-lite\n(Intelligent Study Chat)] as GeminiLite
}

Landing --> Middleware
Dashboard --> Middleware
AuthPages --> Middleware

Middleware --> APIRoutes : Path Guards
Middleware --> RSC : Session Props

APIRoutes --> SupaAuth : Verify Token
APIRoutes --> DB : Mutate Data
APIRoutes --> Storage : Read/Write PDFs

RSC --> DB : Server-side queries

APIRoutes --> GeminiFlash : Structured Output
APIRoutes --> GeminiLite : Streamed Chat
@endum

Authentication Flow

User signs up/in → Supabase Auth issues JWT
Middleware (middleware.ts) refreshes session on every request
Server Components validate user via supabase.auth.getUser()
API routes authenticate requests server-side before processing
Row Level Security (RLS) enforces data isolation at the database level

📦 Prerequisites

Requirement	Version
Node.js	≥ 18.17
pnpm	≥ 9.x (recommended) or npm
Supabase Account	Free tier
Google AI API Key	Get key
Vercel Account	Free tier (for deployment)

🚀 Getting Started

1. Clone the Repository

git clone https://github.com/PREMRAJESH/StudyFLow.git
cd StudyFLow

2. Install Dependencies

# Using pnpm (recommended — matches CI lockfile)
pnpm install

# OR using npm
npm install

⚠️ Important: This project uses pnpm-lock.yaml as the lockfile. Vercel auto-detects this and uses pnpm for CI builds. Always commit pnpm-lock.yaml after adding/removing dependencies.

3. Configure Environment Variables

cp .env.local.example .env.local

Fill in the values (see Environment Variables below).

4. Set Up the Database

Run the full schema in your Supabase SQL Editor — see Database Setup.

5. Start the Development Server

pnpm dev
# or
npm run dev

Open http://localhost:3000 to view the app.

🔑 Environment Variables

Create a .env.local file in the project root with the following variables:

# ─── Supabase ───────────────────────────────────────────
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-supabase-anon-key

# ─── Google Gemini AI ───────────────────────────────────
GOOGLE_GENERATIVE_AI_API_KEY=your-google-ai-api-key

Where to Get These Values

Variable	Source
`NEXT_PUBLIC_SUPABASE_URL`	Supabase Dashboard → Project → Settings → API → Project URL
`NEXT_PUBLIC_SUPABASE_ANON_KEY`	Supabase Dashboard → Project → Settings → API → `anon` / `public` key
`GOOGLE_GENERATIVE_AI_API_KEY`	Google AI Studio → Create API Key

🔒 Security: The NEXT_PUBLIC_ prefix makes variables available client-side. The Supabase anon key is safe to expose — it's rate-limited and gated by RLS policies. The GOOGLE_GENERATIVE_AI_API_KEY is server-only and never exposed to the client.

🗄 Database Setup

Quick Setup

Go to your Supabase Dashboard
Select your project → SQL Editor
Paste the entire contents of supabase-schema.sql
Click Run

Schema Overview

The database includes 7 tables with full Row Level Security:

profiles          ← User profiles (auto-created on signup via trigger)
subjects          ← Study subjects with color, priority, syllabus
study_sessions    ← Scheduled/completed study sessions
tasks             ← Study tasks with due dates and priorities
pomodoro_sessions ← Pomodoro timer session tracking
ai_chat_messages  ← AI assistant conversation history
study_goals       ← Long-term study goals with progress tracking
notes_documents   ← Uploaded notes with extracted text

Storage Buckets

Bucket	Purpose	Max Size	MIME Types
`syllabi`	Subject syllabus PDFs	10 MB	`application/pdf`
`notes`	Study notes PDFs	10 MB	`application/pdf`

Key Database Features

Row Level Security (RLS): Every table enforces user-level data isolation
Auto-profile creation: A Postgres trigger creates a profile row on user signup
Computed columns: study_sessions.duration_minutes auto-calculates from start/end times
Performance indexes: All tables indexed on user_id and frequently-queried columns

💻 Development

Available Scripts

pnpm dev          # Start development server (Next.js with hot reload)
pnpm build        # Create production build
pnpm start        # Start production server
pnpm lint         # Run ESLint

Code Organization Conventions

Server Components are the default — used for data fetching in page/layout files
Client Components use "use client" directive — used for interactivity (forms, timers, etc.)
API Routes in app/api/ handle server-side AI processing and data mutations
Path aliases use @/* mapping to the project root

🌐 Deployment

Deploy to Vercel (Recommended)

Option A: One-Click Deploy

Option B: CLI Deploy

# Install Vercel CLI
npm i -g vercel

# Deploy
vercel

Option C: Git Integration

Push your code to GitHub
Import the repo in Vercel Dashboard
Vercel auto-detects Next.js and pnpm
Add environment variables in Vercel → Project → Settings → Environment Variables
Deploy 🚀

Vercel Configuration

Setting	Value
Framework Preset	Next.js (auto-detected)
Build Command	`next build` (default)
Output Directory	`.next` (default)
Install Command	`pnpm install` (auto-detected from lockfile)
Node.js Version	18.x or 20.x

Required Environment Variables on Vercel

Add these in Vercel → Project → Settings → Environment Variables:

NEXT_PUBLIC_SUPABASE_URL       = https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY  = your-supabase-anon-key
GOOGLE_GENERATIVE_AI_API_KEY   = your-google-ai-api-key

Post-Deployment Checklist

Verify all environment variables are set on Vercel
Run the database schema in Supabase SQL Editor
Configure Supabase Auth → URL Configuration:
- Site URL: https://your-app.vercel.app
- Redirect URLs: https://your-app.vercel.app/auth/callback
Test signup/login flow end-to-end
Test AI schedule generation with at least one subject
Verify PDF upload works (Supabase Storage buckets exist)

📁 Project Structure

StudyFlow/
├── app/
│   ├── api/
│   │   ├── chat/route.ts              # AI chat assistant endpoint
│   │   ├── generate-schedule/route.ts # AI schedule generation endpoint
│   │   ├── generate-tasks/            # AI task generation endpoint
│   │   ├── upload-syllabus/route.ts   # PDF upload & text extraction
│   │   └── notes/                     # Notes CRUD operations
│   ├── auth/
│   │   ├── login/                     # Login page
│   │   ├── sign-up/                   # Signup page
│   │   ├── sign-up-success/           # Post-signup confirmation
│   │   ├── callback/                  # OAuth/email callback handler
│   │   └── error/                     # Auth error page
│   ├── dashboard/
│   │   ├── page.tsx                   # Main dashboard with stats
│   │   ├── layout.tsx                 # Sidebar + header layout
│   │   ├── analytics/                 # Charts & progress analytics
│   │   ├── assistant/                 # AI chat interface
│   │   ├── focus/                     # Pomodoro timer page
│   │   ├── schedule/                  # Study schedule management
│   │   ├── subjects/                  # Subject management
│   │   ├── tasks/                     # Task management
│   │   ├── notifications/             # Notification center
│   │   └── settings/                  # User preferences
│   ├── layout.tsx                     # Root layout (fonts, theme, analytics)
│   ├── page.tsx                       # Landing page
│   └── globals.css                    # Global styles & Tailwind config
├── components/
│   ├── dashboard/                     # Dashboard widgets (overview, streak, etc.)
│   ├── focus/                         # Pomodoro timer component
│   ├── landing/                       # Landing page sections (hero, features, CTA)
│   ├── schedule/                      # Schedule management components
│   ├── subjects/                      # Subject CRUD dialogs
│   ├── tasks/                         # Task CRUD dialogs
│   ├── ui/                            # shadcn/ui base components
│   ├── theme-provider.tsx             # next-themes provider
│   └── theme-toggle.tsx               # Dark/light mode toggle
├── lib/
│   ├── ai/errors.ts                   # AI error handling utilities
│   ├── supabase/
│   │   ├── client.ts                  # Browser Supabase client
│   │   ├── server.ts                  # Server Supabase client
│   │   └── middleware.ts              # Auth session refresh middleware
│   ├── types.ts                       # TypeScript type definitions
│   └── utils.ts                       # Utility functions (cn, etc.)
├── hooks/                             # Custom React hooks
├── middleware.ts                      # Next.js middleware (auth guard)
├── supabase-schema.sql                # Complete database schema
├── next.config.mjs                    # Next.js configuration
├── tsconfig.json                      # TypeScript configuration
├── postcss.config.mjs                 # PostCSS configuration
├── package.json                       # Dependencies and scripts
└── pnpm-lock.yaml                     # pnpm lockfile (commit this!)

📡 API Reference

`POST /api/chat`

AI-powered study assistant. Requires authentication.

Request:

{
  "messages": [
    { "role": "user", "content": "How should I study for my math exam?" }
  ]
}

Response:

{
  "reply": "Here are some effective strategies for your math exam..."
}

`POST /api/generate-schedule`

Generates an AI-optimized study schedule for a given day. Requires authentication.

Request:

{
  "date": "2026-05-18",
  "preferences": {
    "studyHoursGoal": 4,
    "startTime": "09:00",
    "endTime": "18:00",
    "sessionLength": 45,
    "breakDuration": 15
  }
}

Response:

{
  "sessions": [
    {
      "id": "uuid",
      "title": "Linear Algebra - Matrix Operations",
      "subject_id": "uuid",
      "start_time": "2026-05-18T09:00:00.000Z",
      "end_time": "2026-05-18T09:45:00.000Z",
      "is_ai_generated": true
    }
  ],
  "reasoning": "Schedule explanation from AI..."
}

`POST /api/upload-syllabus`

Upload a PDF syllabus for a subject. Extracts text for AI context.

Request: multipart/form-data with file field

`POST /api/notes`

Upload and manage study notes with PDF text extraction.

🔧 Troubleshooting

Vercel Build: `ERR_PNPM_OUTDATED_LOCKFILE`

Cause: Dependencies were added to package.json without updating pnpm-lock.yaml.

Fix:

pnpm install
git add pnpm-lock.yaml
git commit -m "chore: sync pnpm lockfile"
git push

Vercel Build: Using wrong pnpm version

Cause: Vercel auto-selects pnpm version based on project creation date.

Fix: Pin the pnpm version via packageManager in package.json:

{
  "packageManager": "pnpm@9.15.0"
}

Or use Corepack:

corepack enable
corepack prepare pnpm@9.15.0 --activate

Auth Redirect Errors

Cause: Supabase redirect URLs not configured for your deployment domain.

Fix:

Go to Supabase Dashboard → Authentication → URL Configuration
Set Site URL to your production URL
Add your domain to Redirect URLs: https://your-app.vercel.app/auth/callback

AI Features Return 401

Cause: Missing or invalid GOOGLE_GENERATIVE_AI_API_KEY.

Fix:

Get a key from Google AI Studio
Add it to Vercel environment variables
Redeploy

AI Schedule Generation Fails

Cause: No subjects added, or Gemini API quota exceeded.

Fix:

Add at least one subject before generating schedules
Check Google AI Studio for quota/usage limits
The gemini-2.5-flash model has generous free-tier limits

Supabase RLS Errors (403)

Cause: Row Level Security policies are blocking access.

Fix:

Ensure you ran the complete supabase-schema.sql (includes all RLS policies)
Verify the user is authenticated before making requests
Check that user_id matches auth.uid() in your insert operations

🤝 Contributing

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Commit your changes: git commit -m 'feat: add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

📄 License

This project is open source and available under the MIT License.

Built with ❤️ by Prem Rajesh

Name		Name	Last commit message	Last commit date
Latest commit History 19 Commits
app		app
components		components
hooks		hooks
lib		lib
public		public
styles		styles
.env.local.example		.env.local.example
.gitignore		.gitignore
QUICK_START_EXAM_AWARE.md		QUICK_START_EXAM_AWARE.md
README.md		README.md
components.json		components.json
dummy_syllabus.pdf		dummy_syllabus.pdf
middleware.ts		middleware.ts
next-env.d.ts		next-env.d.ts
next.config.mjs		next.config.mjs
package-lock.json		package-lock.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
postcss.config.mjs		postcss.config.mjs
supabase-schema.sql		supabase-schema.sql
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

📚 StudyFlow

AI-Powered Study Planner & Productivity Platform

📋 Table of Contents

✨ Features

🛠 Tech Stack

Core Framework

Backend & Data

UI & Styling

Utilities

🏗 Architecture

Authentication Flow

📦 Prerequisites

🚀 Getting Started

1. Clone the Repository

2. Install Dependencies

3. Configure Environment Variables

4. Set Up the Database

5. Start the Development Server

🔑 Environment Variables

Where to Get These Values

🗄 Database Setup

Quick Setup

Schema Overview

Storage Buckets

Key Database Features

💻 Development

Available Scripts

Code Organization Conventions

🌐 Deployment

Deploy to Vercel (Recommended)

Option A: One-Click Deploy

Option B: CLI Deploy

Option C: Git Integration

Vercel Configuration

Required Environment Variables on Vercel

Post-Deployment Checklist

📁 Project Structure

📡 API Reference

POST /api/chat

POST /api/generate-schedule

POST /api/upload-syllabus

POST /api/notes

🔧 Troubleshooting

Vercel Build: ERR_PNPM_OUTDATED_LOCKFILE

Vercel Build: Using wrong pnpm version

Auth Redirect Errors

AI Features Return 401

AI Schedule Generation Fails

Supabase RLS Errors (403)

🤝 Contributing

📄 License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`POST /api/chat`

`POST /api/generate-schedule`

`POST /api/upload-syllabus`

`POST /api/notes`

Vercel Build: `ERR_PNPM_OUTDATED_LOCKFILE`

Packages