# Operating Best Practices

> Practical guidance for running Xisom Edge AI in production — model preparation, datasource sizing, monitoring, deployment, and security.

Field-tested guidance for keeping a Xisom box healthy in production. Each section
links to the reference page with the full detail. Sections marked **Placeholder**
are being finalized with field data — treat them as direction, not settled numbers.

## The operating loop

```mermaid
flowchart LR
  P["Prepare<br/>modelctl"] --> D["Deploy<br/>upload + pair + activate"]
  D --> M["Monitor<br/>latency · throughput · EP"]
  M -->|"drift / new data"| P
  M -->|"version up"| D
```

## Model preparation

- **Validate against the box's ONNX Runtime version** before shipping — pin
  `--target-ort` so a too-new opset fails on the workstation, not on the floor.
- **Quantize deliberately.** Dynamic INT8 makes models smaller and usually faster,
  at some accuracy cost — re-validate the quantized model and check prediction
  quality before it goes live.
- **Pin reproducible bundles** (`--timestamp`) so the artifact on the box matches
  what you reviewed. See [Preparing Models](/configure/prepare-models/).

## Datasource sizing

- **Match window size × feature count** between model and datasource — the platform
  rejects a mismatched pairing. Record these two numbers with every model.
- **Prefer OPC-UA subscriptions** over polling where the server supports them.
- **Use CSV replay** to validate a model against recorded data before connecting a
  live plant source. See [Input Datasources](/configure/input-datasources/).

## Monitoring & alerting

- **Watch p95/p99 latency, not just the average** — tail latency is where edge
  inference degrades first.
- **An execution-provider fallback to CPU is a regression signal** — if a box that
  should run on TensorRT/CUDA reports CPU, investigate before throughput drops.
- **Live metrics retain for 3 days** — export anything you need for longer-term
  trending. See [Monitoring](/operate/monitoring/).

**Placeholder — recommended thresholds**

Concrete latency / throughput alert thresholds per hardware tier are still being
collected from field deployments. To be filled in here.

## Deployment & versioning

- **Keep frontend and backend versions in lockstep** — a drift triggers the
  version-mismatch banner. See [Versions & Updates](/operate/versioning/).
- **Stage on the Docker lab** before promoting a model or release to a production
  box. See [Docker Lab](/operate/docker-lab/).

**Placeholder — capacity & sizing**

Per-hardware guidance (models per box, max sustained throughput by edge device)
is pending benchmark data. To be filled in here.

## Security

- **Apply least privilege** — reserve admin accounts for actions that need them
  (output test writes, key management); operators sign in as operators.
- **Review the audit trail** periodically — it records who accessed the system and
  when.
- **Terminate TLS at the reverse proxy** in front of the dashboard and API, and use
  authenticated brokers / secured OPC-UA policies for datasources. See
  [Security](/security/).

**Placeholder — backup & recovery**

Recommended backup cadence and restore procedure for model data and configuration
is being documented. To be filled in here.

## Next steps

  - [Preparing Models](/configure/prepare-models/) — Convert, validate, quantize, package.
  - [Monitoring](/operate/monitoring/) — Read the inference dashboard.
  - [Security](/security/) — Access control, hardening, audit.