Staff — Development

How to run and change the Staff POS safely.

Requirements

  • Node.js 20+ and npm
  • A running resa_api backend (Django), local or test
  • See Environments for ports and hosts

Setup

cd staff
npm install
copy .env.example .env

Edit .env (or .env.local) and set the API origin:

Variable Purpose
VITE_API_BASE_URL Backend origin without trailing / or /api

Examples:

# Local API (port 8000, or next free)
VITE_API_BASE_URL="http://localhost:8000"

# Shared testing Staff/API host
VITE_API_BASE_URL="http://resa.morvanes.info"

Resolution lives in src/config/app.ts:

  • Uses VITE_API_BASE_URL when set
  • Otherwise browser window.location.origin, or http://localhost:8000 outside the browser
  • Strips trailing / and a trailing /api
  • Builds API_URL = ${API_ORIGIN}/api

Polling cadence for live data: FETCH_INTERVAL_MS = 10_000 (10 seconds).

Warning — do not commit secrets
Never commit real .env or .env.local files. Keep them local only; .env.example is what belongs in git. Restart the Vite dev server after changing env vars.

Scripts

Command What it does
npm run dev Vite dev server (default port 5173, or next free)
npm run build Production build
npm run build:dev Build in development mode
npm run preview Preview the production build
npm run lint ESLint
npm run check TypeScript (tsc --noEmit)
npm run test Vitest once
npm run test:watch Vitest watch
npm run format Prettier write

Unit tests live under src/**/*.test.ts (orders, reporting, MasaGrid helpers, reservations, PosShell swipe, etc.). There is no in-repo E2E suite.

Path alias and layout conventions

  • Alias: @/* → src/* (vite-tsconfig-paths + tsconfig)
  • Features under src/features/{auth,staff,pos}
  • Shared UI under src/components/{ui,layout,pos,staff,auth}
  • Domain logic under src/lib/{api,orders,menu,reservations,reporting,…}
  • Colocate *.constants.ts, *.types.ts, and often *.helpers.ts / *.row.tsx next to the feature

UI stack notes

  • Tailwind CSS v4 via @tailwindcss/vite; design tokens in src/styles.css
  • shadcn “new-york” + Radix primitives in src/components/ui
  • Sonner toasts from App
  • Icons: lucide-react
  • Charts: recharts
  • Exporting: exceljs, jspdf, html2canvas-pro
  • Forms: react-hook-form + Zod (@hookform/resolvers)

Branding (C-House) is still hard-coded in places such as src/data/restaurant.ts and index.html.

Large surface: AdminPage

src/features/pos/AdminPage.tsx is the central POS host for every tab. Much of the floor logic, dialogs, and data wiring still live here (historically extracted from an older admin.tsx). Prefer extracting new UI into src/components/pos/ and thin hooks under src/lib/query/ rather than growing AdminPage further.

Troubleshooting

Symptom Likely cause What to check
API calls fail Backend down or wrong URL VITE_API_BASE_URL, API process, CORS
Cannot log in Bad credentials or CORS Backend auth logs, /api/auth/login/
Env change ignored Dev server not restarted Stop/start npm run dev
Tab redirects to Masalar Role cannot open that tab Auth & roles matrix
Floor actions blocked Business day closed Day gate on Masalar / Raporlar