How vivaanhooda/digital-treasure-hunt works
Digital Treasure Hunt is a server-authoritative campus game: teams register, receive a frozen randomized challenge order, visit locations, and submit GPS for server verification and scoring before seeing live standings. Admins configure datasets and game operations, while teams receive game state, notifications, and leaderboard updates through APIs and SSE. The README documents the major capabilities; sampled route handlers confirm registration, leaderboard, streaming, notifications, and upload flows. Other admin branches are represented by their exact enclosing route directories because their implementations were not sampled.
Main entry points: game Game endpoints · leaderboard Leaderboard endpoints · session.ts Request authorization · route.ts Team registration
Components 31
Team gameplay
- Registration UI
src/app/(auth)/register/page.tsx - Team registration
src/app/api/register/route.ts - Game screen
src/app/game/page.tsx - Game client hook
src/hooks/useGame.ts - Game endpoints
src/app/api/game - Leaderboard screen
src/app/leaderboard/page.tsx - Leaderboard endpoints
src/app/api/leaderboard
Identity and live updates
- Login UI
src/app/(auth)/login/page.tsx - Auth endpoints
src/app/api/auth - SSE stream
src/app/api/stream/route.ts - Event stream client
src/hooks/useEventStream.ts - Notification endpoints
src/app/api/notifications
Admin operations
- Admin console
src/app/admin - Dataset manager
src/components/admin/DatasetsManager.tsx - Dataset endpoints
src/app/api/admin/datasets - Game and archive admin
src/app/api/admin - Image upload
src/app/api/admin/upload/route.ts - Uploaded image serving
src/app/api/uploads/[...path]/route.ts
Server services
- Game rules
src/lib/game.ts - GPS distance
src/lib/geo.ts - Standings
src/lib/leaderboard.ts - Auth and sessions
src/auth.ts - Request authorization
src/lib/session.ts - Notifications
src/lib/notifications.ts - Upload handling
src/lib/uploads.ts - Dataset services
src/lib/datasets.ts
External infrastructure
- PostgreSQL
- Redis
Other components
- Team
- Team browser
- Administrator
Connections 45
- Team → Registration UI: registers
- Registration UI → Team registration: submits
- Team registration → PostgreSQL: creates team and game state
- Team registration → Game rules: shuffles challenges
- Team → Game screen: plays
- Game screen → Game client hook: uses
- Game client hook → Game endpoints: fetches and submits
- Game endpoints → Request authorization: authorizes
- Game endpoints → Game rules: applies rules
- Game endpoints → GPS distance: checks location
- Game endpoints → PostgreSQL: reads and updates progress
- Game endpoints → Redis: rate limits and publishes
- Team → Leaderboard screen: views standings
- Leaderboard screen → Leaderboard endpoints: requests
- Leaderboard endpoints → Request authorization: authorizes
- Leaderboard endpoints → Standings: gets standings
- Leaderboard endpoints → PostgreSQL: reads own game state
- Leaderboard endpoints → Redis: caches standings
- Standings → PostgreSQL: reads scores
- Team → Login UI: signs in
- Login UI → Auth endpoints: authenticates
- Auth endpoints → Auth and sessions: delegates sign-in
- Auth and sessions → PostgreSQL: checks accounts
- Auth and sessions → Redis: tracks sessions
- Game screen → Event stream client: subscribes
- Event stream client → SSE stream: opens SSE
- SSE stream → Request authorization: requires user
- SSE stream → Redis: subscribes channels
- Team → Notification endpoints: views notifications
- Notification endpoints → Request authorization: authorizes
- Notification endpoints → Notifications: loads notifications
- Notifications → PostgreSQL: reads notifications
- Administrator → Admin console: manages game
- Admin console → Dataset manager: manages datasets
- Dataset manager → Dataset endpoints: requests changes
- Dataset endpoints → Dataset services: delegates dataset work
- Dataset services → PostgreSQL: reads and writes datasets
- Admin console → Game and archive admin: configures operations
- Game and archive admin → PostgreSQL: manages game and archive data
- Game and archive admin → Redis: publishes updates
- Dataset manager → Image upload: uploads images
- Image upload → Dataset services: checks dataset lock
- Image upload → Upload handling: saves file
- Upload handling → Uploaded image serving: serves stored images
- Uploaded image serving → Team browser: returns image