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

# Merchandising & Content Toolkit architecture

> Runtime, product data flow, and storefront rendering for Merchandising & Content Toolkit.

# 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](https://docs.pcnaid.com/nodes/shopify/merchandising-content-toolkit/developer/api/index.md) for the documented interfaces.

See the [merchant setup guide](https://docs.pcnaid.com/nodes/shopify/merchandising-content-toolkit/merchant/guides/index.md) for the store-facing workflow.


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