# client-services — On-site Pack

Everything that runs **inside the restaurant**, on the local server box.
This folder is its **own git repo**, nested inside the `xenia-pos` parent repo.

> **Read the global rules first:** [../../docs/README.md](../../docs/README.md). This file adds only the rules specific to this pack.
> The feature catalog, the cloud contract, known issues and site records all live in the parent's `docs/`.

---

## Services

| Service | Stack | Dev port | Prod exposure | Image |
|---|---|---|---|---|
| `local_backend` | FastAPI + SQLAlchemy + SQLite (`/app/data/pos.db`) | 8000 | only through proxy / inner nginx | `pos-backend` |
| `waiter_pwa` | React + Vite + vite-plugin-pwa, axios, zustand, react-query, Dexie (IndexedDB) | 5173 | `https://<host>` (443) | `pos-waiter` |
| `manager_dashboard` | React + Vite | 5174 | `https://<host>:4443` | `pos-manager` |
| `proxy` | nginx:alpine, TLS termination | — | 80 → 443 redirect, 443, 4443 | stock |

### Request path in production
```
phone ──https──▶ proxy:443 ──http──▶ waiter_pwa nginx:80 ──┬─ /           → static SPA
                                                            ├─ /api/       → backend:8000
                                                            ├─ /api/ws/    → backend:8000 (WebSocket upgrade)
                                                            └─ /static/    → backend:8000/static/
```
Every hop must forward WebSocket upgrades: `proxy_http_version 1.1`, plus `Upgrade` and `Connection` headers, plus a long `proxy_read_timeout`.
The frontends call the API **same-origin, with relative paths** (`baseURL: ''`). Don't hardcode hosts.

## Key files

| File | Why it matters |
|---|---|
| `local_backend/main.py` | App setup, router registration, CORS, **`_run_migrations()`** |
| `local_backend/services/cloud_sync.py` | Every call to the cloud (see the parent's `docs/reference/cloud-contract.md`) |
| `local_backend/roles.py`, `routers/deps.py` | Roles, permission checks, auth dependencies |
| `local_backend/routers/ws.py` | Real-time event stream (seq + cursor replay) |
| `waiter_pwa/src/api/client.js` | axios instance: auth header, 401 → logout, network error → offline |
| `waiter_pwa/src/context/SSEContext.jsx` | Real-time lifecycle, event → store/cache updates, visibility refresh |
| `waiter_pwa/src/db/posdb`, `src/services/offlineOrders` | Offline cache and queued orders |
| `nginx-proxy/nginx.conf` | Proxy config used in dev / by hand |
| `install.sh` | Site installer. **Writes its own copy of the proxy config.** |
| `docker-compose.yml` / `docker-compose.dev.yml` | Prod (pull images) / dev override (build + expose ports) |

---

## Pack-specific rules

**CS-1. Schema changes go through `_run_migrations()`.**
A new table: `create_all` handles it. A new column on an existing table: append an `ALTER TABLE <t> ADD COLUMN ...` to the `migrations` list in `local_backend/main.py`, with a SQLite-safe default for `NOT NULL`.
Add the column to the SQLAlchemy model **and** the Pydantic schema in the same commit. Never drop or rename columns.

**CS-2. New real-time events need both ends.**
If the backend emits a new event type, handle it in `waiter_pwa/src/context/SSEContext.jsx` (and in the manager, if relevant), or state explicitly that it's ignored.
Events carry IDs; clients re-fetch the full object (`/api/orders/{id}`) instead of trusting partial payloads.

**CS-3. The waiter app must survive bad networks.**
Waiters walk in and out of WiFi range and phones sleep. Any new waiter flow must:
- work from the IndexedDB cache when offline, or clearly block with an offline state
- never lose an order that was entered (queue it)
- tolerate duplicate or replayed events

**CS-4. Money and prices are snapshotted.**
Prices, costs and discounts are copied onto order items and logs when the action happens (snapshot pattern, `PriceEventLog`). Reports read the snapshots, never the live catalogue.

**CS-5. The proxy config lives in two places.**
Edit `nginx-proxy/nginx.conf` **and** the heredoc in `install.sh` together (global Rule 9).

**CS-6. Permissions are checked on the backend.**
Hiding a button in the UI is not access control. Every new endpoint declares its role or `perm_*` requirement through `routers/deps.py`.

**CS-7. Greek-market realities.**
Staff UIs are used by Greek staff and must render Greek correctly, including on thermal printers (codepage). Money uses €.

## Common commands

```powershell
# Dev: backend with reload
cd local_backend; uvicorn main:app --reload --port 8000

# Dev: frontends (Vite proxies /api and /api/ws to :8000)
cd waiter_pwa; npm run dev          # :5173
cd manager_dashboard; npm run dev   # :5174
cd waiter_pwa; npm run lint

# Build release images (VERSION comes from .env). See the parent's DEPLOYMENT_GUIDE.md.
docker compose -f docker-compose.yml -f docker-compose.dev.yml build
docker push registry.bonamin.gr/pos-backend:<ver>   # + pos-waiter, pos-manager
```

## Testing
There is no automated test suite yet. Before committing:
- the backend starts cleanly against an **existing** `pos.db` (this catches missing migrations)
- `npm run build` passes for any frontend you touched
- the flow was exercised by hand (the parent's `PLANS AND STRATEGIES/TESTING_CHECKLIST.md`)
- printing was checked against real hardware or `esc-pos-emulator`

Say in the commit or hand-off what was and wasn't verified.