AI Quiz Battle is a full-stack web app where you go head-to-head against a simulated AI opponent in a 5-round quiz match. Pick any topic, choose your difficulty, and the Gemini 2.5 Flash model generates a fresh set of questions on the fly — no static question banks, every game is unique. Built with a React frontend and a PHP + MySQL backend.
| Feature | Description |
|---|---|
| 🤖 AI-Generated Questions | Gemini 2.5 Flash creates 9 stratified questions (Easy/Medium/Hard) per game in real-time — every session is unique |
| ⚔️ AI Opponent | Compete against a simulated neural-net opponent whose accuracy scales with difficulty |
| 📈 Adaptive Difficulty | The game adjusts difficulty between rounds based on your speed and accuracy |
| ⚡ Power-Ups | 50/50 elimination, +10s extra time, and hint reveal — one use each per game |
| 🏆 Leaderboard | Scores persist in MySQL with a global Hall of Fame and podium for the top 3 |
| 📜 Game History | Full local history of every match with topic, difficulty, scores, and outcome |
| ⚙️ Settings | Configurable timer duration (10s–30s), sound toggle, animation toggle, and data management |
| 🔊 Sound Effects | Immersive audio — ticking timers, correct/wrong buzzes, power-up activation, victory/defeat fanfares |
| 🎨 Premium UI | Dark glassmorphism design with smooth Framer Motion animations and responsive layout |
| Technology | Purpose |
|---|---|
| React 18 | Component-based UI |
| Vite 5 | Dev server & bundler |
| Tailwind CSS 3 | Utility-first styling |
| Framer Motion | Page transitions & micro-animations |
| React Router v6 | Client-side routing |
| Lucide React | Icon library |
| Technology | Purpose |
|---|---|
| PHP 8 | Server-side API with built-in router |
| MySQL | Persistent score & leaderboard storage via PDO |
| Google Gemini REST API | Gemini 2.5 Flash integration for question generation (via cURL) |
| XAMPP | Local development environment (Apache + MySQL + PHP) |
ai-quiz-battle/
├── backend/
│ ├── index.php # PHP API router (generate, submit, leaderboard)
│ ├── database.php # MySQL PDO connection & auto-setup
│ ├── .htaccess # Apache URL rewriting
│ └── .env # API keys & DB config (not committed)
│
├── frontend/
│ └── src/
│ ├── components/
│ │ ├── Home.jsx # Topic & difficulty selection
│ │ ├── Quiz.jsx # Core gameplay with timer & power-ups
│ │ ├── Result.jsx # Score comparison & leaderboard submission
│ │ ├── Leaderboard.jsx # Global rankings with podium
│ │ ├── History.jsx # Local match history
│ │ ├── Settings.jsx # User preferences
│ │ ├── Header.jsx # Navigation bar
│ │ ├── Sidebar.jsx # Side navigation
│ │ └── Layout.jsx # Page wrapper
│ ├── context/
│ │ └── GameContext.jsx # Global state management
│ ├── hooks/
│ │ └── useSounds.js # Sound effect hooks
│ └── utils/
│ └── sounds.js # Audio file management
│
├── .gitignore
└── README.md
- XAMPP (includes PHP 8 + MySQL)
- Node.js v16+ (for the React frontend)
- Gemini API Key (free)
git clone https://github.com/farhan-jaffar/Ai-Quiz-Battle.git
cd Ai-Quiz-Battle# Frontend dependencies
cd frontend && npm installNote: The PHP backend has zero npm dependencies — PHP and MySQL handle everything natively.
Create backend/.env:
GEMINI_API_KEY=your_gemini_api_key
# MySQL (XAMPP defaults)
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASS=
DB_NAME=ai_quiz_battleOpen XAMPP Control Panel and start the MySQL service.
# Terminal 1 — PHP Backend
cd backend && php -S localhost:5000 index.php
# Terminal 2 — React Frontend
cd frontend && npm run devOpen http://localhost:3000 and start battling! ⚔️
Tip: You can view your database at any time via phpMyAdmin: http://localhost/phpmyadmin
Add these in your repository Settings → Topics for discoverability:
ai quiz gemini-api react php mysql tailwindcss framer-motion fullstack xampp
This project is licensed under the MIT License.