first commit

README.md

@@ -0,0 +1,91 @@
+# 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
+```