Skip to main content

System Overview

Status​

Active

Date​

2026-04-28

Owners​

  • Platform Backend

Last Verified Commit​

3f36e7a8

Goal​

Describe the current RGB backend topology, the servers_v2 target runtime, and the migration posture between legacy servers/ and servers_v2/.

Repo Runtime Layers​

The repo currently contains four important runtime layers:

  • web/
    • player-facing web clients
  • bo/
    • back-office and agent-facing frontends
  • servers/
    • legacy Python backend services
  • servers_v2/
    • target backend runtime built around service ownership, contracts, workers, and tests

Target Runtime Shape​

servers_v2 is the target backend for the next-stage platform runtime.

Current primary services:

  • gateway
    • player-facing HTTP edge
  • player_service
    • player auth, profile, messages, and public/common data
  • wallet_service
    • single money writer for balances, deposits, and withdrawals
  • game_service
    • provider callbacks and game integration utilities
  • rolling_service
    • rolling lifecycle and wallet-event consumption
  • promotion_service
    • coupon, rebate, cashback, and lossback orchestration
  • agent_service
    • agent-facing portal APIs
  • admin_service
    • back-office edge, top-info websocket, and scheduler-backed operational APIs
  • recon_service
    • SMS automation and reconciliation domain extracted from middle_server

Infrastructure Model​

The current local and target runtime model is:

  • shared PostgreSQL
  • shared Redis
  • shared contracts package: servers_v2/shared/contracts
  • shared DB runtime package: servers_v2/shared/rgb_db
  • one Docker Compose stack for local full-system verification

Several services are intentionally split into API and worker runtimes:

  • wallet_service + wallet_worker

  • rolling_service + rolling_worker

  • promotion_service + promotion_worker

  • agent_service + agent_worker

  • admin_service + admin_worker

  • recon_service + recon_worker

  • player_service + player_worker

player_service runs its outbox loop through the dedicated player_worker; the API process runs with ENABLE_OUTBOX_POLLER: "false".

Entry Surface Summary​

External entry surfaces are intentionally separated by audience:

  • player traffic
    • enters through gateway
  • agent traffic
    • enters through agent_service
  • back-office traffic
    • enters through admin_service
  • provider callbacks
    • enter through gateway, then proxy to loopback-only game_service

Internal service-to-service traffic uses narrowly scoped /internal/* endpoints.

Key Operating Rules​

  • wallet_service is the only money writer.
  • gateway is an edge and compatibility layer, not a domain owner.
  • admin_service is the only back-office HTTP edge for bo/admin.
  • recon_service owns reconciliation state but must not mutate wallet balances directly.
  • worker health must reflect forward progress, not just process liveness.

Multi-Brand Posture​

Per ADR-009, servers_v2 hosts multiple brands on the same runtime:

  • one PostgreSQL, one Redis, one Docker stack
  • brand identity is resolved from the request domain by gateway and forwarded as X-Brand-Id
  • after login, JWT carries brand_id; gateway rejects mismatch between JWT brand and domain brand
  • player identity, wallet topology, wallet state, rolling, promotion, and per-brand configuration are scoped per brand
  • agent is a global entity; the agent_brand join controls which brands an agent can serve
  • game provider credentials are shared across brands; outbound accounts are namespaced as {brand_code}_{account} and reverse-parsed on callback
  • back-office staff identity is intentionally absent in this iteration

Current Migration Posture​

The current target is not "replace every legacy service at once". The posture is staged:

  • player-facing web paths are being absorbed by gateway + domain services
  • agent-facing paths are being absorbed by agent_service
  • provider callbacks are being absorbed by game_service
  • SMS reconciliation is being absorbed by admin_service + recon_service

The main remaining blocker to a full legacy replacement is the residual middle_server scope that is still not fully represented in servers_v2, especially:

  • role and menu management
  • legacy config editing
  • i18n management
  • web rules and FAQ/content management
  • BI push tooling
  • coin-exchange passthrough behavior
  • generic catch-all forwarding behavior

See migration-readiness.md for the current cutover decision.