🎁 WhatsApp Secret Santa

Secret Santa, now with superpowers. ✨

Participants sign up, build their wishlist, and the organiser runs a draw that respects exclusions, sets a budget, avoids repeating past pairings, and delivers results via a reveal page, WhatsApp, email or push. Schedule it for later, reveal the pairings on a date — or keep them secret forever.

Rewritten from the ground up: from an Express prototype → Next.js 16 · React 19 · Better Auth · Postgres/Drizzle. Dockerised, deploy-ready for Coolify. 🐳

---

✨ Features

	Feature	What it does
🔐	Accounts	Email/password login (Better Auth). The first user (or ADMIN_EMAIL) becomes admin automatically.
📝	Wishlists	Each participant lists what they'd like to receive — their santa sees it all.
🚫	Exclusions	Forbidden pairs (couples, siblings) never draw each other.
💰	Budget	Optional per-draw budget, shown on the reveal page.
🕰️	History	Past draws are used to avoid repeating last year's pairing — and each member sees their own match history on their dashboard.
🎲	Robust algorithm	Backtracking derangement — respects constraints, or fails with a clear error.
🔁	Self-draw toggle	Optional per-draw switch to allow being matched to yourself (off by default).
⏰	Schedule a draw	Pick a date/time — the draw runs and delivers itself automatically (in-process scheduler).
👀	Reveal pairings	Choose a date when the full giver→receiver list goes public (admin history + everyone's dashboard), or never.
📬	Pick your delivery	Per draw: reveal page, WhatsApp + link, or WhatsApp direct.
✉️	Email (optional)	Resend integration — emails the match to participants with a known account email.
🔔	Push (optional)	Installable PWA with Web Push notifications when a match is ready.
🔗	Account linking	Manually-added participants can later be linked to a real user account.
🌐	Site metadata	Admin "Technical" tab edits OpenGraph title, description, icon and link-preview banner at runtime.
🏳️	Phone with flags	Country dial-code picker with SVG flags + free-typed codes; stored WhatsApp-style.

📬 Delivery modes

🔗 Reveal	Private reveal links, with a per-link view limit.
💬 WA + Link	WhatsApp message containing the reveal link.
🎅 WA Direct	WhatsApp message with the match's name in the template.

---

🧱 Stack

Layer	Choice
🖼️ Framework	Next.js 16 (App Router) · React 19
🔐 Auth	Better Auth (+ admin plugin)
🗄️ Database	Postgres via Drizzle ORM (pg)
🎨 UI	Tailwind CSS v4 · shadcn/ui · react-day-picker · flag-icons
📲 Messaging	Meta WhatsApp Cloud API · Resend (email) · Web Push (PWA)
⏰ Scheduling	In-process poller via instrumentation.ts
🐳 Deploy	Docker · docker-compose · Coolify-ready

---

🚀 Getting started

🐳 Option A — Docker (recommended)

Brings up the app and Postgres together. Migrations run automatically on start.

# 1️⃣  Configure
cp .env.example .env
#   • BETTER_AUTH_SECRET  →  openssl rand -base64 32
#   • ADMIN_EMAIL         →  the email you'll sign up with (becomes admin)
#   • POSTGRES_*          →  credentials for the bundled database
#   • WA_*                →  (optional) only for WhatsApp delivery

# 2️⃣  Build + run
docker compose up -d --build   # 👉  http://localhost:3000

💻 Option B — Local dev

# 1️⃣  Install
npm install

# 2️⃣  Configure (set DATABASE_URL to a running Postgres)
cp .env.example .env

# 3️⃣  Apply migrations
npm run db:migrate

# 4️⃣  Run
npm run dev      # 👉  http://localhost:3000

💡 Need a quick Postgres for local dev? docker compose up -d db starts just the database.

💡 Sign up with ADMIN_EMAIL to get the admin role, then open /admin to add participants, set exclusions, choose delivery, and run the draw.

---

☁️ Deploy on Coolify

This repo ships a Dockerfile + docker-compose.yml, so Coolify can deploy it as a Docker Compose resource out of the box.

1. New Resource → Docker Compose, point it at this repo.
2. Set the environment variables (Coolify reads them into the compose file):
   • BETTER_AUTH_SECRET — a long random string
   • BETTER_AUTH_URL / NEXT_PUBLIC_APP_URL — your public URL (e.g. https://santa.example.com)
   • ADMIN_EMAIL — the account to auto-promote to admin
   • POSTGRES_USER / POSTGRES_PASSWORD / POSTGRES_DB
   • WA_* — optional, only for WhatsApp delivery
   • RESEND_* — optional, for email delivery
   • VAPID_* / NEXT_PUBLIC_VAPID_PUBLIC_KEY — optional, for push notifications
3. Deploy. 🎉 The bundled Postgres persists in the pgdata volume and migrations run automatically on every container start.

ℹ️ NEXT_PUBLIC_APP_URL is baked into the client at build time — set it before the image is built so reveal links use the right domain.

ℹ️ Prefer Coolify's managed Postgres instead of the bundled one? Remove the db service from the compose file and set DATABASE_URL to the managed instance's connection string.

---

📲 WhatsApp setup

For wa_link / wa_direct you need a Meta WhatsApp Business account and an approved template with two body parameters:

Param	Content
{{1}}	The giver's name
{{2}}	The match's name (wa_direct) or the reveal URL (wa_link)

Set WA_API_TOKEN, WA_PHONE_NUMBER_ID, WA_TEMPLATE_NAME, WA_TEMPLATE_LANGUAGE in .env. Reveal-page delivery needs none of this. ✅

---

✉️ Email setup (optional)

Powered by Resend. When configured, draw results are also emailed to participants whose account email is known.

RESEND_API_KEY="re_..."
RESEND_FROM="Secret Santa <santa@your.domain>"   # verified sender

Leave unset to disable email entirely. The admin Integrations card shows whether it's enabled.

---

🔔 Push notifications setup (optional)

The app is an installable PWA with Web Push. Generate a VAPID key pair once:

npx web-push generate-vapid-keys

VAPID_PUBLIC_KEY="..."
NEXT_PUBLIC_VAPID_PUBLIC_KEY="..."   # same value, inlined into the client
VAPID_PRIVATE_KEY="..."
VAPID_SUBJECT="mailto:you@example.com"

ℹ️ NEXT_PUBLIC_VAPID_PUBLIC_KEY is baked in at build time (it's a Dockerfile build arg). Participants enable notifications from their dashboard.

---

🛠️ Scripts

Script	What it does
npm run dev	🔥 Development server
npm run build	📦 Production build
npm test	🧪 Draw-algorithm unit tests
npm run db:generate	🧬 Generate a Drizzle migration
npm run db:migrate	⬆️ Apply migrations
npm run db:studio	🔍 Open Drizzle Studio

---

🗂️ Structure

app/                  🧭  routes (auth, dashboard, admin, reveal, api, manifest)
components/           🧩  UI (shadcn + components)
lib/                  ⚙️  auth · db/schema · draw · draw-runner · scheduler
                          whatsapp · email · push · pairings · settings · phone
instrumentation.ts   ⏰  boots the in-process draw scheduler
public/              🖼️  PWA service worker + app icon
drizzle/             🗃️  SQL migrations
scripts/             📜  database migration runner
Dockerfile           🐳  standalone production image
docker-compose.yml   🐳  app + Postgres (Coolify-ready)

---

📜 Versions

Branch	What it is
🟢 v2	This rewrite (Next.js · Better Auth · Drizzle) — current branch
🟡 v1	The original Express prototype (static HTML + JSON)

---

🤝 Contributing

Pull requests welcome! If you'd like to enrich the project, open an issue or a PR. Any Ko-Fis given would be greatly welcome to allow me to continue to mantain this project development. If you have any questions or issues, feel free to contact me on Discord (prefereble) or via chat in https://chung-jf.me. My Discord nickname is Rodaviva. 🎄

📄 License

MIT — see LICENSE.

🎄 Happy Xmas! 🎁