🎯 GYANARATNA Platform

A comprehensive educational platform with role-based access for teachers and students, featuring real-time progress tracking, quiz management, and gamified learning experiences.

🚀 Quick Start

Option 1: Automated Setup (Windows)

# Clone the repository
git clone https://github.com/CodeByDeepankar/hackthon-sih.git
cd hackthon-sih

# Run automated setup
start.bat

Option 2: Automated Setup (Linux/Mac)

# Clone the repository
git clone https://github.com/CodeByDeepankar/hackthon-sih.git
cd hackthon-sih

# Make script executable and run
chmod +x start.sh
./start.sh

Option 3: Manual Setup

# Clone and install dependencies
git clone https://github.com/CodeByDeepankar/hackthon-sih.git
cd hackthon-sih

# Next.js app setup
cd frontend
cp .env.local.example .env.local
# Edit .env.local with your Supabase and API credentials
npm install
npm run dev

📋 Prerequisites

• Node.js v18 or higher
• Supabase account with a project (URL and Service Role key)
• Git for cloning the repository

🗄️ Database Setup

Supabase Configuration

1. Sign in to Supabase and create a new project
2. Copy the Project URL and Service Role key from Project Settings → API
3. Update frontend/.env.local with these values (SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY and optional anon key)
4. (Optional) Generate an anon key for browser usage if you call Supabase directly from the client

The backend expects relational tables such as subjects, quizzes, questions, student_progress, quiz_responses, achievements, and supporting reference tables. Use the SQL editor in Supabase to create tables that match the application's data model.

🌟 Features

👩‍🏫 Teacher Dashboard

• Subject Management: Create and organize educational subjects
• Quiz Creation: Build interactive quizzes with multiple choice questions
• Student Progress: Monitor individual and class-wide performance
• Analytics: Real-time insights into student engagement
• School Management: Track students within the same school

👨‍🎓 Student Dashboard

• Take Quizzes: Interactive quiz-taking experience with timers
• Progress Tracking: View personal performance and improvement
• Daily Streaks: Gamified learning with streak tracking
• Subject Exploration: Browse and access quizzes by subject
• Achievement System: Track accomplishments and milestones

🎮 Gamification Features

• Daily Streaks: Encourage consistent learning
• Progress Visualization: Visual progress bars and statistics
• Achievement Badges: Reward system for milestones
• Leaderboards: Friendly competition between students
• Real-time Feedback: Instant quiz results and explanations

🏗️ Architecture

API Layer (Next.js Route Handlers)

• RESTful endpoints served from /api/*
• Supabase data layer on PostgreSQL
• Role-based access control
• Server-Sent Events and WebSocket broadcasting
• Comprehensive error handling

Frontend (Next.js 15)

• Modern React with App Router
• Responsive design with Tailwind CSS
• Clerk authentication
• Progressive Web App (PWA) features
• API client abstraction for Supabase-backed services

Database (Supabase)

• Managed PostgreSQL with realtime channels
• Row-Level Security (RLS) ready policies
• Built-in authentication, storage, and edge functions
• SQL editor and dashboard for data exploration

📚 API Documentation

Health Check

GET /health

Authentication & Users

GET /users/:userId/role
POST /users/role

Subjects

GET /subjects
POST /subjects
PUT /subjects/:id
DELETE /subjects/:id

Quizzes & Questions

GET /quizzes
POST /quizzes
GET /quizzes/:id
GET /questions/quiz/:quizId

Student Progress

GET /students/school/:schoolId
GET /students/:studentId/progress
GET /progress/school/:schoolId
POST /responses

🛠️ Development

Environment Variables

Next.js (.env.local)

SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
# Optional if you call Supabase directly from the browser
# NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
# NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
CLERK_WEBHOOK_SECRET=your-clerk-webhook-secret
GEMINI_API_KEY=your-google-gemini-api-key

Development Commands

npm run dev      # Start development server
npm run build    # Build for production
npm start        # Serve the production build

🚀 Deployment

Production Environment

• Set NODE_ENV=production
• Use HTTPS for all URLs
• Configure proper CORS origins
• Set up database backups
• Enable rate limiting

Docker Deployment

Container templates will be updated to reflect the unified Next.js API layer. Deployments can target any Node.js hosting that supports Next.js.

🔧 Troubleshooting

Common Issues

"Failed to fetch" Error

• Ensure the Next.js dev server is running on port 3000
• Verify Supabase credentials in .env.local
• Check browser console and server logs for detailed errors

Database Connection Failed

• Confirm SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY in .env.local
• Regenerate keys from Supabase dashboard if rotated
• Check Supabase project status page for outages

Authentication or CORS Issues

• Confirm the site URL configured in Clerk matches the dev origin
• Ensure all requests target the same origin (http://localhost:3000 during development)
• Clear cached credentials or restart the dev server after env changes

Debug Tools

• Health check: http://localhost:3000/api/health
• Supabase dashboard: https://app.supabase.com/
• Browser developer tools for frontend issues

📖 Documentation

• Deployment Guide - Comprehensive deployment instructions
• Deployment Checklist - Step-by-step checklist
• Full Stack Guide - Technical architecture details

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

📄 License

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

🆘 Support

If you encounter issues:

1. Check the troubleshooting section above
2. Review the deployment checklist
3. Check server logs for errors
4. Create an issue on GitHub with detailed information

🎯 Features Roadmap

• Advanced analytics dashboard
• Video lesson integration
• Mobile app development
• Multi-language support
• Advanced gamification features
• Integration with external LMS systems

---

Made with ❤️ for gamified STEM education

bput-hackathon

bput-hackathon