Technical details —Agent Portal

Stack & holistic thinking

This app is completely different from the kiosk frontend (Next.js): this is oneB2B management SPAruns on Create React App. Know these six characteristics before reading code — they explain most of the structure.

Directory structuresrc/

Clear layering:pages/(destination route) →components/ (by domain) → services/ + hooks/ + utils/. Two central files:services/api.tsandtypes/index.ts.

Route map & route protection

App.tsxuseBrowserRouter + Routes. All business routes are wrapped internally<ProtectedRoute>; only/loginis public. Catch-all*and/purchaseevenNavigateabout/.

const { isAuthenticated, isLoading } = useAuth();
if (isLoading) return <PageLoadingIndicator variant="section" />;  // wait to read localStorage
if (!isAuthenticated)
  return <Navigate to="/login" replace state={{ from: location }} />;
return <>{children}</>;

Login flow & JWT

1-step login (email + password, no need for email code like kiosk). Token and profile saved in localStorage;AuthProviderinitialize the state from there when opening the app.

services/api.ts— the brain communicates

OneAxiosInstanceUniquely, each endpoint is an export function. Request interceptor attaches token itself; response interceptor catches 401.Are notThere is an intermediate service layer like kiosk — page/component that calls these functions directly.

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);
});

Full endpoint table (prefix base/api)

types/index.ts— shape data domain

The most important type revolves around wallet and cost. Note that many fields have both camelCase and snake_case because the backend returns inconsistently — the code must guard against both.

interface AgentProfile {
  id: string; email: string; name: string; status: string;
  costRate?: number;          // agent's purchase rate (0–1)
}

interface AgentDashboardData {
  credit_balance: number; active_shops_count: number;
  low_balance_warning_enabled?: boolean; /* ... popup permission flag ... */
}

interface AgentWalletLedgerEntry {      // 1 line /agent/transactions
  id: string; type: string; amount: number | null;
  direction: 'in' | 'out' | 'unknown';
  counterparty: { ownerType: string; ownerId: string } | null;
  costRate?: number; costAmount?: number;   // commission written in each line
  platformFeeRate?: number; platformFeeAmount?: number;
  createdAt?: string; created_at?: string;   // ⚠ both types
}

interface AgentShop {
  id: string; name: string; status: AgentShopStatus;
  costRate?: string | number;          // ⚠ string OR number
  minShopCostRateExclusive?: number; // cost shop must be > this level
}

costRate & commission — Agent's commission model

This is the most important concept of repo. Agents make money thankscost rate difference: buy cheap credits (according toagentCostRate), delivered to the shop at a more expensive price (according toshopCostRate). The difference is the commission.

# When AGENT BUY credits from the platform:
estimatedCharge (USD) = credits × agentCostRate
                        # e.g. 100 credit × 0.30 = pay 30 USD to provider

# Khi AGENT GIAO credit for shop:
cashShopOwesAgent (USD) = credits × shopCostRate
                        # e.g. 100 credit × 0.50 = shop owes agent 50 USD

# ⇒ agent PROFIT / 100 credits:
margin = credits × (shopCostRate − agentCostRate)   # = 100 × (0.50 − 0.30) = 20 USD

utils/costFormat.ts— conversion % ⇄ rate

// rate (0.05) → display "5%" (Intl.NumberFormat style:'percent')
export function formatCostRate(raw: string|number|null|undefined): string

// input "5" (user types %) → rate 0.05, clamp [0,100]
export function percentInputToRate(percentStr: string): number {
  const pct = parseFloat(percentStr);
  return Math.min(100, Math.max(0, pct)) / 100;
}

CreditPurchaseModal — buy credits from the platform

Full screen modal (components/credits/CreditPurchaseModal.tsx). User enters numbercredits want to receive, choose the method, the system estimates the amount to be paid, then creates an order and embeds the provider payment page.

Mapping UI → API methods

export const ECASH_APP_ALLOWED_AMOUNTS = [25,31,40,50,60,100,125,130,150,200,300,400,500];

export function mapUiPaymentIdToAgentPaymentMethod(id: string) {
  if (id.startsWith('zerox_')) return id;   // zerox_usdt, zerox_btc...
  return { btcpay: 'btc_onchain', ltc_btcpay: 'ltc_chain',
           doge_btcpay: 'doge_chain', py_usd: 'pyusd',
           cashapp: 'ecash_app' }[id] ?? id;
}

SellCreditsCashToShopTrigger — cash-credits flow

Instead of the old "free" credit distribution, agents sell credits viaPOST /agent/shops/:id/cash-credits. UI usedSellCreditsCashModalfrom@kioskgaming/ui.

// Payload: credits, payment_method?, received_at?, note?
await createShopCashCredits(shopId, { credits: 100, payment_method: 'cash' });
// → record cash-transaction + subtract agent credit + add shop credit

Lifecycle & shop's governance

ShopsPage(list + create) andShopDetailPageRedesign(details) is where the agent exercises full CRUD authority on his shop, including setting prices (cost), resetting passwords, turning on games and managing status.

ShopGovernanceModal— confirm dangerous action

UseModalfrom@kioskgaming/uiwithvariant='delete'for terminate ("irreversible" red warning) andvariant='confirm'for suspend (yellow warning). CallbackonConfirmSuspend/TerminatepayPromise<boolean>; Only close the modal when successful.

Wallet History &agentWalletLedger.ts

AgentTransactionsPageUse hooksuseAgentTransactions({page, limit})(default limit 25) call/agent/transactions. Because the shape ledger is complex, all display logic is combinedutils/agentWalletLedger.ts.

Players — read only

Agent Are notcreate/edit/delete player.PlayersPage (/agent/players) lists all players from all shops;AgentPlayerDetailPage + AgentPlayerDetailPanelshow profile + balance + wallet history (/agent/players/:id/transactions).

Two separate notification systems

Easy to mistake: the app does2 different mechanismswith different endpoints. One is a notification bell (not blocked), the other is a popup that blocks the screen.

Markup link in broadcast

utils/broadcastLinkMarkup.tsparse syntax<link>label|https://...</link>into a secure text/link segment (only accepts http/https viasanitizeBroadcastUrl). BroadcastMessageBody.tsxrender result — common to both bell and popup gate.

Styling, config & build

Tailwind v3 Haveconfig file (different from kiosk v4), incorporating the HSL token design of the shared UI package. Config app wrapped inconfig/env.ts + constants/index.ts.

Cookbook for new devs

Common tasks follow repo conventions.

Common traps (read before fixing)