Development workflow
Start the dev server and make changes — Next.js hot-reloads automatically:State management
The frontend uses a layered state architecture:XState machines
sessionMachine— Login → active session → logout lifecyclesyncMachine— Transport connectivity (online/offline/reconnecting/hubOffline)uiMachine— UI mode management
POS reducer
The centralusePOS reducer manages orders and tables. When adding fields to action payloads, update all three places:
- The
POSActiontype union - The
POSContextValueinterface - The
useCallbackwrapper
Domain layer
Business logic lives insrc/domain/ as pure functions and types, separate from React. Each domain module exports:
- Models — TypeScript types and interfaces
- Computations — Pure functions for calculations (totals, taxes, validation)
- Parsers — Functions to transform API responses into domain models
UI components
The shared component library insrc/ui/ is built on Radix UI primitives with Tailwind v4 styling.
Internationalization
Translations usenext-intl with locale files at src/i18n/locales/{en,es}.json. Wrap user-facing strings with the t() function and add entries to both locale files.