> ## 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.

# Architecture overview

> High-level architecture of the Sirvo POS system.

## System diagram

```
┌─────────────────────────────────────────────────┐
│                  POS Terminal                     │
│  ┌───────────────────────────────────────────┐   │
│  │          Tauri Desktop Shell              │   │
│  │  ┌───────────────────────────────────┐    │   │
│  │  │     Next.js 16 (Static Export)    │    │   │
│  │  │                                   │    │   │
│  │  │  ┌─────────┐  ┌──────────────┐   │    │   │
│  │  │  │ XState  │  │  usePOS       │   │    │   │
│  │  │  │Machines │  │  Reducer      │   │    │   │
│  │  │  └─────────┘  └──────────────┘   │    │   │
│  │  │  ┌─────────┐  ┌──────────────┐   │    │   │
│  │  │  │ Dexie   │  │  Sync        │   │    │   │
│  │  │  │IndexedDB│  │  Transport   │   │    │   │
│  │  │  └─────────┘  └──────┬───────┘   │    │   │
│  │  └───────────────────────┼───────────┘    │   │
│  └──────────────────────────┼────────────────┘   │
└─────────────────────────────┼────────────────────┘
                              │
                    WebSocket │ HTTP
                              │
              ┌───────────────┼───────────────┐
              │               ▼               │
              │    ┌──────────────────┐       │
              │    │    Sync Hub      │       │
              │    │  (Node.js + WS)  │       │
              │    │  ┌────────────┐  │       │
              │    │  │  SQLite    │  │       │
              │    │  └────────────┘  │       │
              │    └────────┬─────────┘       │
              └─────────────┼─────────────────┘
                            │
                   HTTP POST│ (batch-sync)
                            │
              ┌─────────────┼─────────────────┐
              │             ▼                  │
              │    ┌──────────────────┐        │
              │    │   Odoo 12        │        │
              │    │  (Python API)    │        │
              │    │  ┌────────────┐  │        │
              │    │  │ PostgreSQL │  │        │
              │    │  └────────────┘  │        │
              │    └──────────────────┘        │
              └────────────────────────────────┘
```

## Data flow

1. **Bootstrap** — Terminal authenticates via JWT, fetches full config + catalog + floor plan from Odoo
2. **Local operations** — Orders are created and edited locally in the reducer, persisted to IndexedDB via Dexie
3. **Sync** — Changes broadcast through the hub to other terminals in real-time
4. **Upstream** — Completed orders are forwarded from the hub to Odoo via `POST /pos-api/v1/hub/batch-sync`
5. **Offline** — Terminals continue working with local data; changes queue in the outbox until connectivity returns

## Key design decisions

<AccordionGroup>
  <Accordion title="Offline-first with IndexedDB">
    All order data is persisted to IndexedDB (Dexie) immediately. The system remains fully functional without network connectivity. Sync happens opportunistically.
  </Accordion>

  <Accordion title="Domain-driven frontend">
    Business logic lives in `src/domain/` as pure functions, completely decoupled from React. This makes the core logic testable without component rendering.
  </Accordion>

  <Accordion title="XState for complex workflows">
    Session lifecycle, order state transitions, and sync status are modeled as explicit state machines, preventing impossible states.
  </Accordion>

  <Accordion title="Hub as broadcast broker">
    The sync hub is a thin WebSocket relay — it doesn't own business logic. Terminals remain authoritative over their own orders.
  </Accordion>
</AccordionGroup>