Gamification Specification
Status: Canonical Last Updated: 2026-05-11 Source: Schema tables and
packages/backend/convex/domains/minigames.ts
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 — 👋
- Cheers — 🍷
- Heart — ❤️
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