MrBbox

MrBbox is the official loot box application for MrBboy45's Twitch channel. Viewers turn their Channel Points into box credits, open a box on the site with a roulette animation, and receive the physical prizes they win at home. The channel's team manages everything from a back office.

The journey, from Twitch to delivery

1. The viewer exchanges Channel Points for the MrBbox reward on Twitch.
2. Twitch notifies the application, which automatically credits a box and marks the reward as fulfilled on Twitch.
3. The viewer opens the box on the site: the server draws the prize, and the wheel spins to the result.
4. For a physical prize, they enter their delivery details, then the team tracks the shipment.

For viewers

• Login with Twitch, with no password to create.
• My boxes: the box balance updates live, without reloading the page (WebSocket).
• Opening: an animated wheel, showing the rarity and colour of each prize.
• Draw history, paginated, with statistics by rarity.
• Delivery: a form for the details, with a reminder when a prize is waiting for them.
• Public catalogue: the box types, their prizes and the displayed probabilities.
• The winners: a public wall of every prize won, in real time. Every draw is visible, for transparency.

A fair, verifiable draw

• The draw is made on the server, with a cryptographic random generator. The wheel is only an animation of the result that has already been drawn.
• Probabilities are converted to whole numbers (a scale of one million) to avoid floating-point bias.
• A probability out of bounds is rejected: too low, the prize could never come up; too high, it would exceed the generator's range.
• Rarities are customizable (name, colour, image), with a "loser" rarity for boxes that pay nothing.

The Twitch integration

• OAuth login for viewers, and connecting the channel from the admin with the extra permissions it needs.
• EventSub webhook: every Channel Points exchange creates the right viewer's box, then the reward is marked as fulfilled or cancelled on Twitch.
• Catch-up: a reconciliation retrieves missed exchanges (at startup, or from an admin button).
• Each box type is linked to its Twitch reward, and EventSub subscriptions are managed from the admin.

The back office

• Three roles (viewer, admin, streamer) and fine-grained permissions per resource, enforced on the server and in the interface.
• Dashboard: indicators (boxes, draws, viewers), viewer search, manual box grants with their history, and real-time statistics.
• Users: profile, role change, ban and unban.
• Box types and prizes: creation, weights, display order, rarities, CSV import and export and catalogue backup.
• Media library: folders and image upload.
• Winners: shipping follow-up, filters, bulk updates and CSV export.
• Maintenance mode to close the site cleanly.

An overlay for the stream

A dedicated page to embed in OBS (browser source). It shows live who is opening a box, with the roulette, then a notification with the prize won. Events arrive continuously over WebSocket, settings are managed in the admin, and the link is protected by a token that can be regenerated.

The data

A MySQL database managed with Drizzle ORM: users, sessions and accounts (Better Auth), box types, prizes, box-prize links with their weights, boxes, draws, deliveries, rarities, media and folders, overlay and channel settings. Schema changes go through 17 versioned migrations.

Quality and operations

• Tests: unit tests (the draw, prize percentages, dates) and Nuxt application tests (opening a box, granting, statistics, permissions), with Vitest.
• Reliability: configuration validated at startup, seed data, TypeScript, automatic style checks.
• Observability: OpenTelemetry instrumentation (traces and logs).
• Accessibility and SEO: an accessibility audit in development, generated share images and metadata.
• Deployment: a Docker image without administrator rights, with a health check, and a complete Coolify stack (application, MariaDB, Redis).
• Maintenance: dependency updates proposed automatically.

This page describes how the project works. The signed-in area and the back office are not publicly visible.