Skip to main content

​
Merchandising & Content Toolkit architecture

​
Runtime

The app has a React admin interface (Shopify Polaris 13), a Node.js and Express API, PostgreSQL through Prisma, Redis, and BullMQ background workers. Shopify theme app extensions render content and collection features on the storefront. The frontend is a React single-page application embedded in Shopify admin via App Bridge v4, with all merchant-facing routes under /app.

​
Product data flow

  • Sorting — sorting rules drive background collection updates. When Shopify reports a product or inventory change, or a rule runs on a schedule or manually, a BullMQ job reorders the collection using Shopify’s collectionReorderProducts mutation. Each rule targets one collection.
  • Hierarchy — collection parent/child relationships are stored in Shopify collection metafields and read by the Breadcrumbs and Sub-Collections theme blocks.
  • Content — Content Builder blocks are stored as toolkit_content_block metaobjects referenced from the toolkit.content_blocks metafield (with a legacy toolkit.content_data JSON fallback). Theme blocks render that content on the storefront.

​
Storefront rendering

The toolkit-renderer theme app extension provides seven blocks: Breadcrumbs, Sub-Collections, Content Renderer, Recently Viewed, Smart Urgency Badges, Toolkit A/B & Tracking (storefront collector), and Market-aware ranking. Hierarchy and content blocks read directly from Shopify metafields. Recently Viewed uses browser-local history and Shopify’s product JSON endpoint and does not call the app’s backend. The A/B collector calls the public metric API and attributes paid-order revenue via signed cart receipts and the orders/paid webhook.

​
Public surfaces

The API exposes authenticated admin routes, public health endpoints, public storefront A/B and market-ranking routes, and unauthenticated marketing, pricing, and policy pages. See the API overview for the documented interfaces. See the merchant setup guide for the store-facing workflow.