# Dev Quiz Battle
[](https://nextjs.org/)
[](https://react.dev/)
[](https://www.typescriptlang.org/)
[](https://convex.dev/)
[](https://tailwindcss.com/)
Real-time multiplayer coding quiz game powered by AI question generation
[Features](#features) • [Getting Started](#getting-started) • [Documentation](#documentation) • [Tech Stack](#tech-stack)
## 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](https://nodejs.org/) 18 or later
- [pnpm](https://pnpm.io/) (or npm/yarn)
- [Convex account](https://convex.dev/) (free tier available)
- [Groq API key](https://console.groq.com/) (free tier available)
### Installation
1. **Clone the repository**
```bash
git clone https://github.com/violabg/dev-quiz-battle.git
cd dev-quiz-battle
```
2. **Install dependencies**
```bash
pnpm install
```
3. **Set up Convex**
```bash
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:
```env
GROQ_API_KEY=gsk_your_api_key_here
```
5. **Run the development server**
```bash
pnpm dev
```
6. **Open the application**
Navigate to [http://localhost:3000](http://localhost:3000) in your browser.
### Environment Variables
The following environment variables are required:
```env
# 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](https://nextjs.org/)** — React framework with App Router and Server Components
- **[React 19](https://react.dev/)** — UI library with latest features
- **[TypeScript 5](https://www.typescriptlang.org/)** — Type-safe development
- **[Tailwind CSS 4](https://tailwindcss.com/)** — Utility-first styling with OKLCH color support
- **[Base UI](https://base-ui.com/)** — Accessible, unstyled UI components
- **[next-themes](https://github.com/pacocoursey/next-themes)** — Dark/light theme support
### Backend & Database
- **[Convex](https://convex.dev/)** — Real-time backend platform with built-in database, auth, and subscriptions
- **[@convex-dev/auth](https://labs.convex.dev/auth)** — Authentication solution with OAuth support
### AI & Forms
- **[Groq AI](https://groq.com/)** — Fast AI inference for question generation
- **[AI SDK](https://sdk.vercel.ai/)** — AI integration utilities
- **[React Hook Form](https://react-hook-form.com/)** — Performant form validation
- **[Zod](https://zod.dev/)** — TypeScript-first schema validation
### UI Components
- **[Lucide React](https://lucide.dev/)** — Icon library
- **[Sonner](https://sonner.emilkowal.ski/)** — Toast notifications
- **[react-confetti](https://github.com/alampros/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](./docs/architecture.md)** — System design and data flow
- **[Convex Integration](./docs/convex.md)** — Backend setup, schema, and usage patterns
- **[Game Logic](./docs/game-logic.md)** — Game flow and mechanics
- **[UI Components](./docs/components.md)** — Component library and guidelines
- **[Styling Guide](./docs/styling.md)** — Tailwind CSS v4 and theming
- **[API Reference](./docs/api.md)** — Convex queries, mutations, and actions
- **[Contributing](./docs/contributing.md)** — How to contribute to the project
## Scripts
```bash
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:
```bash
# 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:
```bash
node --version # Should be v18.0.0 or higher
```
## Resources
- [Next.js Documentation](https://nextjs.org/docs)
- [Convex Documentation](https://docs.convex.dev/)
- [Groq AI Documentation](https://console.groq.com/docs)
- [Tailwind CSS v4](https://tailwindcss.com/docs)
- [Base UI Components](https://base-ui.com/)
---