LearnDash - Learning Management System

📖 Table of Contents

• Overview
• Features
• Tech Stack
• Quick Start
• Project Structure
• Architecture
• Documentation
• Environment Setup
• Development
• API Reference
• Deployment
• Contributing
• License

🌟 Overview

LearnDash is a modern, AI-powered learning management system built with Next.js 15 and TypeScript. It features a beautiful glassmorphism design with a cosmic theme, comprehensive quiz management, AI-integrated timetable generation, and real-time progress tracking.

The platform is designed to provide an engaging learning experience with features such as:

• AI-generated quizzes with detailed explanations
• Dynamic timetable creation using Google's Gemini AI
• Comprehensive performance analytics
• Beautiful, responsive design with glassmorphism effects
• Full-stack authentication with Supabase

✨ Features

🎯 Core Features

• Authentication System: Complete user authentication with Supabase
• AI-Powered Quizzer: Generate quizzes with multiple subjects and difficulties
• Smart Timetable: AI-generated timetables based on user preferences
• Interactive Dashboard: Track progress, view stats, and manage learning
• Performance Analytics: Detailed insights into learning progress
• Mistake Review: Review incorrect answers with explanations

🎨 Design Features

• Glassmorphism UI: Modern glass-like design elements
• Cosmic Theme: Dark theme with purple/magenta accents
• Responsive Design: Mobile-first, works on all devices
• Smooth Animations: 60fps animations with GPU acceleration
• Component Library: Reusable shadcn/ui components

🔧 Technical Features

• Type Safety: Full TypeScript implementation
• Server-Side Rendering: Next.js App Router with SSR
• Database: PostgreSQL with Supabase
• API Integration: RESTful APIs with proper error handling
• State Management: React hooks and context
• Security: Row-level security and JWT authentication

🛠️ Tech Stack

Frontend

• Framework: Next.js 15.5.4 (App Router)
• Language: TypeScript 5.0
• Styling: Tailwind CSS v4
• UI Components: shadcn/ui
• Icons: Lucide React
• Forms: React Hook Form + Zod validation

Backend & Database

• Database: PostgreSQL (via Supabase)
• Authentication: Supabase Auth
• API: Next.js API Routes
• ORM: Supabase JavaScript Client
• Real-time: Supabase Realtime (planned)

AI & External Services

• AI Model: Google Gemini 2.0 Flash
• Quiz Generation: Custom prompt engineering
• Timetable AI: Conversational AI interface

Development Tools

• Package Manager: npm
• Linting: ESLint + Prettier
• Type Checking: TypeScript compiler
• Git Hooks: Husky (planned)

🚀 Quick Start

Prerequisites

• Node.js 18.0 or higher
• npm or yarn
• Git
• Supabase account
• Google Gemini API key

Installation

1. Clone the repository

   git clone <repository-url>
   cd learning-app

2. Install dependencies

   npm install

3. Set up environment variables

   cp .env.example .env.local

   Configure your environment variables (see Environment Setup)

4. Set up the database

   • Create a new Supabase project
   • Run the migration scripts from supabase/migrations/
   • Configure auth settings

5. Start the development server

   npm run dev

6. Open your browser Navigate to http://localhost:3001

📁 Project Structure

learning-app/
├── src/                          # Source code
│   ├── app/                      # Next.js App Router pages
│   │   ├── (marketing)/          # Marketing routes group
│   │   ├── api/                  # API routes
│   │   │   ├── ai/              # AI integration endpoints
│   │   │   └── quiz/            # Quiz system endpoints
│   │   ├── auth/                # Authentication page
│   │   ├── dashboard/           # Dashboard page
│   │   ├── quiz/                # Quiz taking page
│   │   ├── quizzer/             # Quiz configuration page
│   │   ├── timetable/           # Timetable page with AI
│   │   ├── globals.css          # Global styles
│   │   ├── layout.tsx           # Root layout
│   │   └── page.tsx             # Home page
│   ├── components/              # React components
│   │   ├── auth/               # Authentication components
│   │   ├── layout/             # Layout components
│   │   └── ui/                 # Reusable UI components
│   ├── lib/                    # Utility libraries
│   │   ├── supabase/           # Supabase client configuration
│   │   └── theme.ts            # Theme system
│   ├── services/               # Business logic services
│   │   └── quizSessionService.ts
│   └── types/                  # TypeScript type definitions
├── docs/                      # Documentation (this guide)
├── supabase/                  # Database migrations
│   └── migrations/           # SQL migration files
├── todotasks/               # Project documentation
└── public/                  # Static assets

🏗️ Architecture

High-Level Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Frontend      │    │   Backend       │    │   External      │
│   (Next.js)     │◄──►│   (API Routes)  │◄──►│   Services      │
│                 │    │                 │    │                 │
│ • Pages         │    │ • Quiz API      │    │ • Supabase      │
│ • Components    │    │ • Auth API      │    │ • Gemini AI     │
│ • Hooks         │    │ • AI API        │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                    ┌─────────────────┐
                    │   Database      │
                    │   (Supabase)    │
                    │                 │
                    │ • Users         │
                    │ • Quiz Data     │
                    │ • Sessions      │
                    └─────────────────┘

Key Architectural Decisions

1. App Router over Pages Router: Leverages Next.js 15's latest features
2. Server Components: Improved performance and SEO
3. Supabase for Backend: Rapid development with built-in auth
4. Modular Theme System: Easy customization without hardcoded values
5. TypeScript Everywhere: Type safety across the stack

📚 Documentation

Our documentation is organized to help you find exactly what you need:

For New Developers

• Getting Started Guide
• Development Workflow
• Environment Setup

Understanding the System

• Architecture Overview
• Design System
• Database Schema

Feature Documentation

• Authentication System
• Quiz System
• Timetable AI
• Dashboard

API Documentation

• API Overview
• Authentication Endpoints
• Quiz API
• AI Integration

Deployment

• Production Setup
• Supabase Configuration
• Environment Variables

⚙️ Environment Setup

Required Environment Variables

Create a .env.local file in the root directory:

# Supabase Configuration
NEXT_PUBLIC_SUPABASE_URL=your_supabase_project_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key

# Google Gemini AI
GEMINI_API_KEY=your_gemini_api_key

# App Configuration
NEXT_PUBLIC_APP_URL=http://localhost:3001
NODE_ENV=development

Supabase Setup

1. Create a new project at supabase.com
2. Get your credentials from Settings > API
3. Configure Authentication:
   • Enable Email/Password authentication
   • Add your site URL to redirects
4. Run migrations from the supabase/migrations/ folder

Gemini API Setup

1. Get API key from Google AI Studio
2. Enable Gemini API in your Google Cloud Console
3. Add the key to your environment variables

💻 Development

Available Scripts

# Start development server
npm run dev

# Build for production
npm run build

# Start production server
npm start

# Run linter
npm run lint

# Type checking
npm run type-check

Development Workflow

1. Create a feature branch

   git checkout -b feature/your-feature-name

2. Make your changes

   • Follow the code style guidelines
   • Add TypeScript types
   • Import colors from theme system

3. Test your changes

   • Run the linter
   • Check for TypeScript errors
   • Test in the browser

4. Commit your changes

   git add .
   git commit -m "feat: add your feature"

5. Push and create a pull request

Code Style Guidelines

• TypeScript: Use strict mode, provide types for all variables
• Tailwind: Use theme colors, no hardcoded values
• Components: Follow atomic design principles
• Files: Use PascalCase for components, camelCase for utilities

🔌 API Reference

Authentication Endpoints

Method	Endpoint	Description
POST	/api/auth/signin	Sign in user
POST	/api/auth/signup	Register new user
POST	/api/auth/signout	Sign out user

Quiz Endpoints

Method	Endpoint	Description
POST	/api/quiz/session	Create quiz session
GET	/api/quiz/session/[id]	Get session details
POST	/api/quiz/questions	Save quiz questions
POST	/api/quiz/answers	Save user answers
GET	/api/quiz/history	Get quiz history
GET	/api/quiz/stats	Get performance stats

AI Endpoints

Method	Endpoint	Description
POST	/api/ai/quiz	Generate quiz questions
POST	/api/ai/timetable	Generate timetable

For detailed API documentation, see API Overview.

🚀 Deployment

Production Deployment Checklist

1. Environment Variables

   • Set all required environment variables
   • Use production URLs
   • Secure your API keys

2. Database Setup

   • Run all migrations
   • Configure Row Level Security
   • Set up connection pooling

3. Build Process

   • Run npm run build
   • Check for build errors
   • Test production build locally

4. Deploy

   • Choose your hosting platform
   • Configure custom domains
   • Set up SSL certificates

Recommended Platforms

• Vercel: Seamless Next.js deployment
• Netlify: Simple static hosting
• AWS: Full control and scalability
• DigitalOcean: Affordable VPS hosting

🤝 Contributing

We welcome contributions! Please follow these steps:

1. Read the contributing guide (Contributing Guide)
2. Fork the repository
3. Create a feature branch
4. Make your changes
5. Add tests if applicable
6. Update documentation
7. Submit a pull request

Contribution Areas

• 🐛 Bug fixes
• ✨ New features
• 📝 Documentation improvements
• 🎨 UI/UX enhancements
• ⚡ Performance optimizations
• 🧪 Test coverage

📞 Support

• Documentation: Read the docs
• Issues: Create an issue
• Discussions: Join the discussion
• Email: support@learndash.com

📄 License

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

🙏 Acknowledgments

• Next.js - The React framework
• Supabase - Backend as a service
• Tailwind CSS - CSS framework
• shadcn/ui - Component library
• Google Gemini - AI model
• Lucide - Icon library

---

Made with ❤️ by the LearnDash team