Overview

Dev Quiz Battle is a real-time, multiplayer coding quiz game where developers test their programming knowledge in competitive battles. The game features AI-generated questions across multiple programming languages and difficulty levels, real-time scoring, and a global leaderboard system.

Built with modern web technologies, the application leverages Next.js for the frontend, Convex for real-time backend operations, and Groq AI for dynamic question generation, ensuring every game session offers unique challenges.

Features

• Real-Time Multiplayer — Compete with friends in live quiz battles with instant score updates
• AI-Generated Questions — Unique programming questions generated by Groq AI for every game
• Multiple Languages — Support for JavaScript, TypeScript, Python, Go, Rust, and more
• Difficulty Levels — Questions ranging from easy to expert to match player skill levels
• Live Leaderboard — Global and per-language leaderboards with player rankings
• Responsive Design — Modern UI with light/dark theme support and OKLCH color spaces
• User Profiles — Track your stats, games played, and total score across languages

Getting Started

Prerequisites

• Node.js 18 or later
• pnpm (or npm/yarn)
• Convex account (free tier available)
• Groq API key (free tier available)

Installation

1. Clone the repository

   git clone https://github.com/violabg/dev-quiz-battle.git
   cd dev-quiz-battle
   

2. Install dependencies

   pnpm install
   

3. Set up Convex

   npx convex dev
   

   This will guide you through creating a new Convex project and generate your .env.local file with the necessary credentials.

4. Add your Groq API key

   Open .env.local and add your Groq API key:

   GROQ_API_KEY=gsk_your_api_key_here
   

5. Run the development server

   pnpm dev
   

6. Open the application

   Navigate to http://localhost:3000 in your browser.

Environment Variables

The following environment variables are required:

# Convex (auto-generated by `npx convex dev`)
CONVEX_DEPLOYMENT=your-deployment-name
NEXT_PUBLIC_CONVEX_URL=https://your-deployment.convex.cloud

# Groq API for AI question generation
GROQ_API_KEY=gsk_***

How to Play

1. Sign Up/Login — Create an account or log in using email/password or OAuth providers
2. Create or Join a Game — Start a new game with a unique code or join an existing one
3. Select Question Parameters — Choose programming language and difficulty level
4. Answer Questions — Compete against other players by answering coding questions quickly
5. Track Your Progress — View your score, rankings, and stats on your profile page

Tech Stack

Frontend

• Next.js 16 — React framework with App Router and Server Components
• React 19 — UI library with latest features
• TypeScript 5 — Type-safe development
• Tailwind CSS 4 — Utility-first styling with OKLCH color support
• Base UI — Accessible, unstyled UI components
• next-themes — Dark/light theme support

Backend & Database

• Convex — Real-time backend platform with built-in database, auth, and subscriptions
• @convex-dev/auth — Authentication solution with OAuth support

AI & Forms

• Groq AI — Fast AI inference for question generation
• AI SDK — AI integration utilities
• React Hook Form — Performant form validation
• Zod — TypeScript-first schema validation

UI Components

• Lucide React — Icon library
• Sonner — Toast notifications
• react-confetti — Victory animations

Project Structure

dev-quiz-battle/
├── app/                    # Next.js app directory (routes & pages)
│   ├── auth/              # Authentication pages
│   ├── dashboard/         # Game creation and lobby
│   ├── game/[code]/       # Game room with dynamic route
│   ├── leaderboard/       # Global leaderboard
│   └── profile/           # User profile and stats
├── components/            # React components
│   ├── auth/             # Authentication components
│   ├── game/             # Game-specific components
│   ├── ui/               # Reusable UI components
│   └── layout/           # Layout components
├── convex/               # Convex backend
│   ├── actions/          # Server actions (AI calls)
│   ├── mutations/        # Database write operations
│   ├── queries/          # Database read operations
│   └── schema.ts         # Database schema
├── hooks/                # Custom React hooks
├── lib/                  # Utility functions and types
├── public/               # Static assets
└── docs/                 # Detailed documentation

Documentation

For detailed information about the project architecture and components:

• Architecture Overview — System design and data flow
• Convex Integration — Backend setup, schema, and usage patterns
• Game Logic — Game flow and mechanics
• UI Components — Component library and guidelines
• Styling Guide — Tailwind CSS v4 and theming
• API Reference — Convex queries, mutations, and actions
• Contributing — How to contribute to the project

Scripts

pnpm dev          # Start development server
pnpm build        # Build for production
pnpm start        # Start production server
pnpm lint         # Run ESLint
pnpm devAi        # Start AI SDK DevTools

Development Workflow

The application uses Convex for real-time backend operations, which means:

• Automatic Schema Sync — Schema changes are automatically applied
• Type Safety — Generated TypeScript types from your schema
• Real-Time Updates — All queries are reactive by default
• Hot Reload — Backend changes reload instantly without server restart

When developing:

1. Keep npx convex dev running in a separate terminal
2. Run pnpm dev for the Next.js development server
3. Both servers will hot-reload on file changes

Key Features Explained

Real-Time Game Synchronization

All game state is synchronized in real-time using Convex subscriptions. When a player answers a question, all participants see the update instantly without polling or manual refreshes.

AI Question Generation

Questions are generated dynamically using Groq AI based on selected language and difficulty. The AI generates:

• Question text with programming concepts
• Code samples demonstrating the concept
• Multiple choice answers
• Detailed explanations for the correct answer

Scoring System

Points are calculated based on:

• Answer correctness (base points)
• Response time (faster answers earn more points)
• Question difficulty multiplier

Scores are tracked both per-game and globally across all languages.

Theme Support

The application uses Tailwind CSS v4 with OKLCH color space for:

• Smooth transitions between light/dark themes
• Perceptually uniform colors
• Better color manipulation and gradients
• Consistent appearance across devices

Troubleshooting

Convex Connection Issues

If you encounter connection issues with Convex:

# Ensure Convex is running
npx convex dev

# Clear and reinstall dependencies
rm -rf node_modules .next
pnpm install

AI Question Generation Fails

Verify your Groq API key is correctly set in .env.local and you haven't exceeded rate limits.

Build Errors

Ensure you're using Node.js 18 or later:

node --version  # Should be v18.0.0 or higher

Resources

• Next.js Documentation
• Convex Documentation
• Groq AI Documentation
• Tailwind CSS v4
• Base UI Components

---