Technical details —Shop Portal

Stack & holistic thinking

Before reading the code, understand the 6 most "different" features of this app - especially compared to the Kiosk Frontend app (Next.js) described in report 02. Once you understand them, you will read the code very quickly.

Shop in the B2B chain: Agent → Shop → Cashier → Player

Shop is the intermediate floor:receive credits from Agent(according to exchange rate), yesDistribute credits to Playerat the place of business. Cashier is the operator at the counter. Earning USD comes from the price difference when depositing players.

Directory structuresrc/

Flat folder tree in CRA style. Convention: page PascalCase inpages/, shared components incomponents/, no alias@/*— import using relative path.

Startup Screen & render model

It is a pure client CRA SPA (no SSR).index.tsx render <App/> in StrictModeand register a service worker (PWA).

Routing & ProtectedRoute

All routes declared flat inApp.tsx. No route group, no nested layout (layout is on each page<AppLayout>). All routes except/loginevenly wrapped<ProtectedRoute>.

const { isAuthenticated, isLoading } = useAuth();
const location = useLocation();

if (isLoading) return <PageLoadingIndicator variant="section" />;  // wait for session recovery
if (!isAuthenticated)
  return <Navigate to="/login" replace state={{ from: location }} />;
return <>{children}</>;

Login flow & JWT

1-step login: email + password (+ optional Turnstile). JWT token stored in localStorage. Shop sessioncompletely separatewith the Admin system (private key, no cookies shared).

services/api.ts— the brain communicates

A single file exports ~35 async functions, all sharing the same axios client. Components don't call axios themselves — they import specific functions.

const client = axios.create({ baseURL: API_BASE_URL, timeout: 15000 });

client.interceptors.request.use((config) => {
  const token = localStorage.getItem(STORAGE_KEYS.AUTH_TOKEN);
  if (token) config.headers.Authorization = `Bearer ${token}`;
  return config;
});

client.interceptors.response.use((res) => res, (error) => {
  if (error.response?.status === 401)
    window.dispatchEvent(new Event('auth:unauthorized'));
  return Promise.reject(error);
});

The main endpoint group (prefix base already exists/api)

State management & Synchronize via custom events

Because there is no global store, the app uses itDOM CustomEventcreate an "event bus" so that non-parent-child components can update at the same time (especially wallet balance).

Look up players by phone number — 4 statuses

The business core lies inShopPlayerLinkByPhonePanel.tsx— common to the "Create player" modal (flow="create") and "Transfer from another shop" (flow="transfer"). User enters phone (viareact-phone-number-input), click lookup, the server returns one of 4 statuses to decide the next action.

Two OTP streams: registration vs transfer

OTP ensures the player's consent before changing the shop assignment. The same panel manages two streams using variablesotpFlowMode ('registration' | 'transfer') with 2 different ids:registrationIdortransferId.

OTP Channel & verify (flow create only)

When creating a player, you can choose a channelsmsoremail(if email → email is required). After successful verification at flow registration, if response is returneddata.playerthen callonLinkedPlayer()to navigate to the details page. With flow transfer, the panel remainslookup againphone to pick upplayerIdnew then navigation.

Credit wallet, cost rate & ledger

The shop's wallet is calculated incredits. The balance is shown in the sidebar (AppLayout) and 4 Dashboard stat cards. All fluctuations read fromGET /shop/transactionsand is "presented" via internal helperutils/shopWalletLedger.ts.

// Match backend normalizeLedgerMetadata: metadata can be JSON string, snake_case
export function normalizeMeta(raw: unknown): Record<string, unknown> {
  let m: unknown = raw;
  if (typeof m === 'string') { try { m = JSON.parse(m); } catch { return {}; } }
  const o = { ...(m as Record<string, unknown>) };
  if (o.player_phone != null) o.playerPhone = o.player_phone; // normalize keys
  return o;
}

ShopCreditPurchaseModal & payment provider

The dark UI page allows the shop to buy more credits from the platform. Enter number of credits → calculate estimated USD → select method → ​​create order → receivepaymentUrlembed iframe.

Configure subdomain for location

Each shop has a kiosk URL formlabel.<base>. KioskDomainPageThere are 3 statuses: not yet available (created), available (read-only + Edit), under editing.

// Separate label from FQDN: "mystore.kioskgaming.com" + base "kioskgaming.com" → "mystore"
function subdomainLabelFromFqdn(fqdn: string, base: string): string {
  const suffix = `.${base}`;
  if (base && fqdn.endsWith(suffix)) return fqdn.slice(0, -suffix.length);
  return fqdn.split('.')[0] || '';
}

Broadcast bell & in-app popup gate

Medium shopreceiveNotification from Admin/Agent (bell + popup), mediumsendNotification to player (broadcast + popup).

Tailwind 3 + workspace packages

Different from kiosk frontend (Tailwind v4 without configuration), this app uses itTailwind 3.2 has a config filewith HSL color token declared insideindex.css. The main tone is emerald (primary160 84% 39%).

@tailwind base; @tailwind components; @tailwind utilities;

@layer base { :root {
  --primary: 160 84% 39%;   /* emerald — used via hsl(var(--primary)) */
  --border: 160 10% 90%; --radius: 0.5rem;
} }

// tailwind.config.js — content scans the built ui package
content: ['./src/**/*.{js,jsx,ts,tsx}', '../packages/ui/dist/**/*.js']

Config & environment variable

Read through with concentrationsrc/config/env.ts. Variables must have a prefixREACT_APP_(CRA convention). Available.env.example.

Testing & build

Test infrastructure is CRA's default (react-scripts test= Jest + RTL) butThere are no test files yet in src/. Build usesreact-scripts build (CRA Havetypecheck — else kiosk frontend ignores TS errors).

npm start    # react-scripts start → http://localhost:3004 (PORT)
npm run build  # react-scripts build (with typecheck)
npm test     # react-scripts test — currently no test cases
npm run eject  # ⚠️ should not be used

Cookbook for new devs

Common tasks follow project conventions.

Common traps (read before fixing)