🎯 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

# Backend setup
cd backend
cp .env.example .env
# Edit .env with your CouchDB credentials
npm install
npm start

# Frontend setup (in new terminal)
cd frontend
cp .env.local.example .env.local
npm install
npm run dev

📋 Prerequisites

• Node.js v18 or higher
• CouchDB v3.0 or higher
• Git for cloning the repository

🗄️ Database Setup

CouchDB Installation

• Windows/Mac: Download from Apache CouchDB
• Linux: sudo apt-get install couchdb
• Docker: docker run -d -p 5984:5984 -e COUCHDB_USER=admin -e COUCHDB_PASSWORD=password apache/couchdb:3.3

Database Configuration

1. Start CouchDB service
2. Access admin panel: http://localhost:5984/_utils
3. Create admin user (recommended: admin/password)
4. Update backend/.env with your credentials

🌟 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

Backend (Node.js + Express)

• RESTful API endpoints
• CouchDB integration with offline sync
• Role-based access control
• Real-time progress tracking
• Comprehensive error handling

Frontend (Next.js 15)

• Modern React with App Router
• Responsive design with Tailwind CSS
• Clerk authentication
• Progressive Web App (PWA) features
• Offline-first data synchronization

Database (CouchDB)

• Document-based storage
• Built-in replication and sync
• Offline-capable
• ACID transactions
• Web-based admin interface

📚 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

Backend (.env)

COUCHDB_URL=http://127.0.0.1:5984
COUCHDB_USERNAME=admin
COUCHDB_PASSWORD=password
PORT=4000
NODE_ENV=development
FRONTEND_URL=http://localhost:3000

Frontend (.env.local)

NEXT_PUBLIC_API_URL=http://localhost:4000

Development Commands

Backend

npm start        # Start production server
npm run dev      # Start with nodemon
npm run env-check # Check environment variables

Frontend

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

🚀 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

# Using docker-compose (recommended)
docker-compose up -d

# Manual container setup
docker run -d -p 5984:5984 apache/couchdb:3.3
# Build and run your application containers

🔧 Troubleshooting

Common Issues

"Failed to fetch" Error

• Check if backend server is running on port 4000
• Verify CouchDB is accessible
• Check environment variables

Database Connection Failed

• Ensure CouchDB service is running
• Verify credentials in .env file
• Test connection: curl http://localhost:5984

CORS Errors

• Check FRONTEND_URL in backend .env
• Verify CORS configuration
• Ensure both servers are running

Debug Tools

• Health check: http://localhost:4000/health
• Database admin: http://localhost:5984/_utils
• 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