Heads Up! AI-Powered Party Game

A full-stack MERN application bringing the classic "Heads Up!" party game to your browser and phone supercharged with AI-powered card generation, smart content validation, and real-time motion controls.

---

Table of Contents

• Overview
• How the Game Works
• AI Integration
• Tech Stack
• Database Schema
• API Reference
• Getting Started
• Environment Variables
• Game Flow
• Device Support

---

Overview

Heads Up! is a real-time party guessing game where one player holds their phone to their forehead while others give clues. The player tilts the phone down to mark a correct answer and up to pass. The goal is to guess as many cards as possible before the timer runs out.

This version goes beyond the classic by integrating Groq AI at three key points:

1. Deck Generation — Describe a theme, get a full deck of cards in seconds
2. Content Validation — AI reviews every card before it goes live to ensure quality and appropriateness
3. Smart Gameplay — Cards are shuffled randomly, sessions are tracked, and stats update automatically after every game

---

How the Game Works

For Players on Mobile

1. Browse or create a deck
2. Tap a deck to open the setup screen
3. Choose a timer — 30s, 45s, or 90s
4. Hold the phone vertically against your forehead
5. The app detects your phone angle using the DeviceOrientation API
6. When you tilt the phone face-down → Correct
7. When you tilt the phone face-up → Pass
8. The next card appears automatically after each action
9. The game ends when the timer runs out or all cards are played
10. Results screen shows your score and a full card-by-card breakdown

For Players on Desktop / Laptop

The same game works on desktop using keyboard controls:

• → or D — Correct
• ← or A — Pass

On-screen Pass and Correct buttons are always visible as a universal tap/click fallback on all devices.

Position Detection (Mobile)

The app uses the device beta axis from the DeviceOrientation API to detect phone angle:

Beta Angle	Zone	Action
0° – 30°	Face up	Pass
30° – 65°	Transitioning	Waiting
65° – 115°	Upright (forehead)	Valid hold position
115° – 140°	Transitioning	Waiting
> 140°	Face down	Correct

Before the game starts, the app shows a live position validator that waits for the phone to be held correctly at 65°–115° for at least 0.9 seconds before beginning the countdown. If the phone is lowered below 45° for more than 0.8 seconds mid-game, the game automatically pauses and resumes when the phone is raised back to position.

---

AI Integration

Card Generation — POST /api/ai/generate-cards

Users enter a theme (e.g. "90s Bollywood movies", "Premier League footballers", "SpaceX missions") and a card count. The backend sends a structured prompt to the Groq API:

Generate [count] Heads Up! game cards for the theme: "[theme]".
Return a JSON array of objects with a "Word" field only.
Words should be well-known, varied in difficulty, and fun to guess.

The response streams back as a JSON array and is parsed, deduplicated, and trimmed before being returned to the frontend. Users can then edit, delete, or regenerate individual cards before saving the deck.

Rate limiting: AI generation is limited per user session to prevent abuse.

Card Validation — POST /api/ai/check-cards

Before any deck is saved as public, every card passes through an AI content check. The validator sends the full card list to Claude and receives a simple { valid: Boolean, flagged: String[] } response indicating whether any cards contain inappropriate, offensive, or low-quality content.

Review these Heads Up! game cards for a family-friendly party game.
Return JSON: { "valid": true/false, "flagged": ["word1", "word2"] }
Flag any cards that are offensive, inappropriate, or not suitable for general audiences.

Cards that are flagged are highlighted in the deck editor before the user can publish. Decks with flagged cards cannot be set to IsPublic: true until the flagged cards are removed or edited.

---

Tech Stack

Layer	Technology
Frontend	React 18 + Vite, React Router v6, Tailwind CSS
Backend	Node.js, Express.js
Database	MongoDB with Mongoose ODM
Authentication	JWT stored in httpOnly cookies, bcrypt password hashing
AI	Groq API (card generation + validation)
Mobile APIs	DeviceOrientation API, WakeLock API, Screen Orientation API

Database Schema

User Collection

User {
  _id                   ObjectId (auto)
  Username              String, unique, required, trim, min:3 max:30
  Password              String, required, hashed (bcrypt)
  AvatarColor           String (hex or CSS gradient)
  CreatedAt             Date (auto)
  UpdatedAt             Date (auto)

  Stats {
    GamesPlayed         Number, default: 0
    TotalCorrect        Number, default: 0
    TotalPasses         Number, default: 0
  }

  SavedDecks            [ObjectId] → ref: Deck
  MyDecks               [ObjectId] → ref: Deck

  History [
    {
      DeckId            ObjectId → ref: Deck
      PlayedAt          Date
    }
  ]
}

Deck Collection

Deck {
  _id                   ObjectId (auto)
  Title                 String, required, trim, max:60
  Description           String, trim, max:200
  BackgroundColor       String (hex or CSS gradient)
  CreatedAt             Date (auto)
  UpdatedAt             Date (auto)

  CreatedBy             ObjectId → ref: User  (null = system deck)
  IsSystem              Boolean, default: false

  Cards [
    {
      Word              String, required, trim, max:60
    }
  ]                     max 20 cards enforced via validator

  WordCount             Number (auto-synced via pre-save hook)
  Likes                 Number, default: 0
  Tags                  [String]
  Plays                 Number, default: 0
  IsPublic              Boolean, default: false
}

Note: WordCount is never set manually. A Mongoose pre('save') hook on the Deck model automatically syncs it with Cards.length on every save.

Note: CreatedBy: null marks a deck as a built-in system deck. System decks (IsSystem: true) cannot be edited or deleted by any user.

---

API Reference

Auth — /api/auth

Method	Endpoint	Auth	Description
POST	/api/auth/register	No	Register new user. Body: { Username, Password }
POST	/api/auth/login	No	Login. Returns httpOnly JWT cookie. Body: { Username, Password }
POST	/api/auth/logout	Yes	Clears JWT cookie
GET	/api/auth/me	Yes	Returns current authenticated user object

---

Decks — /api/decks

Method	Endpoint	Auth	Description
GET	/api/decks	No	Paginated public decks. Query: ?page=1&limit=12&tag=movies&sort=plays
GET	/api/decks/:id	No	Single deck by ID
POST	/api/decks	Yes	Create a new deck. Body: { Title, Description, BackgroundColor, Cards, Tags, IsPublic }
PUT	/api/decks/:id	Yes	Edit deck — owner only
DELETE	/api/decks/:id	Yes	Delete deck — owner only
POST	/api/decks/:id/like	Yes	Toggle like on a deck
POST	/api/decks/:id/save	Yes	Toggle save deck to user's SavedDecks

---

AI — /api/ai

Method	Endpoint	Auth	Description
POST	/api/ai/generate-cards	Yes	Generate cards via Claude. Body: { theme: String, count: Number }. Returns { cards: [{ Word }] }
POST	/api/ai/check-cards	Yes	Validate card list. Body: { cards: [{ Word }] }. Returns { valid: Boolean, flagged: [String] }

---

Game Sessions — /api/session

Method	Endpoint	Auth	Description
POST	/api/session/start	Yes	Start a session. Body: { DeckId, TimerDuration }. Returns { SessionId }
POST	/api/session/end	Yes	End session + update all stats. Body: { SessionId, DeckId, TimerUsed, Results: [{ Word, Result }], Score: { Correct, Passed } }

/api/session/end side effects: Increments Deck.Plays, updates User.Stats.GamesPlayed, User.Stats.TotalCorrect, User.Stats.TotalPasses, and pushes { DeckId, PlayedAt } into User.History — all in a single atomic operation.

---

Users — /api/users

Method	Endpoint	Auth	Description
GET	/api/users/:id/profile	No	Public profile — username, avatar, stats, public decks
GET	/api/users/me/decks	Yes	All decks created by the logged-in user
GET	/api/users/me/saved	Yes	All decks saved by the logged-in user

---

Getting Started

Prerequisites

• Node.js v18 or higher
• MongoDB — local instance or MongoDB Atlas
• Groq API Key — from console.groq.com

1. Clone the Repository

git clone https://github.com/your-username/heads-up.git
cd heads-up

2. Install Dependencies

Backend:

cd server
npm install

Frontend:

cd client
npm install

3. Configure Environment Variables

Create a .env file inside the server/ folder (see Environment Variables below).

4. Run the App

Start the backend (from server/):

npm run dev

Runs on http://localhost:5000

Start the frontend (from client/):

npm run dev

Runs on http://localhost:5173

Run both together (from root, if concurrently is set up):

npm run dev

---

Environment Variables

Create server/.env with the following:

# Server
PORT=5000
NODE_ENV=development

# MongoDB
MONGO_URI=mongodb://localhost:27017/headsup
# or your Atlas connection string:
# MONGO_URI=mongodb+srv://<user>:<password>@cluster.mongodb.net/headsup

# JWT
JWT_SECRET=your_super_secret_jwt_key_here
JWT_EXPIRES_IN=7d

# GROQ AI
GROQ_API_KEY=your_groq_api_key

Create client/.env with the following:

VITE_API_BASE_URL=http://localhost:5000

Device Support

Feature	API Used	iOS	Android	Desktop
Tilt controls	DeviceOrientation API	Yes (permission prompt)	Yes	No
Keyboard controls	keydown events	No	No	Yes
Tap/click buttons	onPointerDown	Yes	Yes	Yes
Keep screen on	WakeLock API	Yes Safari 16.4+	Yes	Yes
iOS permission	DeviceOrientationEvent.requestPermission()	Required	N/A	N/A

iOS Note: Safari on iOS 13+ requires an explicit user gesture to grant DeviceOrientation permission. The app triggers this automatically on the "Start Game" button tap — no manual settings change needed.

---

Deck Creation Flow

Manual entry  ──┐
                ├──▶  Deck Editor  ──▶  AI Validation  ──▶  Save / Publish
AI generation ──┘                       (check-cards)

1. User creates a deck manually or enters a theme for AI generation
2. AI generates up to 20 cards via POST /api/ai/generate-cards
3. User edits, deletes, or regenerates individual cards
4. On publish, cards are validated via POST /api/ai/check-cards
5. Flagged cards are highlighted — deck cannot go public until resolved
6. Once clean, deck is saved with IsPublic: true and appears in community browse

---

Built with ❤️ using the MERN stack