> ## Documentation Index
> Fetch the complete documentation index at: https://topten.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture Overview

> How Live Product Insights works: the storefront tracker, the app proxy, the embedded admin app, Shopify webhooks, and the in-process background scheduler.

Live Product Insights is an embedded Shopify admin app with a companion theme
app extension. Four planes make up the system:

1. **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.
2. **Shopify platform** — webhooks deliver orders, refunds, catalog changes,
   inventory updates, app lifecycle events, and mandatory privacy requests.
3. **Admin** — an embedded React Router app renders Polaris dashboards computed
   by a shared metrics library.
4. **Background** — an in-process scheduler generates insights, catches up on orders, builds daily rollups, and prunes
   expired data.

```mermaid theme={null}
graph TD
  subgraph SF["Storefront (theme app extension)"]
    TR["Tracker app embed"] --> PX["Shopify app proxy /apps/live-view/*"]
    CB["Live View Counter block"] --> PX
  end
  subgraph SP["Shopify platform"]
    WH["Webhooks: orders, refunds, products, inventory, lifecycle, GDPR"] --> WR["Webhook routes"]
  end
  PX --> IN["Ingest route (HMAC-verified)"] --> DB[("SQLite")]
  PX --> ST["Stats route (HMAC-verified)"] --> DB
  WR --> DB
  subgraph AD["Admin (embedded app)"]
    UI["React Router + Polaris dashboards"] --> ML["Metrics library"] --> DB
  end
  subgraph BG["Background (in-process)"]
    CR["node-cron scheduler"] --> DB
  end
```

## Stack

| Layer | Technology |
| - | - |
| App framework | React Router 7 (framework mode, file-system routes) on Vite |
| Admin UI | React 18, Shopify Polaris 13, App Bridge, ApexCharts |
| Data | Prisma 6 with SQLite (single database file) |
| Runtime | Node.js 20.19+ / 22.12+, one web process |
| Background work | node-cron (in-process) |
| Storefront | Liquid theme app extension: tracker app embed + Live View Counter block |
| APIs | Shopify Admin GraphQL API (catalog and order sync), app proxy, webhooks |

## 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](https://topten.mintlify.site/privacy.md).
* **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.

> [!NOTE]
>
> Every metric displayed in the admin shows its time window. The definitions
> behind those numbers are documented in [Measurement](https://topten.mintlify.site/measurement.md) and are
> the contract the metrics library implements.

## Where to go next

> [card] [Storefront tracker](https://topten.mintlify.site/architecture/storefront-tracker.md)
>
> Event types, identity, dedupe, consent gating, and transport.

> [card] [App proxy API](https://topten.mintlify.site/architecture/app-proxy-api.md)
>
> The ingest and stats endpoints, authentication, and rate limits.

> [card] [Webhooks](https://topten.mintlify.site/architecture/webhooks.md)
>
> All 13 handled topics and their effects on stored data.

> [card] [Data model](https://topten.mintlify.site/architecture/data-model.md)
>
> The 14 tables, their logical relations, and data lifecycle.

> [card] [Background jobs](https://topten.mintlify.site/architecture/background-jobs.md)
>
> The scheduler, insight generation, order sync, rollups, and pruning.

> [card] [Development](https://topten.mintlify.site/development/local-development.md)
>
> Running, testing, and deploying the app.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.