System Overview
KioskGaming is a multi-tier gaming kiosk platform. It is built around a central backend served by a set of specialized frontends, each targeting a distinct role in the business hierarchy.
Components
| Component | Description |
|---|---|
| Backend | Single API server. All frontends communicate exclusively through this backend. |
| Admin | Internal panel. Used by the platform operator to manage the entire system. |
| Super Agent | Web portal for super agents. Manages agents under their account. |
| Agent | Web portal for agents. Manages shops under their account. |
| Shop | Web portal for shop owners. Manages players and kiosk terminals in their shop. |
| Player | Web and kiosk interface for end users. Used to play games and manage balances. |
Role Hierarchy
Accounts in KioskGaming follow a strict top-down hierarchy. Each level can only create and manage accounts directly below it.
┌─────────────────────────────────────────────────┐
│ ADMIN │
│ Platform operator (internal) │
└──────────────────────┬──────────────────────────┘
│ creates
┌──────────────────────▼──────────────────────────┐
│ SUPER AGENT │
│ Regional distributor / partner │
└──────────────────────┬──────────────────────────┘
│ creates
┌──────────────────────▼──────────────────────────┐
│ AGENT │
│ Local reseller / operator │
└──────────────────────┬──────────────────────────┘
│ creates
┌──────────────────────▼──────────────────────────┐
│ SHOP │
│ Physical gaming kiosk location │
└──────────────────────┬──────────────────────────┘
│ creates
┌──────────────────────▼──────────────────────────┐
│ PLAYER │
│ End user │
└─────────────────────────────────────────────────┘
Role Descriptions
Admin
The platform operator. Has full visibility and control over all accounts, transactions, and configuration. Accesses the system through the Admin panel. Creates super agent accounts directly.
Super Agent
A regional distributor or business partner. Responsible for recruiting and managing agents within their territory. Creates agent accounts through the Super Agent portal.
Agent
A local reseller or kiosk operator. Responsible for managing one or more shops. Creates shop accounts through the Agent portal.
Shop
A physical gaming kiosk location. Manages the kiosk terminals and players registered at that location. Creates player accounts through the Shop portal.
Player
An end user who plays games on the platform. Players can be created in two ways:
| Method | Who initiates | Account type |
|---|---|---|
| Shop registration | Shop owner creates the account | Managed player |
| Self-registration | Player signs up on the public web | Free player |
Free players (self-registered) and managed players (created by a shop) are the same account type. The distinction is only in how they were onboarded.
How the Frontends Connect
All frontends are stateless web applications. They communicate with the backend exclusively over HTTPS. There is no direct communication between frontends.
Admin Portal ──┐
Super Agent ──┤
Agent Portal ──┼──► Backend API ──► PostgreSQL
Shop Portal ──┤ └──► Redis
Player Web ──┘
The backend enforces role-based access on every request — a shop portal session cannot access agent-level endpoints, and so on down the hierarchy.
Player Registration Flows
Flow 1 — Shop creates a player
Shop owner logs in to Shop Portal
│
▼
Creates a player account (name, credentials)
│
▼
Player receives credentials and logs in to Player Web / kiosk
Flow 2 — Player self-registers
Player visits the public Player Web
│
▼
Fills in registration form (email or phone)
│
▼
Account is created as a free player (not linked to a specific shop)
Free players can later be associated with a shop by an agent or admin if needed.