All engineering notes
Gaming, Real-money, architecture record

Provably-Fair iGaming Platform

This is the largest system in the collection and the one with the least tolerance for bugs: every code path either moves money or decides whether a player won. The design principle running through it is that outcomes are decided server-side, deterministically, from seeds committed before the player acts — the browser only renders what already happened. Around that core sits everything a licensed operator actually needs: a cashier, identity verification, bonuses, VIP progression and a fifteen-module affiliate subsystem.

180kBackend lines, across 1.7k files
50Bounded contexts, backend modules
54kClient lines, player web app
6Test suites, unit → e2e → penetration

Repository shape

Three repositories: player web app, operator console, and the backend that owns the money path

How this is presented

Documented as an architecture record. A real-money platform cannot be handed out as a public demo, so the artefact is the fairness model, the module map and the verified scale.

Where money and outcomes are decided

Follow a bet, a fairness proof, a deposit or an affiliate payout through the system. Note that the player client never touches the engine directly.

Player appClient surface

Renders games and balances. Deliberately powerless — it decides nothing.

Client surfaceServiceExternalRealtimeWorker / jobData store
Placing a bet

The money path for an in-house game.

Highlights

  • Provably-fair engine where the server commits to seeds before the player acts, so outcomes can be verified after the fact and cannot be altered retroactively.
  • A custom lint rule bans non-deterministic randomness inside the game engine — fairness is enforced at build time, not by code review.
  • Four in-house game implementations plus an aggregator integration for third-party titles.
  • Fifteen-module affiliate subsystem: tracking, attribution, campaigns, creatives, accrual, payouts, reports and team management.
  • Crypto cashier with identity verification, geo restrictions and TOTP two-factor authentication.
  • Six distinct test tiers including an explicit penetration-test suite and a runtime invariant checker.
  • Full observability stack — distributed tracing, metrics and error tracking — because a silent failure here is a financial loss.

Outcome-first design with a replaceable presentation layer

The important boundary is between the code that decides outcomes and moves money, and the code that draws things. Presentation can be rewritten freely; the engine and the ledger cannot. Everything else is organised as bounded contexts around that core.

Game engine

Deterministic outcome generation for the in-house games, plus the provably-fair primitives shared between them.

  • Server-side only — the client never decides a result.
  • Seeds are committed before play and revealed on rotation, so any round can be recomputed independently.
  • A dedicated lint rule fails the build if non-deterministic randomness appears anywhere in this directory.
  • Shared primitives are factored out so each game inherits the same fairness guarantees.

Application API

Fifty bounded contexts covering wallet, betting, bonuses, promotions, VIP progression, support, CMS and administration.

  • One module per context, so the affiliate system cannot reach into the wallet ledger by accident.
  • Balance and transaction handling are modelled as an explicit taxonomy rather than ad-hoc updates.
  • Rate limiting is Redis-backed so limits hold across instances.

Affiliate and partner subsystem

A near-complete second product: tracking, attribution, campaigns, creatives, accruals, payouts, metrics and reporting.

  • Partners authenticate through their own boundary, separate from player identity.
  • Accrual and payout are separate modules so money owed and money sent never get conflated.
  • Demo-conversion tracking is modelled explicitly to keep test traffic out of real accruals.

Compliance and cashier

Identity verification, geo restrictions, two-factor authentication and crypto deposits and withdrawals.

  • Verification snapshots are stored so a decision can be reconstructed later.
  • Geo-IP lookups gate access by jurisdiction.
  • The cashier is a separate context from the wallet ledger it credits.

Realtime and operations

Live bet feeds, balance pushes, alerting and the observability surface.

  • Distributed tracing and metrics are wired in from the start rather than retrofitted.
  • Configurable alert rules with their own event history.
  • A runtime invariant checker catches impossible states in production data.

Every bounded context

The scene above shows only the runtimes involved in a flow. This is the whole system — one directory per bounded context, which is why the affiliate subsystem cannot reach into the wallet ledger by accident. 52 units across 6 groups.

Money & wallet

9
walletbettingbonusespromopromotionsrakebackpacksb2binpayaggregator

Games

10
crashdiceminesblackjackexternal-gamesgame-settingsgame-hygienefairnessoriginals-insightskinguin

Affiliate & partner

15
affiliatepartnerpartner-accrualpartner-authpartner-campaignspartner-casino-linkpartner-creativespartner-demo-conversionspartner-metricspartner-payoutspartner-promopartner-reportspartner-teampartner-trackingpartner-websites

Identity & compliance

6
authuserskycfavoritesxpleaderboard

Realtime & ops

7
realtimelive-betsnotificationsalertsanalyticsmaintenancesystem

Content & support

5
adminblogseosupportemail

Stack by layer

Player client

Next.js, React Query, next-intl, WebSockets

Operator tooling

Vite, React, Recharts, Rich-text editor

Services

NestJS, WebSocket gateway, Deterministic game engine

Data

PostgreSQL, Drizzle ORM, Redis, Object storage

Integrations

Identity verification, Crypto payments, Game aggregator, Geo-IP, TOTP 2FA

Operations

OpenTelemetry, Prometheus metrics, Error tracking, Redis-backed rate limiting

Delivered work

Fairness and game engine

  • Four in-house games built on a shared provably-fair core.
  • Commit–reveal seed lifecycle with per-round nonce ordering.
  • Build-time enforcement that no non-deterministic randomness enters the engine.
  • Player-facing verification surface so results can be checked independently.
  • Aggregator integration for third-party game titles alongside the in-house set.

Money and compliance

  • Wallet ledger with an explicit transaction taxonomy instead of ad-hoc balance writes.
  • Crypto cashier covering deposits and withdrawals.
  • Identity verification with stored decision snapshots for audit.
  • Geo-IP gating and TOTP two-factor authentication.
  • Bonuses, promotions, rakeback, VIP progression and loot-pack mechanics.

Affiliate subsystem

  • Partner authentication kept separate from player identity.
  • Click tracking, attribution, campaigns, creatives and promo codes.
  • Accrual and payout modelled as distinct stages.
  • Partner-scoped metrics, reports, team management and websites.

Operations and quality

  • Six test tiers: unit, integration, API, penetration, end-to-end and coverage.
  • Runtime invariant checker for impossible states in live data.
  • Distributed tracing, Prometheus metrics and error tracking.
  • Configurable alerting with its own event history.

Key modules

Provably-fair core

The trust anchor for every in-house game.

  • Commit–reveal seeds, deterministic derivation, independent verification.
  • Guarded by a build-time rule, not just by convention.

Wallet and transaction taxonomy

Every balance movement has a named, auditable type.

  • Prevents the classic failure where money moves without a reason attached.
  • Underpins reconciliation and reporting.

Affiliate platform

A second product living inside the first.

  • Fifteen modules spanning tracking through payout.
  • Strict data scoping so partners only ever see their own numbers.

Compliance surface

Keeps the operator inside its licence conditions.

  • Identity verification, jurisdiction gating, two-factor authentication.
  • Decisions are snapshotted rather than merely applied.

Presentation approach

How this project is presented

  • Fairness architecture explained in full, since it is the part worth trusting.
  • Module boundaries shown as a map rather than a source listing.
  • Scale figures counted from the repositories.
  • No live instance: a real-money platform is not a demo.

Documentation and notes

Fairness model

Commit–reveal lifecycle, seed rotation and the verification procedure.

Module map

Fifty bounded contexts and the boundaries between money, game and marketing.

Transaction taxonomy

The named categories every balance movement must belong to.

Test strategy

What each of the six test tiers is responsible for catching.
  • Operator and brand names are intentionally omitted; this is an engineering record.
  • The fairness guarantee depends on seeds being committed before play — that ordering is the whole mechanism.
  • Scale figures are counted from the repositories, not estimated.
All 21 engineering notes