scav-hunt-tracker

A web app for running photo scavenger hunts among friends. Sign in, create a hunt, share an invite link, and race to upload photos that match each item.

Live at https://scavhunt.danqian.net.

Stack

• React 18 (Create React App) frontend.
• Firebase: Auth (Google + email/password), Firestore, Storage.
• FastAPI helper at api/ for HEIC→JPG conversion and CLIP-based item guessing; deployed separately on Render.

Quick start

npm install

# .env at the repo root, for HEIC conversion + the item-guess assistant.
# Skip if you only want to test the core flow without uploads.
echo "REACT_APP_API_URL=https://<your-render-host>" > .env

npm start  # http://localhost:3000

Localhost hits the production Firebase project configured in src/firebase.js — there's no staging. Anything you create on localhost (player profile, hunts, joins) lands in real Firestore. To run in isolation, either point the app at your own Firebase project (see below) or wire up the Firebase Emulator Suite.

npm scripts

Command	What it does
npm start	Run the React dev server on http://localhost:3000
npm run build	Build the production bundle into build/
npm test	Run CRA's test runner (no tests in this project today)
npm run fb -- <args>	Run any firebase CLI command without a global install
npm run fb:login	One-time browser sign-in to the Firebase CLI
npm run fb:deploy:rules	Deploy firestore.rules + storage.rules

Run it on your own Firebase project

Fork or clone the repo, then:

1. Create a Firebase project at https://console.firebase.google.com.
2. Enable the products the app uses (each is one click in the console):
   • Authentication → Sign-in method → enable Google and Email/Password.
   • Firestore Database → create database (production mode is fine; rules get replaced by firestore.rules on first deploy).
   • Storage → get started (default bucket location is fine).
3. Register a web app under Project settings → General → "Your apps" → Web. Copy the firebaseConfig object it gives you.
4. Drop that config into src/firebase.js in place of the existing firebaseConfig. The values aren't secrets — they're public client config.
5. Point the CLI at your project: edit .firebaserc and replace scav-hunt-tracker with your project id.
6. Deploy the security rules:

   npm install
   npm run fb:login           # one-time browser sign-in
   npm run fb:deploy:rules    # pushes firestore.rules + storage.rules

7. (Optional) The HEIC + CLIP helper. If you want iPhone HEIC uploads to render and the "guess which item this is" assistant, deploy api/ somewhere (Render, Fly, Cloud Run, locally with uvicorn api:app --reload) and add REACT_APP_API_URL=<your host> to .env. Without it the rest of the app works, but HEIC uploads will fail and item-guessing is disabled.
8. npm start to test, then npm run build and host the contents of build/ wherever you like (Firebase Hosting, Netlify, Vercel, an S3 bucket, etc.).

Repo layout

src/                React frontend
  Root.jsx            auth gate + ensures players/{uid} profile
  SignIn.jsx          Google + email/password sign-in (Firebase Auth SDK)
  Home.jsx            "Your hunts" list + create button
  CreateHunt.jsx      new hunt -> /manage/:id
  Manage.jsx          owner-only: items, dates, invite link
  Join.jsx            landing page for invite links
  Play.jsx            upload + leaderboard view
  Gallery.jsx         per-hunt photo gallery
  play/               UploadItem, SummaryTable, SubmissionDetails
  members.js          useHuntPlayers + MAX_MEMBERS cap
  firebase.js         Firebase SDK init (public client config)
api/                FastAPI image helpers (HEIC, CLIP)
firestore.rules     Firestore security rules
storage.rules       Storage security rules
firebase.json       Firebase CLI config
CLAUDE.md           Architecture + conventions for working in the repo

For deeper notes on the data model, security rules, and code conventions, see CLAUDE.md.