PLP 2.0 Architecture

System overview and data flow

The new PLP 2.0 implements a hybrid data architecture combining multiple data sources through a multi-phase loading strategy. This is an API driven approach integrating with Search Spring, Shopify and Builder.io.

Data Flow Diagram

Loading Phases

Phase	Purpose	Data Source	Key Files
1	Critical metadata + initial products	Shopify + Search Spring	collection.ts, loader.helper.server.ts
2	CMS-managed content	Builder.io	loader.helper.server.ts
3	Session restoration	Cookie + Search Spring	session.server.ts
4	Product enrichment	Shopify Storefront API	collection.ts

Integration points with Shopify

Shopify Storefront API (GraphQL)

Used for authoritative product and collection data:

Query	Purpose	File
SEARCH_SPRING_COLLECTION_QUERY	Collection metadata, metafields, SEO	CollectionQuery.ts
GET_PLP_PRODUCT_DATA_BY_HANDLE	Product pricing, images, variants	ProductQuery.ts
GET_COLOR_BUBBLE_META_BY_HANDLE	Color swatch thumbnails	ProductQuery.ts
COLLECTION_QUERY_BY_ID	Rec tray collection products	CollectionQuery.ts

Key Metafields Retrieved:

• enable_rollup - Whether to group products by style/fabric/type
• enable_color_bar - Show color bar
• enable_rts - 'Ready To Ship' toggle
• visual_navigation - Builder content ID
• rec_tray - Recommendation tray Builder ID
• sub_navigation - Subcollection tabs
• alternate_title / enable_shop_all - Title display options

Search Spring API (REST)

Primary source for product search, filtering, and sorting. Routes through internal API endpoint:

const url = `${origin}${APIRoutes.COLLECTION_PAGE}${handle}?${params.toString()}`;

Returns:

• results - Array of SanitizedSearchProductResult with basic product info
• facets - Available filters (color, size, type, etc.)
• sorting - Available sort options
• pagination - Page info (currentPage, nextPage, totalPages)
• merchandising - Inline banner configurations
• filterSummary - Currently active filters

Builder.io CMS

Content management for merchandising elements:

Model	Purpose
plp-visual-navigation	Visual nav tiles at top of PLP
rec-tray	Recommended products carousel

Key technical constraints and issues

Technical Constraints

1. Feature Flag Gate - Needed to build this behind a feature gate to allow for production testing while maintaining current experience for customers.
2. Rollup Collection Complexity - Products grouped by style-fabric-type key, requires pre-fetching rollup map. Requires creating and maintaining our own pagination.
3. Deferred Data Pattern - Product enrichment uses promises that resolve during render with React Suspense. There is an active ticket to SSR this with Search Spring data and hydrate with Shopify data.
4. Multiple Data Sources - Needed to pull in data from multiple sources to satisfy requirements from all stakeholders. This adds complexity and multiple points of failure to capture.

Known issues and technical debt

Issue	Location	Description
No Search Spring fallback	loader.helper.server.ts:31	No fallback to Storefront API if Search Spring fails. There is a ticket in the current sprint to resolve data with Shopify if Search Spring does not respond.
Sequential page fetching	Route lines 147-156	Session restoration fetches pages sequentially, not in parallel
Rollup Map Caching	API	Need to move the rollup map creation and caching to our CDN. There is currently a ticket in this sprint for this