🏆 Treasure Hunt Application

A full-stack, secure, mobile-first treasure hunt web application tailored for live events. Built with React (TypeScript), Node.js/Express, Prisma (PostgreSQL), and deploying entirely on Vercel Edge Serverless functions.

🚀 Overview

This project is a high-concurrency web application built to coordinate and manage a live treasure hunt event. It provides separate interfaces for participants (mobile-first gameplay) and administrators (management dashboard). The final iteration of this application has heavily shifted to optimize massive concurrent usage, reliability, and ease of use for event coordinators.

🌟 Key Features

• Randomized Tournament LRU Dispensing: Clues are structurally balanced automatically. Instead of defining static linear paths for teams, the backend drafts 3 unsolved clues randomly on the fly and rigorously assigns the clue with the least physical foot traffic. This guarantees event dispersion while feeling entirely random to players!
• Real-time Validation: Strict server-side verification of answers and locational clues.
• Admin Dashboard: Live monitoring of team progress, activity logs, system health checks, and granular control to Edit, Reset, or Roll clues manually mid-event.
• Stateless Cookie Sessions: The backend strictly utilizes signed, stateless tokens to manage admin and user logins. This permanently fixes Vercel deployment timeouts related to broken Express session database connections.
• Client-Side Media Compression: Bypasses Vercel's strict 4.5MB Edge Network payload maximum by instantly shrinking bulky iPhone camera-roll uploads directly in the client browser canvas before transmitting.
• Automated Game Limiters: The game enforces a definitive mathematical lock at exactly 6 solved clues and natively prevents network-lag submit-spam through server-enforced 30-second cooldowns.

---

🛠️ Tech Stack

Frontend

• Framework: React 19 (Vite)
• Language: TypeScript
• Styling: Tailwind CSS 4
• Routing: React Router DOM V6
• Icons: Lucide React

Backend

• Runtime: Node.js (Express)
• Language: TypeScript
• Database: PostgreSQL (via Supabase)
• ORM: Prisma
• Object Storage: Supabase Storage
• Session Management: Cookie-Session (Stateless JWT/HMAC bindings)

---

📂 Project Structure

treasure-hunt/
├── frontend/           # React + Vite application
│   ├── src/            # UI components, pages, and hooks
│   └── public/         # Static assets
├── backend/            # Express.js API
│   ├── prisma/         # Database schema and migrations
│   └── src/            # API routes (Auth, Game, Admin, Uploads)
├── guides/             # SQL scripts and legacy documentation
└── clink.yaml          # Infrastructure configuration

---

📊 Database Schema

The system uses a heavily-optimized relational schema specifically flattened for speed:

• Team: Represents a group of participants tracking their startedAt, active progression, and login codes.
• Clue: Individual tasks (Locational, Cryptic, or Contextual). Tracks timesServed to enforce LRU load-balancing.
• Submission: Records of team attempts on clues, enforcing 30-second cooldowns to prevent spamming.
• ActivityLog: Vast audit trail for administrative actions, tracking team logins and global operations.

---

🔐 Environment Variables

The application relies thoroughly on Environment Variables to protect secret configuration parameters. When deploying on Vercel, ALL of the below environment variables for both the Backend API and the Frontend React app must be added directly into the Vercel Project Settings at the exact same place.

Variable Name	Purpose	Where to obtain
SUPABASE_KEY_FRONTEND	The "anon" public key. Used to natively display public bucket clue images safely.	Supabase Dashboard > Project Settings > API > anon / public key.
SUPABASE_KEY_BACKEND	The "service_role" secret key. Used exclusively by the backend to bypass RLS and create buckets / upload files.	Supabase Dashboard > Project Settings > API > service_role / secret key.
SUPABASE_URL	The REST API connection URL to your Supabase instance.	Supabase Dashboard > Project Settings > API > Project URL.
DATABASE_URL	Prisma's direct Postgres connection string to the database.	Supabase Dashboard > Settings > Database > Connection String (URI).
ADMIN_USERNAME	The username you will type to log into the /admin portal.	Create your own! (e.g. admin)
ADMIN_PASSWORD	The password you will type to log into the /admin portal.	Create your own! (e.g. secretpassword123)
SESSION_SECRET	A complex random string used to securely sign login cookies and HMAC tokens.	Randomly generate your own! (e.g. jumanji_event_4829!#)
PORT	The local port the Express backend mounts on during testing.	Generally 4000 (Locally). Safe to omit on Vercel.
NODE_ENV	Designates whether to apply heavy security logic.	Set to production on Vercel.

---

🏁 Getting Started (Local Execution)

Prerequisites: Node.js (v18+) and your Supabase PostgreSQL cluster properly configured.

1. Backend Setup

   cd backend
   npm install

   Create a local .env file referencing your variables outlined above.

   npx prisma db push
   npm run dev

2. Frontend Setup

   cd frontend
   npm install
   npm run dev

---

☁️ Vercel Deployment Guide

To seamlessly take this web application live on Vercel Serverless Architecture without fatal database disconnections or build crashes, follow these exact steps:

1. Connect Repository Import your GitHub repository to a new Vercel project exactly as-is.

2. Configure Root & Framework settings

   • Root Directory: Leave it as the default (/). Vercel natively understands mono-repos using NPM workspaces.
   • Framework: Vite (Vercel should intelligently detect this).

3. Modify the Build Command Because Vercel defaults simply run npm run build, we must explicitly build the backend schema first to avoid fatal ESM import bugs on edge networks. Override the standard Build Command in Vercel settings to:

   cd backend && npx prisma db push --accept-data-loss && npx prisma generate && npx tsc && cd ../frontend && npm run build

4. Add Environment Variables Navigate to Environment Variables in the Project Settings. Insert all 9 variables derived from the table above. It is critical that the backend secrets natively share the same vault as the frontend variables since Vercel builds from the monorepo root.

5. Deploy & Seed Click Deploy. Vercel will install the DB schema, wire the Postgres pool, build the standard TSX react app, and go live! Navigate to /admin to verify deployment health.

---

🎨 Design Principles

• Aesthetic: Premium "Jumanji-inspired" theme with vibrant earthen colors, deep moss greens, and rich textured UI.
• Interactivity: Smooth transitions, micro-animations, and large hit-targets for an engaging participant experience.
• Responsiveness: Fully responsive, with a primary focus on touch-screen, mobile usability.

---

📝 License: This project is licensed under the MIT License.