🧠 Adaptive AI Quiz Engine

A modern, AI-powered quiz platform built with React, Node.js, and Firebase that adapts to user learning patterns.

✨ QUICK START - Get Running in 2 Minutes!

🎯 Method 1: One-Click Start (Recommended)

# Run this single command to start everything:
.\start-working-app.bat

🎯 Method 2: Manual Start

# Terminal 1 - Backend
cd server
npm run dev-simple

# Terminal 2 - Frontend  
cd client
npx react-scripts start

🎯 Method 3: Individual Scripts

# Start backend only
cd server && npm run dev-simple

# Start frontend only (in new terminal)
cd client && .\start-client.bat

🌐 Access Your App

• Frontend: http://localhost:3000
• Backend API: http://localhost:3001
• Health Check: http://localhost:3001/api/health

🔥 Your Firebase Project

• Project ID: adaptive-quiz-engine-da726
• Console: https://console.firebase.google.com/project/adaptive-quiz-engine-da726
• Status: ✅ Configured and Ready, built with React, Node.js, Firebase, and Gemini AI.

🚀 Features

🎯 Core Features

• Adaptive Learning: AI-powered question generation based on user performance
• Multi-Modal Quizzes: Text, drag-and-drop, time-based challenges
• Gamification: Streaks, levels, achievements, and leaderboards
• Comprehensive Analytics: Performance tracking and detailed reports

📚 Quiz Categories

• Preparation: GATE, Placement exam prep
• Practice: Subject-specific practice sessions
• Mock Tests: Mixed difficulty assessments
• Game Mode: Competitive and social quizzes

🎮 Interactive Elements

• Real-time multiplayer quizzes
• Drag-and-drop questions
• Time-based challenges
• Social features and friend competitions

🛠 Tech Stack

Frontend

• React 18 with TypeScript
• Tailwind CSS for styling
• Framer Motion for animations
• React Query for state management
• React Router for navigation

Backend

• Node.js with Express
• Firebase (Auth, Firestore, Cloud Functions)
• FastAPI microservice for RAG and analytics
• Gemini AI for question generation

Database & Services

• Firebase Firestore for real-time data
• Firebase Authentication for user management
• Firebase Cloud Functions for serverless logic
• Firebase Cloud Messaging for notifications

📁 Project Structure

adaptive-ai-quiz-engine/
├── client/                 # React frontend
├── server/                 # Node.js backend
├── fastapi-service/        # FastAPI microservice
├── firebase-functions/     # Cloud Functions
├── docs/                   # Documentation
└── deployment/            # Deployment configs

🚀 Quick Start

Prerequisites

• Node.js 18+
• Python 3.9+
• Firebase CLI
• Git

Installation

1. Clone and install dependencies

git clone <repository-url>
cd adaptive-ai-quiz-engine
npm run install-all

2. Set up Firebase

firebase login
firebase init

3. Configure environment variables

# Copy and fill environment files
cp client/.env.example client/.env
cp server/.env.example server/.env
cp fastapi-service/.env.example fastapi-service/.env

4. Start development servers

npm run dev

Environment Variables

Client (.env)

REACT_APP_FIREBASE_API_KEY=your_api_key
REACT_APP_FIREBASE_AUTH_DOMAIN=your_domain
REACT_APP_FIREBASE_PROJECT_ID=your_project_id
REACT_APP_GEMINI_API_KEY=your_gemini_key

Server (.env)

FIREBASE_PROJECT_ID=your_project_id
GEMINI_API_KEY=your_gemini_key
FASTAPI_URL=http://localhost:8001

FastAPI (.env)

FIREBASE_PROJECT_ID=your_project_id
GEMINI_API_KEY=your_gemini_key

📱 Application Flow

1. Onboarding

• Subject and interest selection
• Initial skill assessment quiz
• Personalized learning path creation

2. Dashboard

• Daily streak tracking
• Weekly performance reports
• Leaderboard and social features
• Quick access to quiz modes

3. Quiz Modes

• Preparation: Structured exam prep
• Practice: Focused subject practice
• Mock: Comprehensive assessments
• Game: Competitive multiplayer

4. Analytics

• Performance tracking
• Adaptive difficulty adjustment
• Detailed progress reports
• Personalized recommendations

🎯 Key Features Implementation

Adaptive Learning Algorithm

• Real-time difficulty adjustment
• Performance-based question selection
• Personalized learning paths
• Spaced repetition integration

Gamification System

• XP and level progression
• Achievement badges
• Daily/weekly challenges
• Social competitions

Interactive Quiz Types

• Multiple choice with explanations
• Drag-and-drop matching
• Code completion challenges
• Time-pressure rounds

🚀 Deployment

Development

npm run dev

Production Build

npm run build
firebase deploy

Docker Deployment

docker-compose up -d

📊 Performance & Scalability

• Firebase Firestore: Real-time data synchronization
• Cloud Functions: Serverless scaling
• CDN Integration: Fast global content delivery
• Caching Strategy: Optimized performance
• Load Balancing: High availability

🤝 Contributing

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

👥 Team & Credits

• Project Lead: Dixita Balapuriya
• Contributors: Tejas Solanki, Suresh Amal, Dixita Balapuriya, Julie Kesariya

🙏 Acknowledgments

• Gemini AI for intelligent question generation
• Firebase for robust backend infrastructure
• React community for excellent tooling
• Open source contributors

---

Built with ❤️ for adaptive learning and educational excellence.