Kiến trúc & Tech stack

Tech stack

Lớp	Công nghệ
Framework	React 18 + TypeScript 4.9
Build	Create React App 5 + CRACO 7
Routing	react-router-dom v6 (BrowserRouter)
Styling	Tailwind CSS 3 + CSS variables (design tokens)
HTTP	Axios 1.3
Forms	react-hook-form 7
Toast	react-hot-toast
Icons	lucide-react
CAPTCHA	@marsidev/react-turnstile (Cloudflare Turnstile)
QR Code	qrcode
Monorepo	@kioskgaming/ui, @kioskgaming/page-loading

Không có: Redux, Zustand, React Query, Capacitor.

---

Cấu trúc thư mục

kioskgaming_agent/
├── src/
│   ├── index.tsx                 # Entry point, đăng ký Service Worker
│   ├── App.tsx                   # Router + AuthProvider
│   ├── index.css                 # Tailwind + CSS variables
│   ├── config/env.ts             # Biến môi trường tập trung
│   ├── constants/index.ts        # API URL, storage keys, custom events
│   ├── types/index.ts            # TypeScript interfaces
│   ├── services/api.ts           # HTTP client + toàn bộ API functions
│   ├── hooks/                    # useAuth, ledger hooks, zerox methods
│   ├── pages/                    # Route pages
│   ├── components/
│   │   ├── auth/                 # Login, forgot password, ProtectedRoute
│   │   ├── layout/               # AppLayout, AgentPageLayout
│   │   ├── credits/              # Mua credit, phân phối, rút từ shop
│   │   ├── dashboard/            # AgentHierarchyMiniTree
│   │   ├── finance/              # Withdrawal limits panel
│   │   ├── players/              # AgentPlayerDetailPanel
│   │   ├── shops/                # ShopGovernanceModal, status badge
│   │   └── ui/                   # PortalEmptyState
│   └── utils/                    # format, ledger, sanitize helpers
├── public/
│   ├── _redirects                # Netlify / Cloudflare Pages
│   ├── .htaccess                 # Apache SPA fallback
│   └── web.config                # IIS / Azure Static Web Apps
├── craco.config.js
├── tailwind.config.js
└── package.json

Entry points

File	Vai trò
src/index.tsx	Mount React, register Service Worker (production only)
src/App.tsx	Định nghĩa routes, bọc AuthProvider
src/services/api.ts	Layer tích hợp backend (~834 dòng)

---

State management

Không dùng Redux/Zustand. Kiến trúc state:

Pattern	Vị trí	Mục đích
React Context	hooks/useAuth.tsx	Auth state (user, token, login/logout)
Local useState	Mỗi page/component	UI state, form, modal
Custom hooks	useAgentTransactions, useAgentOnlineBalanceLedger, useSupportedZeroxMethods	Data fetching có reload
localStorage	Auth tokens, user data, zerox methods cache (24h TTL)
Custom Events	window.dispatchEvent	Cross-component sync

Custom events

Event	Constant	Khi nào dispatch
agent-auth-token-changed	AGENT_AUTH_TOKEN_CHANGED_EVENT	Login / logout
auth:unauthorized	—	Axios interceptor nhận 401

Storage keys

Key	Nội dung
agent_auth_token	Bearer token agent
agent_user_data	Profile agent (JSON)

---

Authentication flow

sequenceDiagram
  participant U as Agent user
  participant A as Agent Portal
  participant B as Backend

  U->>A: Nhập username/email + password
  A->>B: POST /agent-auth/login
  alt Cần OTP (2FA)
    B-->>A: needsOtp + pendingToken
    U->>A: Nhập OTP
    A->>B: POST /agent-auth/verify-otp
  end
  B-->>A: accessToken + agent profile
  A->>A: Lưu token vào localStorage

• Header: Authorization: Bearer {token}
• 401 → dispatch auth:unauthorized → auto logout
• ProtectedRoute redirect về /login nếu chưa auth

---

Biến môi trường

Biến	Bắt buộc	Mô tả	Default
REACT_APP_API_BASE_URL	Có	Backend API base URL	http://localhost:3001/api
REACT_APP_TURNSTILE_ENABLED	Không	Bật Cloudflare Turnstile	false
REACT_APP_TURNSTILE_SITE_KEY	Khi bật Turnstile	Site key	''
REACT_APP_APP_NAME	Không	Tên app hiển thị	Kiosk Gaming — Agent
REACT_APP_CLIENT_TELEGRAM_SUPPORT_URL	Không	Link Telegram support	—
REACT_APP_CLIENT_ANDROID_APK_URL	Không	Link tải APK Android	—
REACT_APP_CLIENT_IOS_VIDEO_URL	Không	Video hướng dẫn iOS	—
PORT	Không	Dev server port	3003

warning

Backend cần set AGENT_FRONTEND_URL trỏ về origin của app để redirect payment về /payment/success, /payment/cancelled, /payment/error.

---

Scripts npm

Script	Mô tả
npm start	Dev server port 3003 (CRACO)
npm run build	Production build → thư mục build/
npm test	Chạy test (CRACO)

---

Cấu hình đặc biệt

CRACO + Monorepo UI

craco.config.js import configureKioskgamingUi từ ../packages/ui để webpack resolve shared UI package.

Capacitor

Không có — đây là web app thuần, không có native wrapper.

Service Worker (PWA)

• public/sw.js + serviceWorkerRegistration.ts
• Chỉ register khi NODE_ENV === 'production'

Deploy (Static SPA)

File	Platform
public/_redirects	Netlify, Cloudflare Pages — /* → /index.html 200
public/.htaccess	Apache — rewrite non-file routes → index.html
public/web.config	IIS / Azure Static Web Apps

cd kioskgaming_agent
npm install
npm run build
# Deploy thư mục build/ lên static host

Shared UI package

Components dùng chung từ @kioskgaming/ui:

• PortalCreditTransactionsLedger, PortalUsdWalletLedgerTable
• CreditTransactionDetailModal, UsdWalletTransactionDetailModal
• WithdrawOtpStep, WithdrawBlockedAlert
• FormField, Modal, Button, Input, Select, Textarea
• PlayerFraudIndicatorsPanel, SupportDownloadRail

---

Sơ đồ tổng quan

flowchart TB
  subgraph Client["kioskgaming_agent"]
    Index[index.tsx] --> App[App.tsx]
    App --> Auth[AuthProvider]
    Auth --> Router[React Router]
    Router --> Public["/login, /forgot-password"]
    Router --> Protected["ProtectedRoute + Pages"]
    Protected --> Layout[AppLayout]
    Layout --> API[services/api.ts]
  end

  subgraph Backend["kioskgaming_backend"]
    API -->|Bearer token| AgentAPI["/agent/*"]
    API --> AuthAPI["/agent-auth/*"]
    API --> PaymentAPI["/payment/*"]
  end

  subgraph Storage["Browser"]
    Auth --> LS["localStorage: agent_auth_token"]
  end