16. Infrastructure Stack

This section describes the deployment pattern and runtime expectations for the app.

Platform architecture

Frontend: static or SPA assets generated by TanStack Start, served from a CDN or edge host.
Backend: Nitro-compatible server routes for API endpoints, session grant issuance, and reconciliation.
Terminal UI: same frontend code in a terminal mode, running in a browser kiosk or embedded device.
Data stores: a small persistent database for reconciliation and audit, with optional edge cache for active sessions and blacklists.

Serve frontend assets from Cloudflare Pages as the default production host.
Run backend APIs on Cloudflare Pages Functions / Workers runtime as the default server execution target.
Cache session grant and blacklist state in Cloudflare KV for low-latency edge validation.
Store reconciliation events and audit logs in Cloudflare D1 as the default relational persistence layer.
Alternative hosts or datastores are allowed only as explicit deployment overrides, not as baseline architecture.

Operation	Target latency	Notes
Session grant fetch	< 300 ms	Cached at edge
Policy fetch	< 200 ms	Rarely changes; highly cacheable
Reconciliation upload	< 1 s	Batch; not on the critical path
Terminal report	< 500 ms	Fire-and-forget; async acceptable

Backend unavailability must not prevent offline terminal transactions within a valid session grant window.
Session grants should be pre-fetched and cached by the terminal on startup and refreshed proactively before expiry.
Frontend should display the last known card state and a connectivity indicator when backend is unreachable.

Backend must support both online validation and batched offline reconciliation uploads.
Use versioned deployment and clear migration steps for card layout changes, API schema updates, and key version rotations.
Maintain zero-downtime deployments for the backend; terminals in the field must not be disrupted by backend updates.