Skip to content

Lucky draw flow

A lucky draw is a list of prizes, a pool of entries, and a stage page the MC runs on a projector. Each spin picks one winner on the server for the next prize, and the wheel animates to that name. The wheel is presentation only: the browser never decides who wins.

Primary code:

Piece Where
Admin and stage procedures packages/core/src/server/trpc/routers/luckyDraw.ts
Public procedures (list, get, my status, enter) packages/core/src/server/trpc/routers/luckyDrawPublic.ts
Pure spin rules (next prize, pool, wheel sample) packages/core/src/lib/lucky-draw/spin.ts, tested in apps/web/tests/unit/lucky-draw/spin.test.ts
Code-guess rate limit packages/core/src/server/lucky-draw/rate-limit.ts
Admin pages apps/web/src/app/[locale]/(main)/admin/lucky-draws/ (list, [id], [id]/stage)
Public pages apps/web/src/app/[locale]/(main)/lucky-draw/ (index, [id])
Wheel apps/web/src/components/lucky-draw/PrizeWheel.tsx

Design record and decisions: docs/lucky-draw/implementation.md in the repo.

Each draw picks one entry_mode:

Mode How people get in Entries per person Needs an event?
keyword Sign in at /lucky-draw/[id], type the secret code the MC reveals, tick the T&C One No
purchase Activate snapshots that event’s merch receipts of at least minPurchaseAmount (default RM100) One per receipt, so bigger spenders are weighted Yes, because receipts belong to an event

The event link is optional for keyword draws. It is checked on create, update and activate, so a merch-purchase draw can never exist without one. While a draw is in draft, admins can change or clear its event from the draw page.

stateDiagram-v2
    [*] --> draft
    draft --> open: open (keyword)
    open --> closed: close
    draft --> closed: activate (purchase)<br/>snapshots receipts
    closed --> drawing: first spin
    drawing --> completed: complete
    closed --> completed: complete
  • draft: the only state where the draw, its prizes, T&C and code can be edited or the draw deleted.
  • open: keyword entries are accepted.
  • closed: the entry list is frozen and the stage can spin.
  • drawing: at least one spin has happened.
  • completed: no pending winner is left. Prizes without a present winner are recorded as unawarded in the audit metadata.

status is a text column with a TypeScript-only enum, so the database will not reject a typo.

Open needs the secret code, non-empty T&C and at least one prize. Activate needs at least one prize and an event.

luckyDrawPublic.enter takes { id, code, phone?, acceptTerms: true } and checks, in order:

  1. Rate limit: 10 attempts per user per minute. The limit is keyed on the user, not the IP, because the whole venue shares one IP. It uses Redis on the API and falls back to web.rate_limit.
  2. The draw is a keyword draw and is open.
  3. No staff. Any account with an admin_roles row is refused, because a crew member winning on stage looks rigged. Other people who shouldn’t enter are excluded by the T&C, and staff can void their entry.
  4. The code matches after trimming, ignoring case.
  5. A phone number is required, because staff match its last four digits on stage. If the profile has none, the form asks for it and saves it to user_profiles.phone.
  6. The entry is inserted with onConflictDoNothing. A partial unique index on (draw, user) WHERE purchase_id IS NULL makes a second entry a no-op.

Public procedures never return the entry code, emails or phone numbers.

sequenceDiagram
    participant MC as Stage page
    participant S as luckyDraw.spinNext
    participant DB as Postgres
    MC->>S: spinNext({ id })
    S->>DB: pg_advisory_xact_lock(hashtext(id))
    alt a winner is pending
        S-->>MC: the same pending winner (retry-safe)
    else
        S->>S: nextPrize: smallest prize first, rank 1 last
        S->>S: pickEntry from the pool (CSPRNG)
        S->>DB: insert winner, outcome = pending
        S-->>MC: winner + 72-name wheel + winner's slice
    end
    MC->>S: markOutcome(present | absent)
  • Order. Prizes are spun from the highest rank number to rank 1, so the grand prize goes last.
  • Pool. The pool is every non-voided entry whose user has no winner row in this draw. Anyone picked leaves the wheel, whether present or absent, so each person can win once per draw. Winning one draw doesn’t stop someone winning another.
  • Retry-safe. While a winner is pending, every spinNext call returns that same winner, so a timed-out request that is sent again cannot pick twice. A partial unique index (one non-absent winner per prize) guards the same thing at the database level.
  • Absent. This frees the prize, and the next spin re-spins the same prize without that person. There is no email or push.
  • Empty pool. The spin fails with “No entrants left on the wheel”. Complete the draw, and the remaining prizes are recorded as unawarded.

The stage wheel shows up to 72 names: a random sample of the remaining pool that always includes the winner. The draw itself picks from the whole pool. Every slice carries a name in a font sized to the slice width, and rim pegs mark the slice boundaries. On large wheels a readout under the pointer names the passing slice during a spin. It follows the real CSS transform every frame, so it lands on the winner. The TCGKL logo stays upright in the centre.

Names come from publicEntrantName() (packages/core/src/lib/contest/public-name.ts), which uses the display name, else the first word of the full name, else “Collector”. It skips generated user_… handles. The winner card adds a masked phone tail (•••• 4821) for the on-stage check.

The stage page polls stageState every 3 seconds. Its side rail shows the entrant count, how many are still on the wheel and how many have been picked, the QR and code while entries are open, a spin button that names the prize, the winner card, and the prize ladder (next / on stage / awarded).

After the draw, staff upload a photo per present winner on /admin/lucky-draws/[id]. Photos show on the public results and on the prize card. Hide removes a single photo from the public page without deleting it. Uploading goes through /api/admin/upload, which only admits admin, editor and contest_admin. In practice that makes uploading admin-only, even though setProofPhoto and setPhotoHidden accept payment staff.

Action Roles
Create, edit, delete, prizes, activate admin
Open, close, spin, present/absent, void, complete, photo procedures admin, payment_staff
Admin pages (/admin/lucky-draws, [id], [id]/stage) manage_lucky_draws in PAGE_ACCESS

Every state change is audit-logged: create, update, delete, prize changes, open, close, activate, each fresh spin (SPIN_DRAW), each outcome, voids, completion (RUN_DRAW, with the unawarded prize ids), and photo changes.

  • /lucky-draw: lists draws that are live, or completed within the last 30 days. The first live draw is featured, followed by “More live draws” and “Recent winners”. Drafts never appear.
  • /lucky-draw/[id]: a hero with the grand prize, then one entry band that shows exactly one state: won, voided, in, closed, sign-in steps, the code form, or for purchase draws the “how to enter” steps and your entry count. Prizes and winners form one ladder, and the T&C sit in a collapsible section at the end.
  • Header: a Lucky Draw link under Play (desktop) and in the Explore sheet (mobile), shown only while luckyDrawPublic.list returns something. There is also a footer link.
  • Event pages: EventLuckyDrawPromo shows a card for that event’s live or recent draw. It renders nothing otherwise.

There are no /v1 endpoints. The mobile app opens the same web URL.

The MC runbook is in Events, artists and bookings.