KahootIt 🎮

A real-time multiplayer quiz platform inspired by Kahoot, with AI-powered quiz generation from PDF notes.

🌟 Features

Core Functionality

• AI-Powered Quiz Generation - Upload PDF notes and automatically generate multiple-choice questions using GPT-5 Mini
• Real-time Multiplayer - Host live quiz games with WebSocket-powered real-time updates
• Kahoot-Style Gameplay - Familiar and engaging game interface with:
  • Timed questions with countdown
  • Colorful answer buttons (Triangle, Diamond, Circle, Square)
  • Live leaderboard between questions
  • Answer distribution visualization
  • Podium results at the end

User Features

• Quiz Management - Create, view, edit, and organize your quizzes
• Live Game Hosting - Generate unique PINs for players to join
• Player Experience - Join games with a PIN, see results in real-time
• Responsive Design - Works on desktop, tablet, and mobile devices

🏗️ Tech Stack

Frontend

• Framework: Next.js 14 (App Router)
• Language: TypeScript
• Styling: Tailwind CSS
• Real-time: Socket.IO Client
• State Management: React Hooks (useState, useEffect, useContext)

Backend

• Framework: FastAPI (Python 3.12+)
• Database: SQLite with SQLAlchemy ORM
• Authentication: JWT (JSON Web Tokens)
• Real-time: Socket.IO (python-socketio)
• AI: OpenAI API (GPT-5 Mini)
• PDF Processing: PyMuPDF (fitz)

📋 Prerequisites

• Node.js 18+ and npm
• Python 3.12+
• OpenAI API Key - Get one at https://platform.openai.com/

🚀 Installation

1. Clone the Repository

git clone https://github.com/yourusername/kahootit.git
cd kahootit

2. Backend Setup

cd backend

# Create virtual environment
python -m venv venv

# Activate virtual environment
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Create .env file
# Add your OpenAI API key:
echo "OPENAI_API_KEY=sk-your-key-here" > .env
echo "SECRET_KEY=your-secret-key-for-jwt" >> .env

# Initialize database
python -c "from database import engine; import models; models.Base.metadata.create_all(bind=engine)"

# Start backend server
python main_api.py

Backend will run on http://localhost:8000

3. Frontend Setup

cd frontend

# Install dependencies
npm install

# Start development server
npm run dev

Frontend will run on http://localhost:3000

📖 Usage

Creating Your First Quiz

1. Sign Up/Login

   • Go to http://localhost:3000
   • Click "Sign In" and create an account

2. Create a Quiz

   • Click "Create Kahoot"
   • Upload a PDF file (lecture notes, study materials, etc.)
   • Enter a quiz title
   • (Optional) Specify page range and question count
   • Click "Create Kahoot"
   • AI will generate questions automatically!

3. Host a Live Game

   • Go to "My Kahoots"
   • Click on a quiz
   • Click "Host Live Game"
   • Share the PIN with players

Playing a Game

1. Join as a Player

   • Go to http://localhost:3000
   • Enter the game PIN
   • Enter your name
   • Wait for the host to start

2. Gameplay

   • Answer questions by clicking colored buttons
   • Faster correct answers = more points
   • View your results after each question
   • See final rankings on the podium

Host Controls

• Lobby: See players joining in real-time
• During Game:
  • Timer countdown (20 seconds per question)
  • Live answer distribution
  • Remaining players counter
  • "Show Answer" to reveal correct answer
  • "Next" to advance to leaderboard/next question
• Between Questions: Top 3 leaderboard
• End Game: Full podium with animations

🗂️ Project Structure

kahootit/
├── backend/
│   ├── main_api.py           # FastAPI app & endpoints
│   ├── models.py             # Database models
│   ├── schemas.py            # Pydantic schemas
│   ├── auth.py               # JWT authentication
│   ├── database.py           # Database configuration
│   ├── websocket_manager.py  # WebSocket event handlers
│   ├── game_service.py       # Game logic & PIN generation
│   ├── pdf_processor.py      # AI quiz generation
│   ├── requirements.txt      # Python dependencies
│   └── .env                  # Environment variables (not in repo)
│
├── frontend/
│   ├── app/
│   │   ├── page.tsx          # Homepage (PIN entry)
│   │   ├── login/            # Authentication
│   │   ├── create-kahoot/    # Quiz creation
│   │   ├── my-kahoots/       # Quiz library
│   │   ├── quiz/[id]/        # Quiz detail page
│   │   ├── host/[pin]/       # Host lobby & game control
│   │   └── play/[pin]/       # Player lobby, game, results
│   ├── components/
│   │   ├── Navbar.tsx
│   │   ├── QuizTile.tsx
│   │   └── MainContentWrapper.tsx
│   ├── context/
│   │   └── AuthContext.tsx   # Authentication context
│   ├── lib/
│   │   └── websocket.ts      # WebSocket client
│   └── package.json
│
├── .gitignore
└── README.md

🔑 Environment Variables

Backend (.env)

OPENAI_API_KEY=sk-your-openai-api-key
SECRET_KEY=your-secret-key-for-jwt-signing

Frontend (.env.local) - Optional

NEXT_PUBLIC_API_BASE_URL=http://localhost:8000

🎮 Game Flow

1. HOST creates quiz from PDF → AI generates questions
2. HOST clicks "Host Live Game" → Receives unique PIN
3. PLAYERS enter PIN → Join lobby
4. HOST sees players joining in real-time
5. HOST clicks "Start Game"
6. For each question:
   - Players see question & 4 colored answer buttons
   - 20-second timer counts down
   - Players submit answers
   - Host sees answer distribution in real-time
   - Host clicks "Show Answer" → Dramatic reveal
   - Host clicks "Next" → Top 3 leaderboard shown
7. After all questions → Full podium results
8. Players see their rank & total points

🛠️ API Endpoints

Authentication

• POST /register - Create new user
• POST /token - Login & get JWT

Quizzes

• GET /quiz/ - Get all quizzes for user
• GET /quiz/{quiz_id} - Get quiz details
• POST /upload-notes/ - Create quiz from PDF
• PUT /quiz/{quiz_id} - Update quiz
• DELETE /quiz/{quiz_id} - Delete quiz

Game Management

• POST /api/game/create - Create game session (returns PIN)
• GET /api/game/{pin}/info - Get game info
• POST /api/game/{pin}/start - Start game
• POST /api/game/{pin}/answer - Submit player answer
• GET /api/game/{pin}/leaderboard - Get current leaderboard
• POST /api/game/{pin}/end - End game

WebSocket Events

Client → Server:

• join_lobby - Player joins game
• host_join - Host joins game
• start_game - Host starts game
• show_question - Host shows question
• submit_answer - Player submits answer
• update_leaderboard - Host requests leaderboard
• end_game - Host ends game

Server → Client:

• lobby_joined - Confirm player joined
• host_joined - Confirm host joined
• player_joined - New player joined
• player_left - Player left
• game_started - Game has started
• question_shown - Question displayed
• player_answered - Player submitted answer
• answer_submitted - Answer recorded
• leaderboard_updated - Leaderboard data
• game_ended - Game finished

🧪 Development

Running Tests

# Backend (if tests exist)
cd backend
pytest

# Frontend
cd frontend
npm test

Code Quality

• Frontend uses TypeScript for type safety
• Backend uses Pydantic for data validation
• Console logs removed for production
• Error handling implemented throughout

---

Built with ❤️ using Next.js, FastAPI, and GPT-5 Mini