# Elite Till architecture

## Core principle
The interface is intentionally smaller than the existing Elite Mall POS. A merchant can record a sale with only **amount + payment method**. An inventory item is optional. For M-PESA, the customer number is required and STK confirmation makes the record `provider_verified`. Cash is `merchant_recorded`.

## Sale flow
1. Merchant creates sale with a unique client nonce.
2. Optional tracked stock is reserved for M-PESA.
3. STK request is sent.
4. Callback is protected by an unpredictable callback token and matched to the provider checkout ID.
5. Exact amount is checked.
6. Success posts one append-only `sale_credit`, finalises stock and updates daily metrics.
7. Failure releases stock. Ambiguous/amount-mismatch outcomes become `review` and are never automatically retried.

## Cash
Cash sales are recorded immediately and appear in business performance, but their ledger entry has `withdrawable_delta = 0` and `record_quality = merchant_recorded`.

## Settlement
The payout form contains **no destination input**. It loads the merchant's one active primary `till_settlement_destinations` record. Only a user with role `owner` can submit B2C. A failed/review payout does not create a debit entry. A confirmed B2C callback creates the debit.

## PWA
The service worker caches static assets and the offline notice only. Authenticated pages, sales, callbacks and ledger data are never cached for offline replay. Payment actions are intentionally unavailable offline.

## Database
`001_elite_till.sql` creates all operational tables. `002_append_only_guards.sql` is optional if the hosting DB user has TRIGGER privilege; it makes ledger and audit rows immutable at the DB layer.