- Storefront — a tracker app embed and the Live View Counter block collect real shopper activity and read the live count through Shopify’s app proxy.
- Shopify platform — webhooks deliver orders, refunds, catalog changes, inventory updates, app lifecycle events, and mandatory privacy requests.
- Admin — an embedded React Router app renders Polaris dashboards computed by a shared metrics library.
- Background — an in-process scheduler generates insights, catches up on orders, builds daily rollups, and prunes expired data.
Stack
Request paths
- Event ingest — the tracker batches events and sends them to the app-proxy endpoint. The app verifies Shopify’s proxy signature, rate-limits per shop, validates every event strictly, and writes sessions, presence, and events to SQLite. Malformed events are dropped, never fatal.
- Live count — the counter block polls the stats endpoint every 5 s. The app counts active sessions inside the configured presence window and decides whether the counter should be visible at all.
- Commerce data — webhook handlers upsert orders, apply refunds, mirror catalog and inventory changes into cache tables, and wipe shop data on uninstall or privacy requests.
- Dashboards — admin page loaders call the metrics library, which computes every number from raw events and orders inside the merchant-selected time window.
Key design decisions
- Single-instance deployment. SQLite, the per-shop rate limiter, the view-dedupe locks, and the order-sync throttle are all in-process and in-memory. The app is designed to run as one always-on machine; scaling out horizontally would require swapping these for shared stores.
- Consent-gated collection. The tracker sends nothing until the Shopify Customer Privacy API reports analytics processing as allowed. Unmanaged storefronts without the consent API proceed; a merchant-level opt-out flag is honored first. See Privacy and data.
- Honest counter contract. The counter renders only when the server says the product is countable and the count is above zero. It hides otherwise — it never shows a zero or an invented number.
- Webhook-driven attribution. Orders are attributed to tracked sessions only when the order carries a cart token that matches a tracked cart, inside the merchant-configurable attribution window. Orders synced through the Admin API catch-up cannot be attributed and are labeled honestly.
- No personal information. The schema stores no customer names, emails, or addresses. Shopper identity is a client-generated anonymous UUID.
Every metric displayed in the admin shows its time window. The definitions
behind those numbers are documented in Measurement and are
the contract the metrics library implements.
Where to go next
Storefront tracker
Event types, identity, dedupe, consent gating, and transport.
App proxy API
The ingest and stats endpoints, authentication, and rate limits.
Webhooks
All 13 handled topics and their effects on stored data.
Data model
The 14 tables, their logical relations, and data lifecycle.
Background jobs
The scheduler, insight generation, order sync, rollups, and pruning.
Development
Running, testing, and deploying the app.