Kiến trúc & Tech stack

Tech stack

Lớp	Công nghệ
Framework	React 18.3 + TypeScript 4.9
Build	Create React App 5 + CRACO 7
Routing	react-router-dom v6
Server state	React Query v3 (useApi.ts ~2500 dòng)
HTTP	Axios
Forms	react-hook-form
Styling	Tailwind CSS 3 + Radix UI + shadcn-style components
Tables/Charts	@tanstack/react-table, Recharts
Local state	Zustand 5 (ticket search)
Toast	react-hot-toast
CAPTCHA	@marsidev/react-turnstile
Monorepo	@kioskgaming/ui, @kioskgaming/page-loading
Test	Jest, Playwright (e2e, visual)

---

Cấu trúc thư mục

kioskgaming_admin/
├── src/
│   ├── index.tsx / App.tsx
│   ├── config/
│   │   ├── routes.tsx          # Single source of truth — routes + nav
│   │   ├── permissions.ts      # Role/permission matrix
│   │   └── env.ts
│   ├── components/
│   │   ├── auth/               # Login, ProtectedRoute
│   │   ├── layout/             # Layout, Sidebar, Header
│   │   ├── pages/              # 21+ module trang
│   │   ├── ui/                 # shadcn components, data-table
│   │   └── finance/
│   ├── hooks/
│   │   ├── useAuth.tsx
│   │   └── useApi.ts           # React Query hooks
│   ├── services/api.ts         # ~2800 dòng, ~150 methods
│   ├── contexts/BreadcrumbLabelContext.tsx
│   ├── constants/
│   ├── types/
│   ├── utils/
│   └── queryClient.ts
├── scripts/postbuild-spa-fallback.js
├── craco.config.js
└── package.json

Entry points

File	Vai trò
src/index.tsx	Mount React
src/App.tsx	Providers (QueryClient, Auth), route rendering
src/config/routes.tsx	Route config + sidebar metadata
src/services/api.ts	Axios client + tất cả API methods

---

State management

Layer	Công nghệ	Mục đích
Server state	React Query	Cache API, mutations, invalidation
Auth	React Context (useAuth)	User, token, permissions
Forms	React Hook Form	CRUD modals
Ticket search	Zustand	Filter, pagination
Persist	localStorage	admin_auth_token, admin_user_data

Auth flow

1. Khởi tạo từ localStorage
2. Thiếu permissionObjects → gọi GET /admin/manage/me
3. hasPermission() — ưu tiên API permissions > role fallback
4. Logout → queryClient.clear() + xóa localStorage
5. 401 → auth:unauthorized → auto logout

---

Permissions

14 permission codes trong config/permissions.ts:

dashboard, userManagement, transactionManagement, withdrawalManagement, manualGameDepositManagement, ticketManagement, adminManagement, agentManagement, agentPopupPermissionManagement, walletManagement, gameProviderManagement, vfxConfigManagement, transactionLimitsManagement, domainManagement

Một số route có superAdminOnly: true — chỉ system_admin / super_admin.

---

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	Turnstile
REACT_APP_TURNSTILE_SITE_KEY	''	Site key
REACT_APP_API_TIMEOUT	10000	Axios timeout
REACT_APP_APP_NAME	—	Tên app
REACT_APP_PLATFORM_USD_OWNER_ID	—	Optional platform tier UUID

Port dev mặc định: 3000 (CRA default)

---

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

CRACO

• Alias @ → src/
• Webpack patch cho @kioskgaming/ui

Deploy SPA

npm run build   # craco build + postbuild-spa-fallback.js

File	Platform
scripts/postbuild-spa-fallback.js	Copy index.html → 404.html
public/_redirects	Netlify / Cloudflare
public/.htaccess	Apache
public/web.config	IIS
deploy/nginx-spa.conf.example	Nginx

---

Sơ đồ tổng quan

flowchart TB
  subgraph Client["kioskgaming_admin"]
    App[App.tsx] --> Auth[AuthProvider]
    App --> RQ[React Query]
    Auth --> Router[routes.tsx]
    Router --> PR[ProtectedRoute]
    PR --> Layout[Layout + Sidebar]
    Layout --> useApi[useApi hooks]
    useApi --> API[api.ts]
  end

  subgraph Backend["kioskgaming_backend"]
    API --> Admin["/admin/*"]
    API --> Payment["/payment/admin/*"]
    API --> Support["/support/admin/*"]
  end