POS app

The nexis-omni-pos repository is the point-of-sale: a Flutter app for Android and Windows, built offline-first. It must keep selling when the network is down, so it runs against its own local database (Drift) and syncs to the backend when it can reach it.

The sync model

• Sell locally, sync later. Sales, cash movements, and customer changes are written to the local database first and drained to the backend in a FIFO queue when connectivity allows.
• Client-generated ids as idempotency keys. Operations carry a client-generated id used as the primary key server-side (the same pattern for opening a cash session, recording a movement, and creating a customer). Re-sending a drained operation is a no-op rather than a duplicate; reusing an id across a different context returns a deterministic conflict.
• Terminal versus transient responses. A definite business response (a 2xx, or a deterministic 4xx) settles an item - synced or parked. A transport failure, a 401, or a 5xx / 503 is transient and gets retried; the queue rides out a suspended-tenant 503 rather than parking the work.
• Needs-attention UI. Orders the sync engine parks (conflict, rejected-needs-manager, rejected-terminal) surface in a dedicated screen with retry, void (with manager step-up), and accept-conflict actions.

The wire casing gotcha

The backend serializes responses as camelCase, while request bodies and enum values are sent as PascalCase. The OpenAPI document is the ground truth for casing - readers that assume PascalCase responses will silently misread fields.

Release-build trust

The release build trusts only CA-valid TLS certificates and uses a Secure, host-only refresh cookie. That means production must be a real DNS host with a valid certificate - never a LAN IP or a self-signed cert. This is one of the constraints the deployment plan is built around.

Go deeper

• POS architecture - the layers (Drift, Riverpod, Dio), the lease-guarded sync engine, and client-id idempotency.

The POS repository also holds its own canonical architecture notes next to the code (nexis-omni-pos/docs/architecture/foundation-blueprint.md).