A provably-fair social/sweepstakes slot — play · earn · progress · redeem

A minimal but production-shaped casino proof of concept: one polished slot machine with verifiable fair outcomes, a dual virtual-currency economy, VIP progression, daily login bonuses, and redemption tracking — wired end-to-end across web, API, and database.

⚠️ Not a real-money product. No payments, no purchases, no KYC. Sweeps redemptions are tracked through a status lifecycle, never paid out.

---

• For players — What it is · How to play · Features
• For developers — Quick start · Architecture · Tech stack · Make targets · Provably-fair spins · Money & safety · Testing · CI · Configuration · Docs

---

🎰 For players

What it is

Lunaland is a social / sweepstakes casino: you play real casino-style games with virtual currency — no purchase, ever. Wins in the promotional currency (Sweeps Coins) can build up to a redemption. This POC proves the whole engagement loop — play → earn → progress → redeem — around one polished slot game with provably-fair outcomes.

How to play

1. Register — you start with 10,000 Luna Coins 🌙 + 2.00 Sweeps Coins 💎 at Bronze tier.
2. Spin — pick a currency and a bet, then spin a 3×3 machine with 5 paylines. Wins update your balance and earn XP.
3. Come back daily — claim a daily bonus; consecutive days grow your streak for bigger rewards.
4. Climb the ranks — wagering earns XP and moves you up the VIP tiers, unlocking larger bonuses.
5. Redeem — once you hold ≥ 50.00 Sweeps Coins, request a redemption (gift card / bank / PayPal) and track its status.

Features

🎰 Provably-fair slots	Classic 3×3 machine, 5 paylines (3 lines + 2 diagonals), 6 symbols + a Luna scatter. Every spin is server-computed and independently verifiable. Target RTP ≈ 94%.
🌙 💎 Dual currency	Luna Coins for free play and Sweeps Coins as the redeemable promotional currency (1 SC ≈ $1, redeemable portion only). Exact integer accounting — never floats.
🏆 VIP progression	Earn XP by wagering and climb Bronze → Silver → Gold → Platinum → Diamond. Higher tiers grant larger daily bonuses and an XP boost.
🎁 Daily login bonus	One claim per day of Luna + Sweeps, scaled by tier and a consecutive-day streak. Idempotent — re-claims are cleanly rejected.
💸 Redemption tracking	At ≥ 50 SC redeemable, submit a redemption; Sweeps are held and the request enters the PENDING → APPROVED/REJECTED → PAID lifecycle.

🛠️ For developers

Quick start

cp .env.example .env        # or: make env
make up                     # build + start db, api, web (with hot reload)

Service	URL	Notes
Web (Next.js)	http://localhost:3000	the app
API (NestJS)	http://localhost:4000	health check at /health
Postgres	localhost:5432	migrated + seeded on first boot

Requirements: Docker + Docker Compose. make up is the supported path; Node is pinned to 24.16.0 (.nvmrc) for any host-side tooling.

Architecture

The browser only ever calls the same-origin /api/*; the Next.js server proxies those requests to the NestJS API (API_PROXY_TARGET). No CORS, and no per-environment URL baked into the client — the same image serves make up and make test.

flowchart LR
  UI["Browser · React UI"]
  Next["Next.js web :3000<br/>App Router + /api proxy"]
  Nest["NestJS api :4000<br/>auth · wallet · slot<br/>vip · bonus · redemption"]
  PG[("Postgres 16 :5432<br/>Drizzle ORM")]
  Shared[["@casino/shared<br/>BE↔FE type contract"]]
  UI -- "same-origin /api/*" --> Next
  Next -- "server-side proxy" --> Nest
  Nest -- "SQL" --> PG
  Shared -. "types" .-> Next
  Shared -. "types" .-> Nest

Loading

A contract-first monorepo (see ADR-0007): both apps build against the frozen @casino/shared types — plus docs/api-contract.md and docs/db-schema.md — so the tracks below develop in parallel against disjoint directories.

.
├── backend/             # NestJS API — auth · wallet · slot · vip · bonus · redemption
│   └── src/db/          #   Drizzle schema, migrations, seed
├── frontend/            # Next.js App Router UI (Tailwind v4 "Luna" theme) + /api proxy
├── packages/shared/     # @casino/shared — the BE↔FE type contract
├── docs/                # PRD, ADRs (0001–0008), API & DB contracts, CI notes
├── infra/               # Postgres init scripts
├── tests/               # Playwright integration + e2e (run against the containers)
├── docker-compose*.yml  # base · override (dev) · test · ci
└── Makefile             # task runner (see below)

Tech stack

Layer	Tech
Frontend	Next.js 16 (App Router) · React 19 · Tailwind CSS v4 · TypeScript
Backend	NestJS 11 · TypeScript
Data	PostgreSQL 16 · Drizzle ORM
Shared	@casino/shared workspace package (the BE↔FE type contract)
Infra	Docker Compose · Makefile · Node 24.16
Tests	Jest (unit) · Playwright (integration + e2e, run against the containers)

Make targets

Target	What it does
make up	Build + start db/api/web with hot reload
make down · make clean	Stop · stop and wipe the db volume
make logs · make ps	Tail logs · list containers
make migrate · make seed	Apply Drizzle migrations · seed VIP tiers + demo user
make psql	Open a psql shell on the db
make test · make test-be	Full containerized suite · backend unit tests
make lint · make typecheck	Lint workspaces · TypeScript check
make audit	Fail on high/critical CVEs
make help	List every target

Provably-fair spins

Every spin is server-authoritative and verifiable. A keyed byte stream — HMAC_SHA256(serverSeed, "<clientSeed>:<nonce>") — drives weighted reel strips via rejection sampling (no modulo bias). Each spin stores its seeds, so the grid can be recomputed and checked after the fact. The engine targets RTP ≈ 94%, asserted by a 200k-spin statistical test. See ADR-0004.

Money & safety

Balances are integer minor units (no floats). Every change runs inside a DB transaction with row locking and appends to an immutable ledger, so balances always reconcile and never go negative. Security basics: bcrypt password hashing, JWT auth, request validation, rate limiting, Helmet headers, a CORS allowlist, parameterized queries, and no secrets in source.

Testing

make test       # boots fresh db/api/web containers and runs the full suite against them
make test-be    # backend unit tests in-process (engine determinism + 200k-spin RTP)

make test brings up an ephemeral stack (docker-compose.test.yml) and runs a Playwright runner against the containers: API integration specs hit the api container, and a browser e2e drives the full journey — register → spin → daily bonus → redemption gating → error path — on the web container.

Continuous integration

GitHub Actions (.github/workflows/ci.yml) runs on every push and pull request in two stages:

1. static — npm ci, build shared → backend → frontend, then lint, typecheck, the backend Jest suite (engine determinism + RTP), and an npm audit gate.
2. e2e — builds the images and runs the containerized Playwright suite (docker compose … up against db/api/web), uploading the Playwright report as an artifact.

Both npm and Docker layers are cached (GitHub Actions cache) to keep runs fast. Details in docs/ci.md.

Configuration

All configuration is via environment variables — copy .env.example to .env. Never commit .env.

Variable	Purpose
DATABASE_URL	Postgres connection string used by the API
POSTGRES_USER · POSTGRES_PASSWORD · POSTGRES_DB	Database credentials
JWT_SECRET	Auth signing key — generate with openssl rand -hex 32
JWT_EXPIRES_IN · BCRYPT_ROUNDS	Token lifetime · password-hashing cost
WEB_ORIGIN	CORS allowlist (the web origin permitted to call the API)
API_PROXY_TARGET	Where Next proxies /api/* server-side (the API address)
THROTTLE_TTL · THROTTLE_LIMIT	Rate-limit window · max requests per window
API_PORT · WEB_PORT · POSTGRES_PORT	Service ports (4000 · 3000 · 5432)

The backend validates required vars at boot (DATABASE_URL, JWT_SECRET) and fails fast with a clear message if any are missing.

Docs & decisions

• Product: docs/prd/PRD-current.md
• Architecture decisions: docs/adr/ (ADR 0001–0008)
• API contract (BE↔FE): docs/api-contract.md
• DB schema (DB↔BE): docs/db-schema.md
• CI: docs/ci.md

---

_{Built as a proof of concept · MIT licensed · not a real-money product}