> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laportenard.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Frontend development

> How to work with the Next.js frontend, state machines, and UI components.

## Development workflow

Start the dev server and make changes — Next.js hot-reloads automatically:

```bash theme={null}
cd nu_pos_react
npm run dev
```

For desktop testing, use the Tauri dev window:

```bash theme={null}
npm run desktop:dev
```

## State management

The frontend uses a layered state architecture:

| Layer             | Technology                | Purpose                                 |
| ----------------- | ------------------------- | --------------------------------------- |
| Global app state  | XState machines           | Session lifecycle, sync status, UI mode |
| Order/table state | React reducer (`usePOS`)  | Active orders, table assignments        |
| Persistence       | Dexie (IndexedDB)         | Offline-first data storage              |
| Server state      | API client (`odooApi.ts`) | Bootstrap, order sync, payments         |

### XState machines

* **`sessionMachine`** — Login → active session → logout lifecycle
* **`orderMachine`** — Order state transitions (idle → editing → checkout → paid → finalized)
* **`syncMachine`** — Transport connectivity (online/offline/reconnecting/hubOffline)
* **`uiMachine`** — UI mode management

### POS reducer

The central `usePOS` reducer manages orders and tables. When adding fields to action payloads, update all three places:

1. The `POSAction` type union
2. The `POSContextValue` interface
3. The `useCallback` wrapper

<Warning>
  Missing any of these causes silent type errors or runtime bugs.
</Warning>

## Domain layer

Business logic lives in `src/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 in `src/ui/` is built on Radix UI primitives with Tailwind v4 styling.

## Internationalization

Translations use `next-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.