RetailGuard Sync Monitor

Data Sync — sync-now.ps1 (every 15 min)

Checking...

History

Writeback Agent — writeback.ps1 (every 5 min)

Checking...

History

E2E Verification (price change applied on PC then confirmed in next sync)

Loading jobs...

Product

Price

Status

Verified

When

New Products — addproduct.ps1 (every 5 min)

Barcode

Price

Status

Verified

When

Agent history

Removed Products — removeproduct.ps1 (every 5 min)

Barcode

Status

When

Agent history

Refreshing every 30s

How it all fits together

RetailGuard has two halves. The shop PC (Patrick's) runs the till database (Pervasive / RetailSolutions). The Oracle VM runs the RetailGuard web app and a Flask API. They never talk directly — instead, four small PowerShell agents run on the shop PC as scheduled tasks. Each agent polls the VM for work, does its job against the local till database over ODBC, and reports the result back.

The dashboard queues jobs on the VM (a price change, a new product, a removal). The relevant agent picks the job up on its next run, applies it on the shop PC, and reports back applied or failed. This Monitor page reads the VM's public status endpoints every 30 seconds and shows whether each agent is alive and what it has done recently.

The four agents (scheduled tasks on the shop PC)

Data Sync — sync-now.ps1 (every 15 min)

Exports the six ODBC tables (Stock, transactions, suppliers, departments, etc.) and uploads them to the VM. Keeps the VM's product catalogue current. Health = /api/health → sync_fresh.

Writeback Agent — writeback.ps1 (every 5 min)

Heartbeats the VM, then applies queued price and cost changes with an ODBC UPDATE Stock. The till picks up the new price on its next poll. Health = /api/health → agent_heartbeat_age_min.

New Product — addproduct.ps1 (every 5 min)

Polls for new_product jobs, clones a template Stock row (all 158 columns), and INSERTs the new product with the correct barcode, price, unit cost, department, category and supplier. Health = /api/sync/np-agent-status.

Remove Product — removeproduct.ps1 (every 5 min)

Polls for delete jobs. Before deleting it logs the product's full row to removeproduct.log as a recovery snapshot, then hard-deletes it and verifies zero rows remain. Idempotent (already-gone counts as done). Health = /api/sync/rp-agent-status.

API endpoints

Auth key: Public = open read-only (this page uses these) · Shop token = the agent's X-RG-Shop-Id + X-RG-Shop-Token (sha256-hashed on the VM) · App session = the dashboard's signed bearer token.

Endpoint	Method / Auth	What it does & how it checks
`/api/health`	GET Public	Sync freshness (`sync_fresh`, last sync time, latest data date) and the writeback agent's heartbeat age. Powers the Data Sync + Writeback cards.
`/api/sync/writeback-log`	GET Public	Last 15 jobs from the past 7 days, all types, tagged with `field` (price / cost / new_product / delete), status, source, timestamps and the verified flag. Powers the E2E, New Products and Removed Products lists.
`/api/sync/np-agent-status`	GET Public	New-product agent liveness: `deployed`, `alive` (polled within 15 min), `age_min`, `agent_version`. Recorded each time the agent polls.
`/api/sync/rp-agent-status`	GET Public	Remove-product agent liveness, same shape as np-agent-status. Populated on the remove agent's next poll of delete-jobs.
`/api/sync/heartbeat`	POST Shop token	Writeback agent check-in. Records the heartbeat and delivers pending price/cost jobs. Re-delivers until the agent reports a result.
`/api/sync/new-product-jobs`	POST Shop token	Delivers pending `new_product` jobs to the add agent and records its liveness (`agent_version` + last poll).
`/api/sync/delete-jobs`	POST Shop token	Delivers pending `delete` jobs to the remove agent and records its liveness. Delete jobs are kept off the price heartbeat so only this agent sees them.
`/api/sync/job-result`	POST Shop token	Any agent reports a job outcome (`applied` / `failed` + note). Flips the job's status on the VM.
`/api/price-jobs`	GET / POST App session	Dashboard lists every job (GET) or creates one (POST) with `field` = price / cost / new_product / delete. Validates: field whitelist; new_product needs a barcode matching `^[0-9]{4,20}$`, price > 0, cost ≥ 0; a delete needs a barcode and snapshots the product first (so it can be put back).
`/api/price-jobs/<id>/revert-delete`	POST App session	Puts a removed product back: reads the delete job's stored snapshot and re-queues it as a new_product job. Refuses (409) if no snapshot was captured.
`/api/price-jobs/<id>/{confirm,dismiss,revert,verify-now}`	POST App session	Supporting price-job actions: push drafts, dismiss, revert an applied price change, and re-check verification.

How checks & validation actually work

Agent liveness — every poll writes last_poll = now() for that shop. A card is green when the last poll was within 15 minutes, otherwise yellow/red. "Not polled yet" means the table row hasn't been written since the feature went live (registers on the next 5-minute run).

Decimal safety — Pervasive ODBC rounds plain doubles to whole numbers, so the add agent coerces every money value to a decimal before binding (why a €1.52 price stores as 1.520, not 1).

Existence & idempotency — the add agent checks Code OR BarCode before inserting; the remove agent treats an already-gone product as success. Both keep their own log + acked file so a re-delivered job is safe.

Recovery snapshot — the remove agent logs the full product row before every hard delete, and the VM also stores a snapshot on the delete job, so a removal can be undone from the History page.

E2E verification — a price change is only "confirmed" once it has been applied on the PC and seen at the new value in the next sync back from the till — that round-trip is what the E2E card tracks.