StudySync 🚀

AI-powered collaborative study tracker - A modern, sleek web application built with Next.js 14+ that helps students and study groups track progress, manage flashcards, build habits, and collaborate effectively.

✨ Features

🎯 Core Features

• 🔐 Authentication & RBAC - Google OAuth with role-based access control (OWNER/ADMIN/MEMBER)
• 👥 Group Management - Create/join study groups, invite by email, group selector
• 📚 Smart Flashcards - AI-powered spaced repetition with difficulty adjustment
• ⏰ Study Timer - Pomodoro-like timer with focus mode and fullscreen support
• 📊 Analytics Dashboard - Weekly study hours, streaks, task completion tracking
• 💬 Real-time Chat - Per-group chat with Socket.IO integration
• 🎯 Habit Tracker - Gamified habit building with streak tracking
• 🤖 AI Study Buddy - Intelligent study assistant with Cohere AI integration
• 💳 Stripe Billing - Free/Premium tiers with subscription management

🎨 UI/UX Features

• Modern Glassmorphism Design - Sleek, minimalist black/white theme
• Smooth Animations - Hover effects, transitions, and micro-interactions
• Responsive Design - Works perfectly on desktop, tablet, and mobile
• Keyboard Shortcuts - Quick navigation with Ctrl+1/2/3
• Fullscreen Mode - Distraction-free study environment
• Dynamic Backgrounds - Animated gradient elements

🛠️ Tech Stack

Frontend

• Next.js 14+ - App Router, Server Actions, TypeScript
• Tailwind CSS 4 - Utility-first styling with custom animations
• React Query - Data fetching and caching
• Socket.IO Client - Real-time communication
• Recharts - Data visualization

Backend

• Next.js API Routes - Server-side API endpoints
• NextAuth.js - Authentication with Google OAuth
• Prisma - Database ORM with PostgreSQL
• Zod - Runtime type validation
• Socket.IO - Real-time server with namespaces/rooms

Database & Services

• PostgreSQL - Primary database
• Stripe - Payment processing
• Cohere AI - AI study assistant
• SendGrid - Email invitations

Development & Deployment

• Docker - Containerization
• GitHub Actions - CI/CD pipeline
• Vitest - Unit testing
• Playwright - E2E testing
• ESLint & Prettier - Code quality
• Husky & lint-staged - Git hooks

🚀 Quick Start

Prerequisites

• Node.js 18+
• PostgreSQL 14+
• Git

Installation

1. Clone the repository

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

2. Install dependencies

npm install

3. Set up environment variables

cp .env.example .env.local

4. Configure environment variables

# Database
DATABASE_URL="postgresql://username:password@localhost:5432/studysync"

# NextAuth
NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET="your-secret-key"

# Google OAuth
GOOGLE_CLIENT_ID="your-google-client-id"
GOOGLE_CLIENT_SECRET="your-google-client-secret"

# AI Services
COHERE_API_KEY="your-cohere-api-key"
OPENAI_API_KEY="your-openai-api-key"

# Stripe
STRIPE_SECRET_KEY="your-stripe-secret-key"
STRIPE_PUBLISHABLE_KEY="your-stripe-publishable-key"
STRIPE_WEBHOOK_SECRET="your-stripe-webhook-secret"

# Email
SENDGRID_API_KEY="your-sendgrid-api-key"

5. Set up the database

npx prisma migrate dev
npx prisma db seed

6. Start the development server

npm run dev

7. Open your browser Navigate to http://localhost:3000

📁 Project Structure

studysync/
├── src/
│   ├── app/                    # Next.js App Router
│   │   ├── api/               # API routes
│   │   ├── dashboard/         # Dashboard pages
│   │   ├── groups/           # Group management
│   │   └── layout.tsx        # Root layout
│   ├── components/            # React components
│   │   ├── SmartFlashcards.tsx
│   │   ├── HabitTracker.tsx
│   │   ├── AIStudyBuddy.tsx
│   │   └── ...
│   ├── server/               # Server-side utilities
│   └── styles/               # Global styles
├── prisma/                   # Database schema & migrations
├── tests/                    # Test files
├── scripts/                  # Utility scripts
├── docker/                   # Docker configuration
├── .github/                  # GitHub Actions workflows
└── docs/                     # Documentation

🎯 Key Components

Smart Flashcards

• Spaced Repetition Algorithm - Intelligent review scheduling
• Difficulty Adjustment - Automatic difficulty based on performance
• Category Filtering - Organize cards by subject
• Progress Tracking - Visual progress bars and statistics

Habit Tracker

• Streak Tracking - Daily habit completion with streak counters
• Gamification - Progress bars and achievement system
• Flexible Habits - Add, edit, and delete habits
• Visual Feedback - Color-coded progress indicators

AI Study Buddy

• Cohere AI Integration - Intelligent responses to study questions
• Context Awareness - Understands study-related queries
• Real-time Chat - Instant AI assistance
• Study Tips - Personalized learning recommendations

Group Management

• Role-based Access - OWNER/ADMIN/MEMBER permissions
• Email Invitations - Invite members via email
• Real-time Chat - Group communication
• Progress Sharing - Collaborative study tracking

🔧 Development

Available Scripts

npm run dev          # Start development server
npm run build        # Build for production
npm run start        # Start production server
npm run lint         # Run ESLint
npm run lint:fix     # Fix ESLint issues
npm run format       # Format code with Prettier
npm run test         # Run unit tests
npm run test:e2e     # Run E2E tests
npm run db:reset     # Reset database
npm run db:seed      # Seed database

Database Operations

npx prisma studio           # Open Prisma Studio
npx prisma migrate dev      # Run migrations
npx prisma generate         # Generate Prisma client
npx prisma db push          # Push schema changes

Testing

npm run test                # Unit tests with Vitest
npm run test:e2e            # E2E tests with Playwright
npm run test:coverage       # Test coverage report

🚀 Deployment

Docker Deployment

# Build Docker image
docker build -t studysync .

# Run with docker-compose
docker-compose up -d

Vercel Deployment

1. Connect your GitHub repository to Vercel
2. Set environment variables in Vercel dashboard
3. Deploy automatically on push to main branch

Environment Variables for Production

Ensure all required environment variables are set in your production environment:

• Database connection string
• Authentication secrets
• API keys for external services
• Stripe webhook endpoints

📊 API Documentation

Authentication Endpoints

• POST /api/auth/signin/google - Google OAuth sign-in
• GET /api/auth/session - Get current session
• POST /api/auth/signout - Sign out

Study Management

• GET /api/dashboard/stats - Get dashboard statistics
• POST /api/groups - Create new study group
• GET /api/groups/[id] - Get group details
• POST /api/groups/[id]/invite - Invite member to group

AI Services

• POST /api/ai/huggingface - AI study assistant (Cohere)
• POST /api/ai/chat - OpenAI chat completion

Stripe Integration

• POST /api/stripe/checkout - Create checkout session
• POST /api/stripe/portal - Create customer portal
• POST /api/stripe/webhook - Handle Stripe webhooks

🧪 Testing

Unit Tests

npm run test

Tests are written with Vitest and cover:

• Component rendering
• State management
• API endpoints
• Utility functions

E2E Tests

npm run test:e2e

End-to-end tests cover:

• User authentication flow
• Study group creation
• Flashcard interactions
• Payment flows

🔒 Security

• Session Protection - Secure session management with NextAuth
• Role-based Access Control - Granular permissions system
• Input Validation - Zod schema validation on all inputs
• Rate Limiting - API rate limiting for security
• CORS Configuration - Proper cross-origin resource sharing
• Environment Variables - Secure secret management

🤝 Contributing

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

Development Guidelines

• Follow TypeScript best practices
• Write tests for new features
• Update documentation as needed
• Follow the existing code style
• Ensure all tests pass before submitting

📈 Roadmap

Phase 1 (Current)

• ✅ Core study tracking features
• ✅ AI study assistant
• ✅ Group management
• ✅ Payment integration

Phase 2 (Planned)

• 🔄 Mobile app (React Native)
• 🔄 Advanced analytics
• 🔄 Study room scheduling
• 🔄 Integration with calendar apps

Phase 3 (Future)

• 🔄 Machine learning recommendations
• 🔄 Video study sessions
• 🔄 Study material sharing
• 🔄 Advanced collaboration tools

🐛 Troubleshooting

Common Issues

Database Connection Issues

# Check if PostgreSQL is running
pg_ctl status

# Reset database
npm run db:reset

Authentication Issues

• Verify Google OAuth credentials
• Check NEXTAUTH_URL matches your domain
• Ensure NEXTAUTH_SECRET is set

Build Issues

# Clear Next.js cache
rm -rf .next

# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

📄 License

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

🙏 Acknowledgments

• Next.js Team - For the amazing framework
• Tailwind CSS - For the utility-first CSS framework
• Prisma - For the excellent database toolkit
• Cohere - For AI capabilities
• Stripe - For payment processing

📞 Support

• 📧 Email: sivanp515@gmail.com
• 📖 Documentation: docs.studysync.app
• 🐛 Issues: GitHub Issues

---

Built with ❤️ by the StudySync Team

Empowering students to study smarter, not harder.