Backend · Deep dive · dev branch

Techniquedetail

Bootstrap composition root, biz/core/infra layer, 4 payment gateways, 22 game adapters, RabbitMQ + masterWorker. Read later01-backend.html.

bootstrap/ 58 biz · 48 core · 58 infra 45 repositories 16 workers

01 — Structure

Directory tree`src/`

kioskgaming_backend/ ├── src/server.js ← entry: buildAppWithRoutes + startWorkers ├── src/bootstrap/ ← composition root │ ├── index.js, database.js, repositories.js │ ├── services.js, app.js, routes.js, workers.js ├── controllers/ admin/ agent/ shop/ user/ … ├── routes/ 59 route files │ ├── users/ admin/ payment/ kiosk/ │ ├── agent.js shop.js superAgent.js cashier.js │ └── *Auth.js portalAuth.js ├── middleware/ JWT, RBAC, request signing, domain ├── repositories/ 45 repository classes ├── services/ │ ├── biz/ 58 orchestration services │ ├── core/ 48 domain + repository access │ ├── infra/ 58 integrations (email, wallet, fraud…) │ ├── payment/ deposit/withdrawal adapters, webhooks │ ├── gameProviderAdapters/ 22 game adapters + baseProvider │ ├── queues/ retryQueue, rabbitmqProducer, gameWalletSyncQueue │ └── outbound/ outbound queue payloads ├── database/models/ 78 Sequelize models ├── workers/ 16 background workers ├── thirdpartyapi/ low-level HTTP clients per provider ├── modules/cashier-management/ cashier domain module └── utils/ redis, rabbitmq, logger, caches ├── scripts/architecture/ checkLayering.js, violation inventory ├── tests/unit/ (148) · tests/integration/ └── stress-test/ load test v1/v2 + scenarios

02 — Lifecycle

Request lifecycle via bootstrap

server.js

buildAppWithRoutes() → startWorkers(db) → listen PORT (default 3001). Graceful shutdown: SIGTERM/SIGINT → stopWorkers().

bootstrap/database.js

Sequelize connect, load 78 models, associations. UTC timezone (process.env.TZ = 'UTC').

bootstrap/repositories.js + services.js

Wire 45 repositories into core/infra services; biz services receives core/infra dependencies via setter injection.

bootstrap/app.js

Express + helmet + cors (DB-driven origins + DEV_ORIGINS) + compression + morgan + rate limiters + language middleware.

bootstrap/routes.js

mountRoutes: inject models/services into controllers, mount ~40 route groups,errorHandlerFinal.

Controller → Biz → Core → Infra

Controller not calledglobal.dbarchitecture lint. Transaction boundaries are usually in biz or infra wallet services.

src/bootstrap/index.jsjs
async function buildAppWithRoutes() {
  const db = await initDatabase();
  const repos = createRepositories(db);
  const services = initServices(db, repos);
  const { app, authLimiter, portalAuthLimiter } = buildApp();
  mountRoutes(app, authLimiter, db, repos, services, portalAuthLimiter);
  return { app, db, repos };
}

03 — Layers

Service layer pattern (biz / core / infra)

biz/

Orchestration: validate business input, call multiple cores/infra, emit events. For example:agentCreditPurchaseBizService.js, paymentTransactionBizService.js.

core/

Domain access via repository — CRUD + query for 1 aggregate. For example:paymentTransactionCoreService, userCoreService.

infra/

Side effects & integrations: email, SMS, telegram, wallet transfer, game sync, fraud. For example:walletService, gameWalletSyncService.

repositories/

Sequelize queries only. Core services call the repository — biz does not import the repository directly (lint rule).

💡

Import rules

Controller → biz/core/infra OK. Biz → core/infra OK. Core → repository OK. Biz → repository = violation. Controller → repository = critical violation.

04 — Payment

Deposit & withdrawal flows (4 providers)

Deposit

depositService.createDeposit()→ select the adapter viagetDepositAdapter(provider)
Adapters: linkMePayDepositAdapter, btcPayDepositAdapter, zeroxProcessingDepositAdapter, meldDepositAdapter
Webhook routes: /api/payment/linkmepay/*, /btcpay/webhook, /zeroxprocessing/webhook, /meld/webhook
depositCallbackService + paymentWebhookShared: verify, idempotency, credit wallet, transaction state machine

Withdrawal

withdrawalApprovalService — admin/portal approve → getWithdrawalAdapter()
Adapters: LinkMePay, BTCPay, 0xProcessing (Meld does not support withdrawal)
Payout status poll: btcPayPayoutStatusWorker, zeroxProcessingPayoutStatusWorker in masterWorker
Portal USD withdrawal: portalUsdWithdrawalPayoutService + OTP via withdrawalOtpService

src/services/payment/depositAdapters/index.js
const ADAPTERS = {
  btcpay: btcPayDepositAdapter,
  linkmepay: linkMePayDepositAdapter,
  zeroxprocessing: zeroxProcessingDepositAdapter,
  meld: meldDepositAdapter
};

05 — Adapters

Adapter patterns

PaymentDeposit / Withdrawal registry

Factory functions getDepositAdapter / getWithdrawalAdapter — validate contract (paymentUrl, externalTransactionId) fail-fast.

GamegameProviderAdapters registry

AdapterRegistry.getAdapter(code)— alias map (firekirin→fkterminal), load config from GameProvider model (strip sensitive fields), instantiate adapter class.

22 adapters + baseProvider.js fallback for vegas/apex/valor/mythic/arcadia.

Third-partythirdpartyapi/

Low-level HTTP clients (bluedragon, gamevault, jack2win, megaspin…). Adapter calls thirdpartyapi, logs throughgameProviderApiLogService.

06 — Auth

Auth & JWT (multi-portal)

Actor	Secret	Session table	Notes
Kiosk player	`JWT_SECRET`	UserSession	Refresh token rotation, phone/email OTP
Admin	`ADMIN_JWT_SECRET` (super: `SUPER_ADMIN_JWT_SECRET`)	AdminSession	Email OTP 2FA before issuing tokens
Agent / Shop / SuperAgent	`JWT_SECRET`	AgentSession / ShopSession / SuperAgentSession	Portal login 2FA, email verify gate writes
Cashier	Module-specific	CashierSession	`modules/cashier-management/middleware/`
Kiosk device	Request signing HMAC	—	`REQUEST_SIGNING_SECRET` for `/api/kiosk/*`

Shared flows: /api/portal-auth (forgot password), portalLogin2faService, portalCredentialNotifyServiceuseportalSiteUrl.jsto build links by role.

07 — Database

Database models (78)

Sequelize models in src/database/models/. Migrations: npm run migrate. Partitioned tables: wallet transactions — npm run partition:list.

User & Session

User
UserSession
UserGameAccount
UserGameWallet
PasswordReset
PasswordChangeHistory
AccountOtp
EmailCode
PhoneCode

Wallet & Ledger

Wallet
WalletTransaction
UsdWallet
UsdWalletTransaction
UsdWalletReservation
GameWalletTransaction
ZeroxStaticWallet

Payment

PaymentTransaction
PaymentApiLog
PaymentProviderFeeConfig
CallbackLog
TransactionStep
TransactionEvent
TransactionFraudFlag

Hierarchy B2B

Agent
AgentSession
AgentGameMapping
SuperAgent
SuperAgentSession
SuperAgentGameMapping
Shop
ShopSession
ShopGameMapping
ShopActionLog
CommissionLog

Cashier

Cashier
CashierSession
CashierDevice
CashierDeviceAccess
CashierShift
CashierShiftHandover
CashierShiftAdjustment
CashierTransaction
CashierCashDrop
CashierAuditLog
CashierRedemptionApproval
CashDenominationCount

Cash & CDN

CashTransaction
CashTransactionEvent
OnlineDebtSettlement
OnlineDebtSettlementLine
PlayerTransferLog

Game & Domain

GameProvider
GameProviderApiLog
GameAgentBalance
Domain
DomainGameMapping
KioskHeartbeat

Admin & Support

Admin
AdminSession
AdminOTP
AdminPermission
Permission
AdminActionLog
AdminLoginLog
AdminBroadcast
SupportTicket
TicketReply

Ops & Config

TransactionLimitsConfig
VfxConfiguration
VfxConfigSchedule
InAppPopup
ReconciliationReport
GamifyRewardWebhookLog

08 — Workers

Queue & background workers

RabbitMQ (khi RABBITMQ_ENABLED ≠ false)

emailQueueWorker, smsQueueWorker, telegramQueueWorker, lowBalanceCheckQueueWorker
Producer: services/queues/rabbitmqProducer.js

masterWorker (60s tick, Redis lock)

retry — retryWorker.processRetryQueue + services/queues/retryQueue.js
deposit_timeout / withdrawal_timeout — pending transaction cleanup
btcpay_payout / zerox_payout — poll external payout status
agent_balance_sync — sync game agent balances
expired_data_cleanup — sessions, email/phone codes (daily)
player_inactivity_spike — fraud detection

Standalone workers

cashierManagementWorker, lowBalanceDailyWorker, dailyStatsReportWorker, reconciliationWorker, agentBalanceSyncWorker

Game wallet async: gameWalletSyncQueue— decouple provider latency from HTTP response.

09 — CI

Architecture lint scripts

npm run lint              # ESLint biz/core/infra + scripts/architecture
npm run architecture:inventory   # regenerate violation baseline
npm run architecture:check       # fail CI if NEW violations vs baseline
npm run ci:backend        # lint + architecture:check + jest

Scanner: scripts/architecture/scanArchitectureViolations.js — detect controller→repository, biz→repository, cross-layer imports. Baseline: architecture/architecture-violation-baseline.json.

10 — Cookbook

Instructions for new developers

AAdd API endpoint

Create biz service inservices/biz/
Core service + repository if new DB is needed
Controller calls biz — do not query DB directly
Route in routes/, mount in bootstrap/routes.js
Wire dependencies in bootstrap/services.jsif new service

BAdd payment provider

Create deposit adapter (+ withdrawal if any) inservices/payment/
Register indepositAdapters/index.jsand/orwithdrawalAdapters/index.js
Webhook handler in paymentUserController + route payment.js
Env vars + PaymentProviderFeeConfig seed

CAdd game provider

HTTP client in thirdpartyapi/myprovider/
Adapter extend baseProvider.js in gameProviderAdapters/
Register in gameProviderAdapters/index.js
Insert GameProvider record (code, config, gameUrl)

DRun locally

npm install && cp .env.example .env
npm run migrate          # DB migrations
npm run dev              # nodemon src/server.js
npm run ci:backend       # lint + architecture + tests
curl http://localhost:3001/health

11 — Gotchas

Common errors

Symptom	Reason	Fix
Service undefined model	Not wired in bootstrap/services.js	Add setRepository/setModels in initServices()
architecture:check fail	Imported the wrong new floor	Move logic down to core/infra; Do not import repository from biz
Webhook double credit	Idempotency bypass	Check CallbackLog + syncMetadata.walletCreditedAt
Portal JWT invalid	Wrongly used ADMIN_JWT for portal	Agent/shop/super-agent uses JWT_SECRET + correct session table
RabbitMQ workers are not running	RABBITMQ_ENABLED=false or broker down	Check RABBITMQ_URL; fallback sync in some infra services
CORS blocked	Origin is not yet in the Domain table	Admin → Domains or add DEV_ORIGINS in bootstrap/app.js
0x/BTCPay payout stuck	Poll worker disabled	ZEROX_PAYOUT_POLL_ENABLED / BTCPAY_PAYOUT_POLL_ENABLED + API keys
Game sync timeout	Provider is slow	Job into gameWalletSyncQueue; check GameProviderApiLog

Techniquedetail

Directory treesrc/

Request lifecycle via bootstrap

Service layer pattern (biz / core / infra)

Deposit & withdrawal flows (4 providers)

Deposit

Withdrawal

Adapter patterns

Auth & JWT (multi-portal)

Database models (78)

User & Session

Wallet & Ledger

Payment

Hierarchy B2B

Cashier

Cash & CDN

Game & Domain

Admin & Support

Ops & Config

Queue & background workers

RabbitMQ (khi RABBITMQ_ENABLED ≠ false)

masterWorker (60s tick, Redis lock)

Standalone workers

Architecture lint scripts

Instructions for new developers

Common errors

Directory tree`src/`