# Loot Hunt

A digital alternate reality game — find and scan hidden QR codes in real life to earn points and climb the leaderboard.

## How It Works

1. **Organizers** create a "hunt" and generate printable QR code cards
2. **Players** scan hidden QR codes to earn points — first find gets the most points
3. **Leaderboards** track top players per hunt and globally

### Point System

| Scan Order | Points |
|-----------|--------|
| 1st scan  | 500    |
| 2nd scan  | 250    |
| 3rd scan  | 100    |
| 4th+      | 50     |

Players earn points only once per package. Re-scanning lets you update the package hint.

## Tech Stack

- **Node.js** + Express
- **SQLite** via better-sqlite3
- **EJS** templates
- **PDFKit** + qrcode for printable QR sheets
- **Docker** deployment via Portainer

## Quick Start (Development)

```bash
cp .env.example .env
npm install
node src/setup-admin.js admin yourpassword
npm run dev
```

Visit `http://localhost:3000`

## Docker Deployment

The project deploys via Gitea Actions → Docker build → Portainer stack update.

```bash
# Build locally
docker build -t loot-hunt .

# Run
docker run -p 3000:3000 -v loot-data:/app/data \
  -e SESSION_SECRET=your-secret \
  -e BASE_URL=https://loot-hunt.com \
  loot-hunt

# Create admin user inside container
docker exec -it loot-hunt node src/setup-admin.js admin yourpassword
```

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `PORT` | Server port | `3000` |
| `NODE_ENV` | Environment | `production` |
| `BASE_URL` | Public URL (for QR codes) | `http://localhost:3000` |
| `SESSION_SECRET` | Session encryption key | (required) |
| `DB_PATH` | SQLite database path | `./data/loot-hunt.db` |
| `UPLOADS_DIR` | Image uploads directory | `./data/uploads` |
| `TRUST_PROXY` | Trust reverse proxy headers | `false` |

## Project Structure

```
src/
├── app.js              # Express application entry point
├── setup-admin.js      # CLI tool to create/promote admin users
├── config/
│   └── database.js     # SQLite initialization & schema
├── middleware/
│   └── auth.js         # Auth & admin middleware
├── models/
│   └── index.js        # All database operations
├── routes/
│   ├── auth.js         # Login/register/logout
│   ├── admin.js        # Hunt management & PDF download
│   ├── loot.js         # QR scan handling, image upload, hints
│   └── hunts.js        # Public hunt profiles & leaderboards
├── utils/
│   └── pdf.js          # QR code PDF generation
└── views/              # EJS templates
```