EduBridge 🌉

Learn Anywhere. Anytime. Together.

EduBridge is a modern, offline-first learning platform that bridges the educational gap between rural and urban students. Built with cutting-edge technologies, it provides equal access to quality education through AI-powered tutoring, interactive content, gamified learning, and robust community features.

🚀 Live Demo | 🐛 Report Bug

✨ Features

🎓 Core Learning Platform

Course Management: Create, publish, and manage comprehensive courses
Multi-format Content: Support for text, videos (YouTube/uploads), and external links
Progress Tracking: Real-time learning progress with completion percentages
Offline Support: PWA with offline capabilities for uninterrupted learning

🤖 AI-Powered Learning

AI Tutor: Personalized tutoring powered by Google Generative AI and OpenAI
Custom Quiz Generation: AI-generated quizzes based on course content
Adaptive Learning: Personalized learning paths based on student progress

🎮 Gamification & Engagement

Points & Achievements: Earn points and unlock achievements
Streak System: Maintain learning streaks for consistent progress
Leaderboards: Compete with peers and track progress
Level System: Progress through different learning levels

👥 Community Features

Discussion Forums: Course-specific and general discussion threads
Announcements: Teachers can broadcast updates to students
Social Learning: Like, reply, and engage with community content

🔐 Authentication & Roles

NextAuth Integration: Secure authentication with multiple providers
Role-based Access: Separate dashboards for students and teachers
Protected Routes: Middleware-based route protection

🛠️ Tech Stack

Frontend

Next.js 16 - React framework with App Router
TypeScript - Type-safe development
Tailwind CSS - Utility-first styling
Radix UI - Accessible component primitives
Framer Motion - Smooth animations
React Hook Form + Zod - Form management

Backend & Database

Prisma - Type-safe database ORM
PostgreSQL - Primary database (Neon)
NextAuth.js - Authentication system
Upstash Redis - Caching and session storage

AI & External Services

Groq SDK - Fast AI inference
Cloudinary - Media management

PWA & Performance

Workbox - Service worker functionality
Dexie - IndexedDB wrapper for offline data

🚀 Quick Start

Prerequisites

Ensure you have the following installed:

Node.js 20+ (Download)
pnpm (Install guide)
PostgreSQL database or Neon account
Cloudinary account for media storage

One-Click Setup

# Clone and setup
git clone <repository-url>
cd edubridge
pnpm install

# Setup environment (copy and configure)
cp .env.example .env

# Initialize database
pnpm prisma generate
pnpm prisma db push

# Start development
pnpm dev

Environment Configuration

Create a .env file in the root directory:

# Database (Required)
DATABASE_URL="postgresql://username:password@localhost:5432/edubridge"

# NextAuth (Required)
NEXTAUTH_SECRET="your-super-secret-key-here"
NEXTAUTH_URL="http://localhost:3000"

# OAuth Providers (Required for social login)
GITHUB_ID="your-github-oauth-app-id"
GITHUB_SECRET="your-github-oauth-app-secret"
GOOGLE_ID="your-google-oauth-client-id"
GOOGLE_SECRET="your-google-oauth-client-secret"

# AI Services (Required for AI features)
GROQ_API_KEY="your-groq-api-key"

# Cloudinary (Required for media uploads)
NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME="your-cloud-name"
CLOUDINARY_API_KEY="your-api-key"
CLOUDINARY_API_SECRET="your-api-secret"

# Redis (Optional - for caching)
UPSTASH_REDIS_REST_URL="your-redis-url"
UPSTASH_REDIS_REST_TOKEN="your-redis-token"

🔧 Detailed Setup Instructions

Database Setup Options

Option 1: Local PostgreSQL

# Install PostgreSQL locally
# Create database
createdb edubridge

Option 2: Neon (Recommended)

Sign up at neon.tech
Create a new project
Copy the connection string to DATABASE_URL

OAuth Providers Setup

GitHub OAuth App

Go to GitHub Developer Settings
Click "New OAuth App"
Set Authorization callback URL to: http://localhost:3000/api/auth/callback/github
Copy Client ID to GITHUB_ID
Generate and copy Client Secret to GITHUB_SECRET

Google OAuth App

Go to Google Cloud Console
Create a new project or select existing one
Enable Google+ API
Go to "Credentials" → "Create Credentials" → "OAuth 2.0 Client IDs"
Set Authorized redirect URI to: http://localhost:3000/api/auth/callback/google
Copy Client ID to GOOGLE_ID
Copy Client Secret to GOOGLE_SECRET

AI Service Setup

Groq (Primary AI Provider)

Sign up at groq.com
Generate API key
Add to GROQ_API_KEY

Media Storage Setup

Cloudinary

Sign up at cloudinary.com
Get your cloud name, API key, and secret
Add to respective environment variables

Verify Installation

# Check if everything is working
pnpm run lint          # Should pass without errors
pnpm run build         # Should build successfully

Open http://localhost:3000 to see your application running! 🎉

📱 PWA Installation

EduBridge works as a Progressive Web App:

Desktop: Click the install button in your browser's address bar
Mobile: Use "Add to Home Screen" from your browser menu
Offline: Access courses and content even without internet connection

🏗️ Project Structure

📁 Detailed Project Structure

edubridge/
├── 📁 app/                     # Next.js App Router (main application)
│   ├── 📁 actions/            # Server actions for data mutations
│   ├── 📁 api/                # REST API endpoints
│   │   ├── auth/              # Authentication endpoints
│   │   ├── courses/           # Course management API
│   │   ├── ai/                # AI-powered features API
│   │   └── gamification/      # Points and achievements API
│   ├── 📁 ai-tutor/           # AI tutoring chat interface
│   ├── 📁 announcements/      # Teacher announcements system
│   ├── 📁 community-forum/    # Discussion forums
│   ├── 📁 course-player/      # Interactive course content player
│   ├── 📁 courses/            # Course catalog and browsing
│   ├── 📁 create-course/      # Course creation wizard
│   ├── 📁 login/ & signup/    # Authentication pages
│   ├── 📁 onboarding/         # User role selection flow
│   ├── 📁 quiz/               # Interactive quiz system
│   ├── 📁 student*/           # Student dashboard and features
│   ├── 📁 teacher*/           # Teacher dashboard and tools
│   └── 📁 manage-course/      # Course management interface
├── 📁 components/             # Reusable React components
│   ├── 📁 gamification/       # Achievement badges, progress bars
│   ├── 📁 quiz/               # Quiz components and logic
│   ├── 📁 revision/           # AI-powered revision tools
│   └── 📁 ui/                 # Base UI components (Radix UI)
├── 📁 hooks/                  # Custom React hooks
│   ├── use-gamification.ts    # Points, streaks, achievements
│   ├── use-offline-*.ts       # PWA offline functionality
│   └── use-mobile.ts          # Mobile-responsive utilities
├── 📁 lib/                    # Core utilities and configurations
│   ├── aiClient.ts            # AI service integrations (Groq, OpenAI)
│   ├── auth.ts                # NextAuth.js configuration
│   ├── cloudinary.ts          # Media upload and management
│   ├── gamification.ts        # Gamification logic and calculations
│   ├── offline-*.ts           # Offline data synchronization
│   ├── prisma.ts              # Database client configuration
│   └── utils.ts               # General utility functions
├── 📁 prisma/                 # Database layer
│   ├── 📁 migrations/         # Database migration history
│   ├── schema.prisma          # Database schema (PostgreSQL)
│   └── seed.ts                # Sample data seeding
├── 📁 public/                 # Static assets
│   ├── 📁 icons/              # PWA icons (various sizes)
│   ├── manifest.json          # PWA manifest configuration
│   ├── sw.js                  # Service worker for offline support
│   └── 📁 images/             # Static images and placeholders
├── 📁 styles/                 # Global CSS and Tailwind config
├── 📄 middleware.ts           # Route protection and auth middleware
├── 📄 next.config.mjs         # Next.js configuration
├── 📄 tailwind.config.js      # Tailwind CSS configuration
└── 📄 tsconfig.json           # TypeScript configuration

Key Directories Explained

Directory	Purpose
`app/`	Next.js 13+ App Router - all pages and API routes
`components/`	Reusable UI components organized by feature
`lib/`	Core business logic, utilities, and configurations
`prisma/`	Database schema, migrations, and seeding
`hooks/`	Custom React hooks for shared logic
`public/`	Static assets, PWA files, and images

🎯 Key Features Deep Dive

Course Management

Rich Content Editor: Support for multiple content types
Video Integration: Upload to Cloudinary or embed YouTube videos
Progress Tracking: Automatic progress calculation and completion tracking
Enrollment System: Manage student enrollments and access

AI Tutoring

Contextual Help: AI understands course content and student progress
AI Provider: Fallback system with Groq
Personalized Responses: Tailored explanations based on learning level

Gamification System

Achievement Types: First lesson, streak milestones, quiz mastery
Point System: Earn points for completing lessons and quizzes
Streak Tracking: Daily activity streaks with longest streak records
Level Progression: Advance through levels based on total points

🔧 Available Scripts

Command	Description
`pnpm dev`	Start development server with hot reload
`pnpm build`	Build optimized production bundle
`pnpm start`	Start production server
`pnpm lint`	Run ESLint for code quality checks
`pnpm prisma generate`	Generate Prisma client
`pnpm prisma db push`	Push schema changes to database
`pnpm prisma studio`	Open Prisma Studio (database GUI)
`pnpm prisma migrate dev`	Create and apply new migration

Development Workflow

# Daily development
pnpm dev                    # Start development server

# Database changes
pnpm prisma db push         # Quick schema updates
pnpm prisma migrate dev     # Create proper migrations

# Code quality
pnpm lint                   # Check for linting issues
pnpm build                  # Verify production build

📚 API Documentation

EduBridge provides a comprehensive REST API for all platform features:

Authentication Endpoints

POST /api/auth/signin - User authentication
POST /api/auth/signup - User registration
GET /api/auth/session - Get current session

Course Management

GET /api/courses - List all courses
POST /api/courses - Create new course
GET /api/courses/[id] - Get course details
PUT /api/courses/[id] - Update course
DELETE /api/courses/[id] - Delete course

Learning & Progress

POST /api/progress - Update learning progress
GET /api/progress/[userId] - Get user progress
POST /api/quiz/attempt - Submit quiz attempt
GET /api/gamification/achievements - Get user achievements

AI Features

POST /api/ai/tutor - AI tutoring chat
POST /api/ai/quiz-generate - Generate AI quiz
POST /api/ai/revision - AI-powered revision

🔒 Security Features

Authentication: Secure NextAuth.js implementation
Authorization: Role-based access control (Student/Teacher)
Data Protection: Input validation with Zod schemas
CSRF Protection: Built-in Next.js CSRF protection
Rate Limiting: API rate limiting for abuse prevention
Secure Headers: Security headers configured

🔧 Troubleshooting

Common Issues and Solutions

Database Connection Issues

# Check if DATABASE_URL is correct
echo $DATABASE_URL

# Reset database connection
pnpm prisma db push --force-reset
pnpm prisma generate

Build Errors

# Clear Next.js cache
rm -rf .next

# Clear node_modules and reinstall
rm -rf node_modules pnpm-lock.yaml
pnpm install

# Check TypeScript errors
pnpm tsc --noEmit

Environment Variables Not Loading

# Ensure .env is in root directory
ls -la .env

# Restart development server after .env changes
pnpm dev

AI Features Not Working

Verify API keys are set correctly in .env
Check API key permissions and quotas
Ensure network connectivity to AI services

PWA Not Installing

Check if running on HTTPS (required for PWA)
Verify manifest.json is accessible
Clear browser cache and try again

Getting Help

If you encounter issues:

Check the logs - Look at browser console and terminal output
Search existing issues - Check GitHub Issues
Create a new issue - Provide detailed error messages and steps to reproduce
Join our community - Get help from other developers

🌐 Deployment

Live Application: https://edu-bridge-lac.vercel.app/

Deploy to Vercel (Recommended)

Manual Vercel Setup:

Fork this repository
Connect to Vercel
Import your forked repository
Configure environment variables in Vercel dashboard
Deploy automatically on push to main branch

Alternative Deployment Options

Docker Deployment

# Dockerfile (create this file)
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build
EXPOSE 3000
CMD ["npm", "start"]

# Build and run
docker build -t edubridge .
docker run -p 3000:3000 edubridge

Manual Server Deployment

# On your server
git clone <your-repo>
cd edubridge
pnpm install
pnpm build

# Set up environment variables
# Configure reverse proxy (nginx/apache)
# Set up process manager (PM2)
pm2 start npm --name "edubridge" -- start

Environment Variables for Production

Ensure these are set in your production environment:

All variables from .env example
NEXTAUTH_URL should be your production domain
Database should be production-ready (not local)

🤝 Contributing

We welcome contributions!

Quick Contribution Steps

Fork the repository
Clone your fork: git clone <your-fork-url>
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes and test them
Commit with clear messages: git commit -m 'Add amazing feature'
Push to your branch: git push origin feature/amazing-feature
Open a Pull Request with a clear description

Development Guidelines

Follow the existing code style and conventions
Write meaningful commit messages
Add tests for new features when applicable
Update documentation as needed
Ensure CI passes before submitting PR

Areas for Contribution

🐛 Bug fixes and improvements
✨ New features and enhancements
📚 Documentation improvements
🎨 UI/UX enhancements
🔧 Performance optimizations
🌐 Internationalization (i18n)

Name		Name	Last commit message	Last commit date
Latest commit History 49 Commits
.github/workflows		.github/workflows
.vscode		.vscode
app		app
components		components
hooks		hooks
lib		lib
prisma		prisma
public		public
scripts		scripts
styles		styles
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.prettierrc		.prettierrc
README.md		README.md
components.json		components.json
eslint.config.mjs		eslint.config.mjs
middleware.ts		middleware.ts
next.config.mjs		next.config.mjs
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
postcss.config.mjs		postcss.config.mjs
tsconfig.json		tsconfig.json
vercel.json		vercel.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

EduBridge 🌉

📋 Table of Contents

✨ Features

🎓 Core Learning Platform

🤖 AI-Powered Learning

🎮 Gamification & Engagement

👥 Community Features

🔐 Authentication & Roles

🛠️ Tech Stack

🚀 Quick Start

Prerequisites

One-Click Setup

Environment Configuration

Database Setup Options

OAuth Providers Setup

AI Service Setup

Media Storage Setup

Verify Installation

📱 PWA Installation

🏗️ Project Structure

Key Directories Explained

🎯 Key Features Deep Dive

Course Management

AI Tutoring

Gamification System

🔧 Available Scripts

Development Workflow

📚 API Documentation

Authentication Endpoints

Course Management

Learning & Progress

AI Features

🔒 Security Features

🔧 Troubleshooting

Database Connection Issues

Build Errors

Environment Variables Not Loading

AI Features Not Working

PWA Not Installing

Getting Help

🌐 Deployment

Deploy to Vercel (Recommended)

Alternative Deployment Options

Environment Variables for Production

🤝 Contributing

Quick Contribution Steps

Development Guidelines

Areas for Contribution

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages