A web-based multiplayer Jeopardy game with host and player views, real-time gameplay, and access to 200,000+ real Jeopardy questions.

Play Now: poor-mans-jeopardy.vercel.app

• Lobby System: 4-character room codes with optional password protection
• Host Controls: Full game management including question selection, buzzer control, and score adjustments
• Player View: Clean interface with buzzer button and live game board updates
• Real-time P2P Sync: Instant updates via WebRTC peer-to-peer connections powered by PeerJS
• Score Tracking: Automatic score calculation with manual adjustment options
• Timer System: Configurable countdown timer with synchronized display across all clients
• Win Tracking: Persistent win counts across multiple games in the same lobby
• Instant Buzzer: Sub-50ms buzzer response times via direct P2P communication

• Custom Questions: Create and edit your own trivia questions
• Template System: Save and reuse game configurations
• Dataset Integration: Access to 200,000+ real Jeopardy questions from the included CSV dataset
• Category Browser: Search and filter through thousands of available categories
• Media Support: Add images and GIFs to questions and answers via URL or Tenor integration

• Sound Effects: Buzzer audio feedback (toggleable)
• Background Animation: Customizable dither effect (toggleable)
• Responsive Design: Works on desktop and mobile devices
• Frosted Glass UI: Modern, translucent interface design
• Local Storage: Templates and settings persist across sessions

• Framework: Next.js 16 with React 19
• Language: TypeScript 5.7
• Styling: Tailwind CSS v4
• Real-time: PeerJS for WebRTC peer-to-peer communication
• Database: Upstash Redis (via Vercel integration) - Required for production
• APIs: Tenor GIF API (optional)
• Graphics: Three.js for background effects

The game uses a hybrid approach for real-time synchronization:

1. Primary: PeerJS (WebRTC) - The host acts as a central peer. Players connect directly to the host via WebRTC for instant state updates (~50ms latency). This handles:

   • Buzzer events (critical for fair play)
   • Game state broadcasts
   • Question/answer reveals with synchronized timestamps
   • Lobby close notifications

2. Fallback: HTTP Polling - When P2P connections fail or during initial setup, the game falls back to efficient HTTP polling with version-based change detection.

Note: Local development uses in-memory storage. Production deployments require Upstash Redis integration to persist lobby data across serverless function instances.

• Node.js 18+
• pnpm (recommended) or npm

# Clone the repository
git clone https://github.com/MosesCommitsFraud/PoorMansJeopardy.git
cd PoorMansJeopardy

# Install dependencies
pnpm install

# Create environment file
cp .env.example .env.local

# Run development server
pnpm dev

Open http://localhost:3000 in your browser.

For local development, create a .env.local file:

# Optional: Tenor API key for GIF search
NEXT_PUBLIC_TENOR_API_KEY=your_tenor_api_key_here

# Optional: Redis connection (for testing with production-like storage)
# If not provided, uses in-memory storage (lobbies reset on server restart)
KV_REST_API_URL=your_redis_url
KV_REST_API_TOKEN=your_redis_token

Tenor API Key (optional): Enables GIF search functionality

1. Create a free account at Tenor Developer Portal
2. Obtain an API key
3. Add to .env.local

Without the Tenor API key, you can still paste image URLs directly.

Upstash Redis is REQUIRED for production - without it, lobbies will disappear due to serverless function limitations.

The app automatically detects these environment variables (injected by Vercel integration):

• KV_REST_API_URL + KV_REST_API_TOKEN (legacy Vercel KV)
• UPSTASH_REDIS_REST_URL + UPSTASH_REDIS_REST_TOKEN (new Upstash integration)

See Deployment section for setup instructions.

1. Initial Deployment

   • Click the button above or fork the repository
   • Import into Vercel
   • (Optional) Add NEXT_PUBLIC_TENOR_API_KEY environment variable
   • Complete initial deployment

2. Add Upstash Redis Integration ⚠️ REQUIRED

   Without Redis, lobbies will disappear in production due to serverless architecture.

   Option A: Via Vercel Dashboard

   • Go to your project in Vercel
   • Navigate to Storage tab
   • Click Create Database → Select Redis
   • Connect it to your project
   • Environment variables are automatically injected

   Option B: Via Vercel Marketplace

   • Visit vercel.com/marketplace/upstash
   • Click Add Integration
   • Select your Jeopardy project
   • Complete the integration

3. Redeploy

   • After adding Redis, trigger a new deployment
   • Verify lobbies now persist correctly

Vercel uses serverless functions that:

• Run in isolated, ephemeral instances
• Don't share memory between requests
• Terminate after ~15 seconds of inactivity

Without persistent storage (Redis), lobby data stored in one function instance won't be accessible to another, causing "Lobby not found" errors. Local development works fine because it runs as a single, continuous process.

├── app/
│   ├── api/                 # API routes (lobbies, questions)
│   ├── host/               # Host view pages
│   ├── lobby/              # Lobby management
│   └── player/             # Player view
├── components/
│   ├── ui/                 # Reusable UI components
│   ├── category-browser.tsx
│   ├── gif-picker.tsx
│   └── EndGameScreen.tsx
├── contexts/               # React contexts (settings)
├── hooks/
│   └── usePeerSync.ts      # React hooks for P2P communication
├── lib/
│   ├── kv-store.ts         # Storage abstraction
│   ├── peer-sync.ts        # PeerJS manager (host/player P2P)
│   ├── questions-loader.ts # Dataset integration
│   ├── tenor-api.ts        # Tenor API wrapper
│   └── template-storage.ts # Template management
├── types/                  # TypeScript definitions
└── assets/
    └── files/              # 200k+ Jeopardy questions CSV

Contributions are welcome! Please check out the contribution guidelines.

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

• Follow existing code style and conventions
• Test changes locally before submitting
• Update documentation as needed
• Keep commits focused and descriptive

Found a bug or have a feature request?

• Check existing issues: GitHub Issues
• Open a new issue with detailed information
• Include steps to reproduce for bugs
• Provide context for feature requests

This project is provided as-is for educational and personal use. The included Jeopardy questions dataset is sourced from publicly available data.

• Question dataset sourced from historical Jeopardy game data
• Real-time P2P communication powered by PeerJS - Simple WebRTC wrapper for peer-to-peer connections
• GIF integration powered by Tenor API
• UI components inspired by shadcn/ui
• Background effects using Three.js