Gamification Specification
Status: Canonical
Last Updated: 2026-05-11
Source: Schema tables and packages/backend/convex/domains/minigames.ts
Doc Status: Excellent | ✓ All 6 checks passed
Overview
The gamification system includes guest profiles (created on QR scan), photo wall submissions, guest reactions (Wave/Cheers/Heart), lucky spin wheel, and Google review challenges. Each feature is backed by dedicated Convex tables.Related specs
- Tech Stack — Real-time via Convex subscriptions
- Data Model — guestProfiles, challenges, spinResults tables
- Public Pages — Wall page at
/wall - Admin Dashboard — Challenge configuration in admin
- Staff POS — Challenges triggered at table level
- User Stories — US-CG01 through US-CG04 cover guest gamification
Features Overview
| Feature | Description | Tables |
|---|---|---|
| Guest Profiles | QR scan creates profile | guestProfiles |
| Photo Wall | Guests submit photos | photoSubmissions, photoLikes |
| Guest Reactions | Wave, Cheers, Heart | guestReactions |
| Lucky Spin | Wheel for prizes | spinPrizes, spinResults |
| Google Review | Review challenge | challengeConfig, challengeSubmissions |
Guest Profile System
Creation
Profiles are created when a guest scans their reservation QR code at check-in.Profile Data
- Nickname (guest entered)
- Country
- Origin (how they heard about us)
- Mood tags (selectable)
- Bio (optional)
- Avatar (optional)
Wall Page (/wall)
Public gallery of guest photos with like functionality.
- Grid of photo submissions
- Like button per photo
- Winner badges for featured photos
Table View (/dashboard/table)
Staff can view profiles at their table.
- Guest list for table
- Profile cards
- Mood tags display
Photo Wall
Submission Flow
- Guest visits photo station
- Takes photo or selects from gallery
- Adds caption (optional)
- Submits
- Photo appears on Wall after approval
Photo Card
- Image
- Caption
- Like count
- Submitter nickname
- Winner badge (if applicable)
Likes
- Any guest can like any photo
- One like per profile per photo
- Like count updates in real-time
Winner System
Admin can mark photos as winners.- Special badge displayed
- Featured in winner section
Guest Reactions
Types
- Wave — Hello/greeting
- Cheers — Toast/celebration
- Heart — Love/appreciation
How It Works
- Guests see other profiles at their table/event
- Can send reactions to other guests
- Reactions accumulate on profile
- Displayed as reaction badges
Lucky Spin
Configuration
Admin configures via/dashboard/admin/pos/challenges:
- Enable/disable
- Prize list with weights
- Max value per spin
Prizes
Types:- MENU_ITEM — Specific menu item
- DISCOUNT — Percentage off
- FREE_ITEM — Free item
Spin Flow
- Guest at table initiates spin
- Random prize selected by weight
- Prize applied to order as comp
- Result recorded in spinResults
Google Review Challenge
Configuration
Admin enables and sets:- Reward menu item
- Challenge period
Submission Flow
- Guest writes Google review
- Takes screenshot
- Submits via app
- Admin reviews screenshot
- Approves/rejects
- If approved, menu item added to bill as comp
Challenge Management
Admin Dashboard (/dashboard/admin/pos/challenges)
- Toggle challenges on/off
- Configure per-challenge settings
- View submission stats
Per-Challenge Stats
- Total submissions
- Approval rate
- Participation trend