Architecture & Tech stack

Tech stack

Layer	Technology
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)
Phone input	react-phone-number-input
QR / Poster	qrcode, html-to-image
Date	date-fns
Mobile	Capacitor 7 (Android wrapper, remote URL mode)
Monorepo	`@kioskgaming/ui`, `@kioskgaming/page-loading`

Directory structure

kioskgaming_shop/
├── src/
│   ├── index.tsx                 # Entry point, Service Worker registration
│   ├── App.tsx                   # Router + AuthProvider
│   ├── index.css                 # Tailwind + CSS variables
│   ├── config/env.ts             # Centralized environment variables
│   ├── constants/index.ts        # API URL, storage keys, custom events
│   ├── types/index.ts            # TypeScript interfaces
│   ├── services/api.ts           # HTTP client + all API functions
│   ├── hooks/                    # useAuth, ledger hooks, zerox methods
│   ├── pages/                    # 18 route pages
│   ├── components/
│   │   ├── auth/                 # Login, forgot password, ProtectedRoute
│   │   ├── layout/               # AppLayout (sidebar, header, nav)
│   │   ├── credits/              # Buy credits, crypto wallets
│   │   ├── dashboard/            # Dashboard overview
│   │   ├── finance/              # Withdrawal limits panel
│   │   ├── players/              # Player detail panel
│   │   ├── poster/               # Promo poster templates
│   │   └── ui/                   # ModalPortal, empty states
│   └── utils/                    # format, ban, phone, ledger helpers
├── public/                       # Static assets, PWA manifest, service worker
├── android/                      # Capacitor Android wrapper
├── scripts/                      # set-android-app-name.js
├── craco.config.js               # CRA override (monorepo UI package)
├── capacitor.config.ts           # Capacitor remote URL config
├── tailwind.config.js
├── vercel.json                   # SPA rewrite
└── deploy/nginx-spa.conf.example

Entry points

File	Role
`src/index.tsx`	Mount React, register Service Worker (production only)
`src/App.tsx`	Define routes, wrap `AuthProvider`
`src/services/api.ts`	Backend integration layer (~1146 lines)

State management

No Redux/Zustand. State architecture:

Pattern	Location	Purpose
React Context	`hooks/useAuth.tsx`	Auth state (user, token, login/logout)
Local useState	Each page/component	UI state, form, modal
Custom hooks	`useShopWalletTransactions`, `useShopOnlineBalanceLedger`, `useSupportedZeroxMethods`	Data fetching with reload
localStorage	Auth tokens, user data, zerox methods cache (24h TTL)
Custom Events	`window.dispatchEvent`	Cross-component sync

Custom events

Event	Constant	When dispatched
`shop-auth-token-changed`	`SHOP_AUTH_TOKEN_CHANGED_EVENT`	Login / logout
`shop-credit-balance-refresh`	`SHOP_CREDIT_BALANCE_REFRESH_EVENT`	After balance change flow
`auth:unauthorized`	—	Axios interceptor receives 401

Storage keys

Key	Content
`shop_auth_token`	Shop bearer token
`shop_user_data`	Shop profile (JSON)
`cashier_auth_token`	Cashier token (separate client, not main flow)
`cashier_user_data`	Cashier profile

Authentication flow

sequenceDiagram
  participant U as Shop user
  participant S as Shop Portal
  participant B as Backend

  U->>S: Enter loginId + password
  S->>B: POST /portal-auth/login
  alt OTP required (2FA)
    B-->>S: needsOtp + pendingToken
    U->>S: Enter OTP
    S->>B: POST /shop-auth/verify-otp
  end
  B-->>S: accessToken + shop profile
  S->>S: Save token to localStorage
  S->>B: GET /shop/me (refresh profile)

Header: Authorization: Bearer {token}
401 → dispatch auth:unauthorized → auto logout
ProtectedRoute redirects to /login if not authenticated

Environment variables

Variable	Required	Description	Default
`REACT_APP_API_BASE_URL`	Yes	Backend API base URL	`http://localhost:3001/api`
`REACT_APP_TURNSTILE_ENABLED`	No	Enable Cloudflare Turnstile	`false`
`REACT_APP_TURNSTILE_SITE_KEY`	When Turnstile enabled	Site key	`''`
`REACT_APP_APP_NAME`	No	Display app name	`Kiosk Gaming — Shop`
`REACT_APP_CLIENT_TELEGRAM_SUPPORT_URL`	No	Telegram support link	—
`REACT_APP_CLIENT_ANDROID_APK_URL`	No	Android APK download link	—
`REACT_APP_CLIENT_IOS_VIDEO_URL`	No	iOS setup video	—
`PORT`	No	Dev server port	`3004`
`CAP_SERVER_URL`	Build APK	Remote URL for Capacitor	`https://shop.kioskservice.club/`

warning

Backend must set SHOP_FRONTEND_URL to the app origin so payment redirects to /payment/success and /payment/cancelled.

npm scripts

Script	Description
`npm start`	Dev server port 3004 (CRACO)
`npm run build`	Production build
`npm run cap:sync:dev`	Sync Capacitor → `https://dev-shop.kioskservice.club/`
`npm run cap:sync:prod`	Sync Capacitor → `https://shop.kioskservice.club/`
`npm run apk:dev` / `apk:prod`	Build debug APK

Special configuration

CRACO + Monorepo UI

craco.config.js imports configureKioskgamingUi from ../packages/ui so webpack resolves the shared UI package.

Capacitor Android

App ID: club.kioskservice.kioskgaming.shop
Remote URL mode: does not bundle web assets, loads from remote URL
Dev: https://dev-shop.kioskservice.club/
Prod: https://shop.kioskservice.club/

SPA routing (production)

Platform	Config
Vercel	`vercel.json` rewrite `/(.*) → /index.html`
Netlify/Cloudflare	`public/_redirects`
Nginx	`deploy/nginx-spa.conf.example` (`try_files`)

Service Worker

public/sw.js + serviceWorkerRegistration.ts
Registers only when NODE_ENV === 'production'

Shared UI package

Shared components from @kioskgaming/ui:

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

Overview diagram

flowchart TB
  subgraph Client["kioskgaming_shop"]
    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| ShopAPI["/shop/*"]
    API --> AuthAPI["/shop-auth/*, /portal-auth/*"]
    API --> PaymentAPI["/payment/*"]
  end

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

Tech stack​

Directory structure​

Entry points​

State management​

Custom events​

Storage keys​

Authentication flow​

Environment variables​

npm scripts​

Special configuration​

CRACO + Monorepo UI​

Capacitor Android​

SPA routing (production)​

Service Worker​

Shared UI package​

Overview diagram​