KioskGaming Backend — Technical Report (2026-06-24)

Business overview

kioskgaming_backendis the root composition for the entire platform — 6 frontend apps (kiosk player, admin, agent, super agent, shop, cashier) and kiosk heartbeat calling into REST API on port 3001. Current codebase on branchdevUse layered architectureroutes → controllers → biz → core → infra → repositories → PostgreSQL, initialize viasrc/bootstrap/.

🔐

Multi-portal authentication

JWT for player (JWT_SECRET), admin OTP 2FA (ADMIN_JWT_SECRET), agent/shop/super-agent/cashier portal auth + shared /api/portal-auth (forgot password, login 2FA).

💰

Online payment

4 gateway: LinkMePay, 0xProcessing, BTCPay, Meld — deposit/withdrawal adapter registry, webhook verify, idempotency via CallbackLog.

🎮

22 Game providers

Adapter registry in gameProviderAdapters/ — credit/debit/sync balance, GameProviderApiLog audit, retry queue + masterWorker reconciliation.

🏪

B2B hierarchy

Super Agent → Agent → Shop → Player; Cashier separate module for cash counter; USD wallet + credit ledger for each portal level.

📨

Async messaging

RabbitMQ workers (email, SMS, Telegram, low-balance check) + masterWorker tick 60s (retry, timeout, payout poll, agent balance sync).

🛡️

Architecture lint

npm run architecture:checkPrevent layering violations (controller → direct repository, biz import on wrong layer). CI: lint + architecture + jest.

Layered architecture

All requests go through the bootstrap composition root — no more direct internal mount routesserver.js.

HTTP Request → helmet · cors · rateLimit · language · domainMiddleware

↓

routes/ — URL + middleware + controller

↓

controllers/— parse input, call biz service

↓

services/biz/— orchestration, business validation (58 files)

↓

services/core/ — domain CRUD via repository (48 files)

↓

services/infra/ — email, telegram, wallet, fraud, sync (58 files)

↓

repositories/ (45) → PostgreSQL · Redis cache/lock · RabbitMQ

src/bootstrap/index.js — buildAppWithRoutes()

initDatabase() → createRepositories(db) → initServices(db, repos)
→ buildApp() → mountRoutes(app, …) → startWorkers(db)

Payment providers

Deposit adapters: getDepositAdapter() in services/payment/depositAdapters/. Withdrawal adapters: getWithdrawalAdapter() in withdrawalAdapters/. Webhook routes mount at/api/payment/*.

Provider	Type	Ability	Webhook / Worker
LinkMePay `linkmepay`	Fiat link / eCash	Deposit, Withdrawal	IPN + payout IPN webhooks
0xProcessing `zeroxprocessing`	Crypto multi-coin	Deposit, Withdrawal	Webhook + static wallet + payout poll worker
BTCPay Server `btcpay`	Bitcoin / Lightning	Deposit, Withdrawal	Webhook + payout poll worker
Meld `meld`	Fiat on-ramp	Deposit only	Webhook on-ramp completion

Deposit flow (summary)

POST /api/payment/deposit

depositServicecreate PaymentTransaction pending, call deposit adapter → pay paymentUrl/address.

Provider webhook

depositCallbackService verify signature, ghi CallbackLog, idempotency check, credit wallet in DB transaction.

Notify + retry

Telegram/email via RabbitMQ; temporary error →retryQueue + masterWorker retry task.

Game providers (21 adapters)

Registry: src/services/gameProviderAdapters/index.js— per adapter extensionbaseProvider.js, map alias (firekirin→fkterminal, juwa→gamevault…).

BlueDragon

bluedragon

REST sweepstakes API

Cashier

cashier

Vegas X / in-person terminal

Vegas7Games

vegas7games

Vegas X API variant

FKTerminal

fkterminal

alias: firekirin

PMTerminal

pmterminal

alias: pandamaster

MWTerminal

mwterminal

alias: milkyway

OSTerminal

osterminal

alias: orion

GameVault

gamevault

alias: juwa

Jack2Win

jack2win

vblink777, egame99, ultrapanda…

OpenJack2Win

openjack2win

Open API jack2.win

LasVegasSweeps

lasvegassweeps

Sweepstakes

River Pay

riverpay

River payment terminal

CashFrenzy

cashfrenzy

Terminal API

GameRoom

gameroom

Game room terminal

MrAllInOne

mrallinone

Multi-game terminal

VegasRoll

vegasroll

Roll games

Mafia77777

mafia77777

Slot terminal

MegaSpin

megaspin

MegaSpin Pay terminal

Galaxy World

galaxyworld

Galaxy terminal

Glamor Spin

glamorspin

FastAPI provider

Noble777

noble777

Noble777 terminal

B2B portal APIs

Portal	Auth prefix	API prefix	Main function
Agent	`/api/agent-auth`	`/api/agent`	Dashboard, shops/players, credit purchase/distribute, USD withdrawals + OTP, cash settlement, ZeroX static wallets, broadcasts
Super Agent	`/api/super-agent-auth`	`/api/super-agent`	Manage agents, credit distribution, USD ledger, portal withdrawal limits, hierarchy stats
Shop	`/api/shop-auth`	`/api/shop`	Kiosk subdomain, player transfer/deposit, credit purchase, fraud indicators, cash transactions, provider fees
Cashier	`/api/cashier-auth`	`/api/cashier`	Shift management, cash in/out, device access, redemption approval (`modules/cashier-management/`)
Shared portal	`/api/portal-auth`	—	Forgot password, login 2FA (`portalLogin2faService`), credential notify emails
Admin	`/api/admin-auth`	`/api/admin/*`	RBAC 4 roles, payment approval, CDN agents/shops/players, finance corrections, monitoring

Important environment variables

.env — commonly used variable group (see full .env.example)

# Core
PORT=3001 NODE_ENV DB_HOST/DB_PORT/DB_NAME/DB_USER/DB_PASS
JWT_SECRET ADMIN_JWT_SECRET SUPER_ADMIN_JWT_SECRET
REDIS_URL RABBITMQ_URL RABBITMQ_ENABLED

# Payment
ZEROX_PROCESSING_* BTCPAYSERVER_* LinkMePay credentials MELD_*

# Portal URLs
AGENT_SITE_URL SUPERAGENT_SITE_URL SHOP_SITE_URL CASHIER_SITE_URL ADMIN_SITE_URL

# Security / ops
REQUEST_SIGNING_SECRET TELEGRAM_BOT_TOKEN CF_API_TOKEN (Cloudflare DNS)
MASTER_WORKER_INTERVAL_MS=60000 ZEROX_PAYOUT_POLL_ENABLED BTCPAY_PAYOUT_POLL_ENABLED

Details bootstrap, workers, cookbook →01-backend-detail.html

Route map (summary)

Prefix	Describe	Auth
`/api/auth`, `/api/users`, `/api/wallet`	Player kiosk	JWT_SECRET
`/api/payment`	Deposit/withdraw + webhooks	JWT / signature
`/api/game-wallet`, `/api/game-providers`	Game wallet sync	JWT
`/api/kiosk/*`	Heartbeat, info, win ticker	Request signing
`/api/admin/*`	Platform admin	ADMIN_JWT + RBAC
`/api/agent`, `/api/shop`, …	B2B portals	Portal JWT + session
`/health`	Health check	Public