StudyFlow 📚

A collaborative virtual study platform that brings students together to learn, focus, and grow. Join themed study rooms, use synchronized Pomodoro timers, chat with fellow students, interact with AI study companions, and track your progress through gamification.

✨ Features

🏠 Virtual Study Rooms

Create or join themed study rooms (Cozy Library, Rainy Night, Forest, Coffee Shop, etc.)
Room capacity management (up to 8 users per room)
Real-time participant tracking
Browse available rooms with live participant counts

⏱️ Synchronized Pomodoro Timer

Room-wide synchronized study/break sessions
Customizable study (25 min) and break (5 min) durations
Automatic session switching
Session completion tracking for achievements

💬 Real-time Chat

In-room chat with fellow students
Real-time message synchronization
AI study buddies that send motivational messages
Chat history per room

🎮 Gamification System

Experience points (XP) and leveling
10 unique achievements to unlock
Track focus time, streaks, and sessions
Global leaderboard
User statistics dashboard

🎵 Music & Ambient Sounds

7 audio options: Lo-fi, Classical, Rain, Forest, Café, White Noise, Silence
Advanced music player with controls
Theme-specific ambient soundscapes

🔐 Authentication

Email/password authentication
Google OAuth
GitHub OAuth
Discord OAuth
Secure profile management

🤖 AI Study Companions

AI students that join study rooms
Motivational messages every 2 minutes
Simulated study buddies for engagement

👤 User Profiles

Personal stats (focus time, streaks, level, XP)
Achievement showcase
Study session history
Customizable avatars

🚀 Quick Start

Prerequisites

Node.js 18+ installed
A Supabase account (free tier works!)
Git installed

Installation

Clone the repository

git clone https://github.com/yourusername/studyflow.git
cd studyflow

Install dependencies
```
npm install
```
Set up Supabase

Follow the complete guide: SUPABASE_SETUP.md

Quick version:
- Create a Supabase project at supabase.com
- Run all 7 database migrations
- Configure authentication providers

Configure environment variables

cp .env.example .env

Edit .env and add your Supabase credentials:

VITE_SUPABASE_URL=https://your-project-id.supabase.co
VITE_SUPABASE_ANON_KEY=your-anon-key-here
VITE_APP_URL=http://localhost:5173

Start the development server
```
npm run dev
```
Open http://localhost:5173 in your browser.

📖 Documentation

Document	Description
SUPABASE_SETUP.md	Complete Supabase setup guide with step-by-step instructions
DEPLOYMENT.md	Deploy to production (Vercel, Netlify) with custom domains
TROUBLESHOOTING.md	Solutions to common issues and error messages

🛠️ Tech Stack

Frontend

⚛️ React 18.3.1 - UI library
📘 TypeScript 5.5.3 - Type safety
⚡ Vite 5.4.2 - Build tool & dev server
🎨 Tailwind CSS 3.4.1 - Styling
🎭 Lucide React - Icon library

Backend & Database

🗄️ Supabase 2.57.4 - PostgreSQL database, authentication, real-time
🔒 Row Level Security (RLS) - Database security
📡 Supabase Real-time - WebSocket subscriptions
⚡ Edge Functions - Serverless functions for AI features

State Management

⚛️ React Context API - Global state
🪝 Custom Hooks - Business logic encapsulation

📁 Project Structure

studyflow/
├── src/
│   ├── components/          # React components
│   │   ├── Audio/          # Music & ambient sounds
│   │   ├── Auth/           # Authentication components
│   │   ├── Layout/         # Header and layout
│   │   ├── StudyRoom/      # Study room components
│   │   └── UI/             # Reusable UI components
│   ├── context/            # React Context (AppContext)
│   ├── hooks/              # Custom React hooks
│   ├── lib/                # Service layer
│   │   ├── auth.ts         # Authentication service
│   │   ├── roomService.ts  # Room operations
│   │   ├── chatService.ts  # Chat functionality
│   │   ├── profileService.ts # User profiles
│   │   └── aiStudentService.ts # AI companions
│   ├── pages/              # Page components
│   ├── types/              # TypeScript definitions
│   ├── utils/              # Helper functions
│   ├── App.tsx             # Main app component
│   └── main.tsx            # Entry point
├── supabase/
│   ├── migrations/         # Database schema migrations (7 files)
│   └── functions/          # Edge Functions (AI, cleanup)
├── public/                 # Static assets
├── .env.example            # Environment variable template
├── vercel.json            # Vercel deployment config
└── vite.config.ts         # Vite configuration

🗄️ Database Schema

Core Tables:

profiles - User profiles with stats and progression
study_rooms - Room metadata and timer state
room_participants - Room membership tracking
chat_messages - Chat history
achievements - Achievement definitions (10 default)
user_achievements - Earned achievements
study_sessions - Study session tracking
user_settings - User preferences
ai_students - AI companions

Key Features:

Row Level Security (RLS) on all tables
5 stored procedures for atomic operations
Auto-cleanup triggers for empty rooms
Presence management with 2-minute timeout

See SUPABASE_SETUP.md for migration details.

🚢 Deployment

Deploy StudyFlow to production in minutes!

Deploy to Vercel (Recommended)

Push your code to GitHub
Sign up at vercel.com with GitHub
Import your repository
Add environment variables:
- VITE_SUPABASE_URL
- VITE_SUPABASE_ANON_KEY
- VITE_APP_URL
Deploy!

Complete guide: DEPLOYMENT.md

Other Platforms

StudyFlow also works great on:

Netlify
Render
Railway
Cloudflare Pages

See deployment guide for platform-specific instructions.

🎯 Usage

Creating a Study Room

Sign up or log in
Click "Create Room"
Choose a theme (Cozy Library, Rainy Night, etc.)
Set study/break durations
Select ambient music
Start studying!

Joining a Room

Browse available rooms on the home page
Click "Join" on any room with available space
Automatically join the synchronized timer
Chat with other participants
Earn XP and achievements

Earning Achievements

First Steps: Join your first study room
Social Butterfly: Join 5 different rooms
Focus Master: Complete 10 study sessions
Night Owl: Study for 100 minutes total
Marathon Runner: Complete a 50-minute session
Streak Starter: Maintain a 3-day streak
... and 4 more!

🤝 Contributing

Contributions are welcome! Here's how:

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

Development Guidelines

Follow TypeScript best practices
Use ESLint and Prettier for code formatting
Write meaningful commit messages
Test your changes locally before submitting

📝 Scripts

# Development
npm run dev          # Start dev server at localhost:5173

# Build
npm run build        # Build for production (outputs to dist/)
npm run preview      # Preview production build locally

# Linting
npm run lint         # Run ESLint

🐛 Troubleshooting

Having issues? Check out our comprehensive troubleshooting guide:

👉 TROUBLESHOOTING.md

Common issues:

Authentication errors → Solutions
Database errors → Solutions
Deployment issues → Solutions

📊 Free Tier Limits

Vercel Free Tier:

✅ Unlimited personal projects
✅ 100GB bandwidth/month
✅ Automatic SSL & global CDN

Supabase Free Tier:

✅ 500MB database storage
✅ 1GB file storage
✅ 50,000 monthly active users
⚠️ Projects pause after 1 week of inactivity

Perfect for getting started! Upgrade when you need more.

🔒 Security

All database tables protected by Row Level Security (RLS)
OAuth providers use industry-standard authentication
Environment variables for sensitive data
HTTPS enforced in production
XSS and CSRF protection via security headers

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Supabase - Backend infrastructure
Vercel - Hosting platform
Lucide Icons - Beautiful icons
Tailwind CSS - Styling framework

📞 Support

Need help?

⭐ Show Your Support

If you found StudyFlow helpful, please consider giving it a star on GitHub!

Built with ❤️ for students who want to study better together

Start your focused study session today! 🚀

Name		Name	Last commit message	Last commit date
Latest commit History 25 Commits
.bolt		.bolt
src		src
supabase		supabase
.env.example		.env.example
.gitignore		.gitignore
COMPLETE_MIGRATION.sql		COMPLETE_MIGRATION.sql
DEPLOYMENT.md		DEPLOYMENT.md
README.md		README.md
SUPABASE_SETUP.md		SUPABASE_SETUP.md
TROUBLESHOOTING.md		TROUBLESHOOTING.md
eslint.config.js		eslint.config.js
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
tailwind.config.js		tailwind.config.js
tsconfig.app.json		tsconfig.app.json
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
tsconfig.tsbuildinfo		tsconfig.tsbuildinfo
vercel.json		vercel.json
vite.config.ts		vite.config.ts

byessilyurt/studyflow

Folders and files

Latest commit

History

Repository files navigation