Technical details —Cashier App

Stack & holistic thinking

Different from Kiosk Frontend (Next.js, state machine in-memory): this is oneCreate classic React AppPackaged by Capacitor into an Android app for counter staff. Grasp the following 6 "strange" characteristics before reading the code.

Directory structuresrc/

Flat directory tree according to CRA standards:pages/for each screen,components/, services/, hooks/, utils/. Alias @/NOT used — import using relative path.

Startup screen:index.tsx → App.tsx

A normal CRA SPA: bootstrap React in#root, set the tab title, register the service worker, and then let the router decide on the display.

document.title = ENV.APP_NAME;

const root = ReactDOM.createRoot(document.getElementById('root') as HTMLElement);
root.render(
  <React.StrictMode><App /></React.StrictMode>
);

registerServiceWorker(); // PWA/offline shell

Routers & protection route

Full definition inApp.tsx. Each business screen is wrapped<Protected>(it isCashierProtectedRoute). Public route only/login.

const { isAuthenticated, isLoading } = useCashierAuth();

if (isLoading) return <PageLoadingIndicator variant="section" />;

if (!isAuthenticated)
  return <Navigate to="/login" replace state={{ from: location }} />;

return <>{children}</>;

Auth, tokens & device identifier

Auth of cashiercompletely separatewith Shop Admin (different localStorage key). Each login is associated with onedevice fingerprintand must register the device for store management to approve.

cashierApi.ts — axios singleton

OneAxiosInstancemade available withbaseURL, timeout 15s, and 2 interceptors. All API functions are pure exports (not classes), most are wrappedtry/catchreturns a standard envelope.

const c = axios.create({ baseURL: API_BASE_URL, timeout: 15000 });

c.interceptors.request.use((config) => {
  const token = localStorage.getItem(STORAGE_KEYS.CASHIER_AUTH_TOKEN);
  if (token) config.headers.Authorization = `Bearer ${token}`;
  return config;
});

c.interceptors.response.use((r) => r, (error) => {
  if (error.response?.status === 401)
    window.dispatchEvent(new Event('cashier-auth:unauthorized'));
  return Promise.reject(error);
});

Backend endpoint table (afterbaseURLincluded/api)

Denomination engine

The heart of every fund operation.utils/denominations.tskeep constant + formula;components/DenominationGrid.tsxis a reusable UI for Opening, Cash drop, Closing and Handover.

export function computeDenominationTotal(items: DenominationItem[]): number {
  const total = items.reduce(
    (sum, i) => sum + i.denomination * i.quantity, 0);
  return Math.round(total * 100) / 100; // avoid float errors
}

Life cycle ca & thestatus

The app does not have a centralized state machine like a kiosk frontend; instead the "state machine" resides on the backend via the fieldshift.status, and the frontend reacts by redirecting and toggling the button.

Another state appears in the UI:auto_locked, suspended, no_show, cancelled. In code, "actionable shift" =['active','auto_locked','suspended'].

Close shift with "blind close" style

const res = await cashierCloseShiftBlind(id, { denominations: items });
// Expected number is NOT displayed until submission is complete:
res.data = { actualClosingCash, expectedClosingCash,
            discrepancyAmount, discrepancyFlagged, status };

Deposit / Redeem in ActiveShiftPage

Core working screen: look up players (debounce 250ms), load credits, exchange credits, create new players via modal. All trading buttons are enabled only whencanOperate === true.

useEffect(() => {
  const t = setTimeout(() => void loadPlayers(), 250);
  return () => clearTimeout(t);
}, [search]); // keystroke → wait 250ms → GET /cashier/players

Handover & Cash drop

Two sub-fund operations, both rotating aroundDenominationGrid. HandoverPageespecially because there is2 modesautomatically deduced from ca.'s status.

if (['active','auto_locked','suspended'].includes(current.status))
  setMode('initiate');
else if (current.status === 'scheduled')
  setMode('confirm');
else setMode('none'); // do not allow handover

Capacitor / Android — the biggest difference

Here's what makes this repo different from every other web app in the system: it's packaged intoAPK AndroidRuns on tablet counter. But there's an important surprise about how the app loads content.

const remoteUrl = process.env.CAP_SERVER_URL?.trim()
  || 'https://cashier.kioskservice.club/';

const config: CapacitorConfig = {
  appId: 'club.kioskservice.kioskgaming.cashier',
  appName, // '[Dev] Cashier...' or 'Cashier - Kiosk Gaming'
  webDir: 'build',
  server: {
    url: remoteUrl, // ★ load from LIVE web, not from local build!
    allowNavigation: ['dev-cashier.kioskservice.club', 'cashier.kioskservice.club'],
  },
};

Actual build flow (script in package.json)

# DEV: point WebView to dev-cashier + rename "[Dev] ..."
npm run apk:dev
#  └→ CAP_SERVER_URL=https://dev-cashier... cap sync android
#     && node scripts/set-android-app-name.js dev
#     && cd android && ./gradlew assembleDebug

# PROD: points to cashier.kioskservice.club
npm run apk:prod   # = apk (default)

Tailwind v3 & CRACO

Other kiosk frontend (Tailwind v4 no config): this isTailwind v3Havetailwind.config.js + postcss.config.js, using design token stylehsl(var(--…)). Build via CRACO to patch webpack.

const patch = require('../packages/ui/scripts/craco-patch-source-map-loader-ui.cjs');

module.exports = {
  webpack: {
    configure: (cfg) => { patch(cfg); return cfg; },
  },
};

Config & environment variable

Stay focusedsrc/config/env.ts. According to CRA standards, variables must have a prefixREACT_APP_just entered the bundle (differently used by Next.jsNEXT_PUBLIC_).

Test setup

Repo has the set@testing-library/*via CRA/Jest but currently there is no actual test file in the codebase.

npm start          # craco start → http://localhost:3000
npm run build      # craco build → build/ folder
npm test           # craco test (Jest watch)
npm run apk:prod   # cap sync + gradlew assembleDebug

Cookbook for new devs

Common tasks follow project conventions.

Common traps (read before fixing)