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.
Two entry modes
Section titled “Two entry modes”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.
Status machine
Section titled “Status machine”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.
Entering (keyword mode)
Section titled “Entering (keyword mode)”luckyDrawPublic.enter takes { id, code, phone?, acceptTerms: true } and
checks, in order:
- 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. - The draw is a keyword draw and is
open. - No staff. Any account with an
admin_rolesrow 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. - The code matches after trimming, ignoring case.
- 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. - The entry is inserted with
onConflictDoNothing. A partial unique index on(draw, user) WHERE purchase_id IS NULLmakes a second entry a no-op.
Public procedures never return the entry code, emails or phone numbers.
Spinning
Section titled “Spinning”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
spinNextcall 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 wheel
Section titled “The wheel”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).
Proof photos
Section titled “Proof photos”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.
Who can do what
Section titled “Who can do what”| 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.
Public surface
Section titled “Public surface”/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.listreturns something. There is also a footer link. - Event pages:
EventLuckyDrawPromoshows 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.
Running one on the day
Section titled “Running one on the day”The MC runbook is in Events, artists and bookings.
