SnapHunt

SnapHunt is a real-world multiplayer photo scavenger hunt for 2–6 friends. Each player secretly photographs a nearby object, then receives an AI-written voice clue for another player's target. Search your surroundings, photograph the exact object, and let the AI provide matching evidence while the backend applies the game rules. Successful discoveries can unlock generated visual clues and races against other hunters. A cheerful pug hosts the experience.

Built for the Hacktoberfest "Touch Grass" challenge: it is a game that gets people off their chairs and looking at the real world around them.

Demo

• Demo video: https://drive.google.com/file/d/1wKuDRf7nL-k8ujCB4NbgPSmx_ULod4wN/view?usp=sharing

How to play

You need 2-6 players in the same area, each with a phone and an internet connection. No accounts and no API keys are required to play — guests join with a nickname.

1. One player creates a room and shares the join code. Everyone else joins on their own phone.
2. Each player secretly photographs a different object that everyone can physically reach. The other players never see these originals.
3. When every player has submitted and been accepted, the host starts the game.
4. Each player receives a voice clue for another player's object—never their own. Listen to it or read the text, find the object, and submit a photo.
5. A verified discovery earns points and can unlock a generated visual hint for another unresolved target. If the visual-clue challenger finds it before its original voice-clue hunter, that original hunter is eliminated for the rest of the round.
6. Continue hunting until the round ends, then check the leaderboard. The player with the highest total score wins; each player has at most five failed verification attempts per round. Faster finds earn more points; requesting a second clue reduces the award.

Three or more players are recommended to experience visual-clue races.

Play safely: watch where you are walking, only photograph objects you are allowed to, and be considerate of people around you. The app asks for camera access (to take photos) and plays audio clues through the browser.

The game has been playtested with 3 people at home using common household objects, and in a real case outdoors with some objects.

Current stack

Layer	Technology
Vision model	Qwen3.8-27B (nebius/Qwen/Qwen3.8-27B) via Nebius — primary; google/gemma-4-31b-it as a configurable alternative via VISION_MODEL (not an automatic fallback)
Agent framework	Mastra (structured agent responses)
Speech	ElevenLabs text-to-speech for clues
Visual clues	fal fal-ai/nano-banana-2/edit image editing
Frontend	Next.js, React, HeroUI, Tailwind CSS
Backend	Express
Data	Drizzle ORM, PostgreSQL, Supabase Storage
Realtime	Server-Sent Events
Hosting	Vercel

Repository layout

apps/
  web/                 Next.js frontend (@snaphunt/web)
  api/                 Express backend (@snaphunt/api)
packages/
  contracts/           Shared types and API contracts
  core/                Game rules and domain logic
  infra/               Database, storage, and provider adapters

The backend follows a ports-and-adapters style: game rules live in core and are enforced by the server, not by the AI providers. Providers (vision, speech, image editing) sit behind adapter interfaces so they can be swapped or faked.

Original target photos remain private to their creators; other hunters receive only authorized clues, not the reference photos. Provider credentials stay on the backend and are never exposed to the frontend.

Architecture

flowchart LR
  subgraph Phones["Players' phones"]
    Web["Next.js web app<br/>camera · clues · leaderboard"]
  end
  subgraph Backend["Backend (Express API on Vercel)"]
    Routes["Routes + controllers<br/>Zod validation · guest sessions"]
    SSE["SSE room updates"]
    Core["Core game rules<br/>assignments · scoring · eliminations"]
    subgraph Adapters["Adapters (ports implemented in packages/infra)"]
      Vision["Mastra vision agent"]
      Voice["ElevenLabs TTS"]
      Hints["fal image edit"]
      DB["Drizzle repositories"]
      Store["Supabase Storage<br/>private photos"]
    end
  end
  Web -- "HTTP: photos, finds" --> Routes
  SSE -- "live room state" --> Web
  Routes --> Core
  Core --> Vision & Voice & Hints & DB & Store
  Core --> SSE
  Vision --> Model["Qwen3.8-27B via Nebius<br/>(or Gemma 4 31B IT)"]
  DB --> PG[("PostgreSQL (Supabase)")]

The AI providers return evidence and media; only the core game rules change scores, assignments, or eliminations.

More detail:

• docs/architecture.md — technical design
• docs/product-brief.md — game rules and hackathon context (the brief predates the switch to Qwen as the default vision model; the table above reflects the current setup)

Development setup

Prerequisites: Node.js and Bun.

Install dependencies from the repo root:

bun install --frozen-lockfile

Option A: fake providers (no credentials, no AI calls)

The fake API serves real game flow with in-memory rooms and mocked vision, speech, and hints. It accepts every submitted target and returns "match" as the default judge verdict — useful for UI and game-flow work, but it is not real AI verification. All state resets on restart.

Terminal 1 — fake API (port 8787):

bun run dev:api:fake

Terminal 2 — web app (port 3000):

NEXT_PUBLIC_API_URL=http://localhost:8787 BASE_PATH= bun run dev:web

Then open http://localhost:3000.

Option B: real providers

The real backend needs credentials in .env at the repo root. Create it if you do not have one:

test -e .env || cp .env.example .env

Fill in the required values locally (see .env.example):

This is the beginning of the README. Read the rest at the original. Read the full README ↗