13 — Bridge & Devices

Bridge WebSocket, device discovery, printers, C# bridge (reference expanded)

Bridge in the customer’s stack

The bridge sits at the edge of the tenant network (typically a small Windows PC or VM on the same subnet as printers and KDS). Browsers and tablets talk to our cloud over HTTPS as usual. When the cloud needs something on the LAN, it sends a message down the existing WebSocket to the bridge; the bridge executes locally (spool print jobs, fire KDS tickets, optional RPC to a local crypto node, etc.).

• No inbound NAT: Sites do not expose bridge ports to the internet; connectivity is outbound-only from bridge → cloud.
• Routing “everything”: Practically, the bridge routes LAN-side capabilities we have implemented (print, KDS, device notifications, crypto RPC, wallet listing)—not arbitrary TCP proxying. New capabilities extend the same pattern: new action handlers on the bridge and callers on the server.
• Identity: Connection is keyed by bridgeId + tenantSlug; the server resolves the tenant and stores orgId for isolation. bridgeToken is supported in the URL for future hardening (validation is still TODO in code).

WAN failover, offline, and “Starlink if AT&T dies”

WAN redundancy (primary fiber/cable vs Starlink, dual ISP, SD-WAN) is normally handled by the customer’s router, firewall, or SD-WAN appliance—not by the bridge application. When the public path to our API changes or comes back, the bridge’s existing reconnect and retry logic (see C# ServerConnectionService) should re-establish the WebSocket automatically once DNS and routing stabilize.

Offline operations: True offline POS (queue sales locally, sync later) is implemented in the browser SPA via IndexedDB (pawspos_offline) and posApi / idempotent replay — see 14 — Frontend and 06 — POS & Invoicing. The Node.js bridge (bridge/) attaches the same style of mutation envelope headers on mutating axios calls toward the cloud API (Idempotency-Key, X-PPO-*) so bridge-originated writes dedupe consistently with web POS. On the C# bridge side, OfflineQueueService periodically attempts to drain a local SQLite queue when cloud sync is authenticated; that path remains largely scaffolding (verify before relying on it).

Failsafe operations: If the bridge process stops, LAN routing from the cloud stops until it restarts; mitigations are monitoring, auto-restart (Windows Service / PM2-style supervisor), and redundant bridge host if the site requires it. Peripheral-level failsafe (e.g. backup printer) remains local policy.

Cloud server: WebSocket and manager

Mount: WebSocketServer in backend/server.js, path /api/bridges/connect. Logic: backend/services/bridgeConnectionManager.js.

Query parameters: bridgeId, tenantSlug (required); bridgeToken (optional, not yet enforced server-side).

On connect, the server validates the tenant exists and is active, then sends { type: "welcome", bridgeId, message }.

REST API (tenant-authenticated)

Mounted under the API prefix (e.g. /api). All routes use requireSessionAuth and tenantResolver unless noted.

WebSocket protocol (summary)

Bridge → cloud (inbound to server)

Cloud → bridge

Requests are JSON messages: { "type": "request", "requestId", "action", "data" }. The C# client may also accept a top-level deviceNotification message type for the same payload shape.

Sequence: print / KDS from cloud

C# bridge (bridge-win-csharp/PAWSPOS.Bridge)

Services (inventory)

HTTP controllers under the bridge host (e.g. BridgeController, HomeController) support legacy health/info endpoints used when bridge_url HTTP fallback is enabled.

Tenant configuration

Table tenant_configs (per-tenant DB): bridge_url, bridge_token. Routes ensure the table exists. Generated appsettings uses API_BASE_URL or defaults to staging API.

Source files (this repo)

• backend/services/bridgeConnectionManager.js — WebSocket registry, sendRequest, status, device tracking
• backend/routes/bridge.routes.js — REST endpoints under /bridge/*
• backend/server.js — WebSocketServer on path /api/bridges/connect
• bridge-win-csharp/PAWSPOS.Bridge/Services/ServerConnectionService.cs — outbound client, message switch, request actions

Signage: cloud → bridge (high level)

Detail: 26 — Signage & Displays.

Device routing & discovery (flows)

Goal: Staff see registers, kiosks, and KDS-style endpoints in Admin → Devices (/admin/devices/manager). Rows live in the tenant Devices table. There is no magic browser LAN scan of every device on Wi‑Fi — visibility comes from heartbeats to the cloud API (while a user session exists), manual CRUD, and bridge-side plumbing (local DB, WebSocket notify-device, signage WS clients).

1) Where device truth shows up

2) Browser heartbeat sequence (auto-register)

While POS is open and the user is logged in, the SPA posts JSON on an interval. deviceKey is stable in localStorage. Local IP is best-effort (WebRTC and optional manual deviceLocalIP) — not guaranteed across browsers or locked-down networks.

3) Cloud ↔ bridge: live register awareness (not the same as SQL rows)

POST /api/bridge/notify-device pushes a deviceNotification request down the bridge WebSocket when the cloud wants the bridge to know a register entered or exited POS. The bridge connection manager keeps a short-lived in-memory map (trackDevice), surfaced in GET /api/bridge/status as activeDevices. That list is for ops and bridge diagnostics; it does not replace the Devices table unless the heartbeat path also wrote the row.

4) On-site bridge: LAN heartbeat endpoint (Node / C#)

The Node bridge exposes POST /local/devices/heartbeat for LAN agents. It forwards the body toward the cloud as POST …/devices/heartbeat with a Bearer token after bridge authentication. The public router for /api/devices applies cookie session auth to those routes — so server-to-server bridge forwarding may receive 401 until a bridge-scoped ingest path exists (for example a dedicated POST /api/bridges/… handler or optional Bearer validation on heartbeat). Today, the path into Devices that matches the dashboard session model is the logged-in browser heartbeat.

5) Signage and other LAN clients

Signage relay players use the bridge’s local /ws relay. They are not inserted into Devices by default — they consume playlists. If you need them listed as devices, use the same heartbeat pattern as other LAN clients once bridge-to-cloud device ingest is aligned with auth, or register them manually in Admin → Devices.

Device registry, metadata, and POS vertical modules

Where registers are defined: Tenant staff configure devices in the dashboard at /admin/devices/manager (frontend/src/pages/admin/sections/devices/DeviceManager.jsx) — create/edit rows in the tenant Devices table (type, location, name, device_key, JSON metadata). This is not the Business Hub (/business-hub) settings search; forecourt/fuel and similar toggles live on the device record.

POS modules (verticals): Optional Modern POS panels are gated by metadata.posModules (alias pos_modules). The server normalizes module IDs in backend/utils/posModules.js. Today only fuel is recognized: { "posModules": ["fuel"] } on the POS device row. Admin: Forecourt / fuel module checkbox; table shows Fuel and optional pump count under POS extras.

Forecourt site config (fuelSite): Stored as metadata.fuelSite (legacy fuel_site read on parse; canonical key on save). Sanitized in backend/utils/fuelSite.js; admin device POST/PUT runs normalizeDeviceMetadataFuelSite. Fields: authorizationMode (pos | attendant | fms_monitor); pumps[] (id, label, hoses 1-12); grades[] (code, label, optional tankId, productSku); integration (type: none | site_bridge | third_party_fms, vendor, notes); posPanel (maxPumpsVisible, showAllStop, showTankAlarmsShortcut). Admin form: FuelSiteFormSection.jsx inside DeviceManager.jsx.

Runtime: GET /api/pos/settings (06 — POS & Invoicing) returns device.posModules and device.fuelSite via parseFuelSiteFromDeviceRow. ModernPOS.jsx passes both to PosModuleHost / FuelModulePanel. Cart line metadata for fuel: see ch. 06.

Related platform routes

Devices: POST /api/devices/heartbeat, /api/admin device CRUD (devices router), and device catalog flows (see route appendix)—orthogonal to the bridge WebSocket but part of “who is on the floor.” See Device routing & discovery above for flowcharts (browser heartbeat vs bridge notify vs signage). Notify bridge: POST /api/bridge/notify-device ties POS/session events to the bridge’s view of active registers. Signage: /api/signage/* and POST /api/bridge/notify-signage.

Bridge implementations