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
Styling	Tailwind CSS 3 + CSS variables
HTTP	Axios 1.3
Forms	react-hook-form 7
Toast	react-hot-toast
Icons	lucide-react
CAPTCHA	@marsidev/react-turnstile
QR / Phone	qrcode, react-phone-number-input
Monorepo	@kioskgaming/ui, @kioskgaming/page-loading
PWA	Service worker (không Capacitor)

---

Cấu trúc thư mục

kioskgaming_superagent/
├── src/
│   ├── index.tsx
│   ├── App.tsx
│   ├── config/env.ts
│   ├── constants/index.ts
│   ├── types/index.ts
│   ├── services/api.ts
│   ├── hooks/                    # useAuth, ledger, zerox methods
│   ├── pages/
│   ├── components/
│   │   ├── auth/
│   │   ├── layout/               # AppLayout
│   │   ├── credits/              # Mua/phân phối/rút credit
│   │   ├── dashboard/            # HierarchyMiniTree
│   │   ├── finance/
│   │   └── shops/
│   └── utils/
├── public/                       # SPA fallback, manifest, sw.js
├── craco.config.js
├── vercel.json
└── package.json

---

State management

Pattern	Vị trí	Mục đích
React Context	hooks/useAuth.tsx	Auth state
Local useState	Pages/components	UI state
Custom hooks	useAgentTransactions, useSuperAgentOnlineBalanceLedger	Data fetching
localStorage	agent_auth_token, agent_user_data	Persist auth
Custom Events	agent-auth-token-changed, auth:unauthorized	Cross-component sync

note

Storage keys dùng prefix agent_ (legacy naming) dù đây là Super Agent portal.

---

Biến môi trường

Biến	Default	Mô tả
REACT_APP_API_BASE_URL	http://localhost:3001/api	Backend API
REACT_APP_TURNSTILE_ENABLED	false	Cloudflare Turnstile
REACT_APP_TURNSTILE_SITE_KEY	''	Site key
REACT_APP_APP_NAME	Kiosk Gaming — Agent	Tên app
PORT	3003	Dev server port

Backend cần AGENT_FRONTEND_URL (hoặc URL super agent tương ứng) cho payment return /payment/return.

---

Deploy

File	Platform
vercel.json	Vercel SPA rewrite
public/_redirects	Netlify / Cloudflare Pages
public/.htaccess	Apache
public/web.config	IIS

Không có Capacitor — web SPA/PWA thuần.

---

Sơ đồ tổng quan

flowchart TB
  subgraph Client["kioskgaming_superagent"]
    App[App.tsx] --> Auth[AuthProvider]
    Auth --> Router[React Router]
    Router --> Protected[ProtectedRoute + Pages]
    Protected --> Layout[AppLayout]
    Layout --> API[services/api.ts]
  end

  subgraph Backend["kioskgaming_backend"]
    API -->|Bearer token| SA["/super-agent/*"]
    API --> AuthAPI["/super-agent-auth/*"]
  end