Offline & sync queue

The gateway is designed to keep ingesting ECGs even when the internet is down. All cloud-bound records are written to a local SQLite queue first, then flushed in the background.

What happens when the cloud is unreachable

1. ECG file lands in drop folder → parser writes the record to local SQLite.
2. HL7 message goes to your HMIS over LAN (no internet needed) — clinicians can still see results in the HMIS.
3. The record is added to the sync_queue table.
4. The sync loop attempts to push every SYNC_INTERVAL_MS (default 60s). On failure it backs off: 1 min → 5 min → 15 min → 1 hour, then stays at 1 hour until success.
5. When the cloud comes back, the queue drains in chronological order. No records are lost.

Idempotency

Every record carries a file_hash (SHA-256 of the original file). The cloud rejects duplicates by hash, so a queue retry that succeeded once is safe to replay — the cloud returns { duplicate: true, id: <existing> } and the gateway marks it synced.

Capacity

Default queue cap is 50,000 records (≈ a year of ECGs for a busy 1-gateway clinic). Past the cap the gateway starts dropping the oldest unsynced records and emits a queue_overflow warning. Increase via SYNC_QUEUE_MAX if needed.

Inspecting the queue

docker compose exec gateway sqlite3 /data/gateway.db \
  "SELECT id, created_at, retry_count FROM sync_queue WHERE synced_at IS NULL"

Forcing a flush

curl -X POST http://localhost:3000/internal/sync/flush

Useful right after restoring an internet connection — saves you waiting for the next interval.