Edge Caching Strategy
Relevant source files
The following files were used as context for generating this wiki page:
The Edge Caching Strategy in the Commerce platform is designed to provide high-performance, multi-tenant data delivery while maintaining strict data isolation and surgical cache invalidation. It utilizes a tag-based system partitioned into specific namespaces—primarily shopify for commerce data and cms for content—ensuring that revalidation in one system does not inadvertently purge data in another.
The strategy relies on a structural invariant where every cached entity is both Tenant-scoped and Locale-qualified. This ensures that cache tags include a Shop key and a locale identifier, preventing cross-tenant data leakage and allowing for granular updates when content or products change within a specific shop or region.
Sources: CONTEXT.md:27-36, apps/storefront/README.md:104-108
Cache Partitioning and Taxonomy
The system employs Cache Namespaces to distinguish between different data lifecycles. This isolation prevents entanglement between unrelated systems.
| Namespace | Purpose | Source System |
|---|---|---|
shopify | Storefront product, collection, and catalog data. | Shopify Storefront API |
cms | Page content, articles, and global configurations. | Convex-native CMS |
Sources: CONTEXT.md:27-33, apps/storefront/README.md:131-133
Tag Structure
Tags are constructed using a hierarchical "leaf-to-root" pattern. This allows the system to invalidate a single item (leaf), a group of items (branch), or an entire tenant's data (root).
- Leaf:
cms.<shopId>.<collection>.<key>(e.g.,cms.shop-1.pages.home) - Branch:
cms.<shopId>.<collection>(e.g.,cms.shop-1.pages) - Tenant Root:
cms.<shopId>(Broad sweep for the whole tenant)
Sources: packages/cms/README.md:118-124, packages/convex/convex/revalidate/tags.test.ts:31-36
Revalidation Pipeline
Revalidation is triggered by external events, such as a CMS publish action or a Shopify webhook. The platform handles these through dedicated API routes that verify the authenticity of the request before executing revalidateTag.
CMS Revalidation Flow
When a document is published in the Admin CMS, a revalidation pipeline in Convex computes the necessary tags and delivers a signed HMAC event to the storefront.
The diagram shows how a publish event in the CMS flows through Convex to trigger a secure revalidation in the Next.js storefront.
Sources: packages/cms/README.md:114-118, apps/storefront/README.md:144-148
Shopify Webhook Revalidation
Shopify webhooks are accepted at /[domain]/api/revalidate. The system maps Shopify topics (e.g., product updates) to specific entity tags to perform surgical invalidation.
The sequence diagram illustrates the processing of a Shopify webhook, from HMAC validation to tag-based cache purging.
Sources: apps/storefront/README.md:137-142
Multi-Tenant Isolation
A core requirement of the caching strategy is that revalidating one tenant must not touch another's data. This is enforced by the inclusion of the shopId in every tag generated.
Tenant-Specific Root Tags
For operations that are not entity-specific, such as sitemap generation or broad tenant updates, the system uses "Tenant Root Tags."
// Example of deriving root tags for a shop
export function cmsTenantRootTags(shop: { id: string }) {
return [
`cms.${shop.id}`,
'cms'
];
}
Sources: packages/cms/src/cache-descriptor.ts:1-10, packages/convex/convex/revalidate/tags.test.ts:48-50
Security and Verification
To prevent unauthorized cache purging, revalidation endpoints are protected by shared secrets and HMAC signatures.
| Secret Variable | Purpose | Verified In |
|---|---|---|
CONVEX_REVALIDATE_SECRET | Validates signed revalidation events from Convex. | /api/revalidate/convex |
SHOPIFY_WEBHOOK_SECRET | Validates X-Shopify-Hmac-SHA256 headers. | /[domain]/api/revalidate |
Sources: apps/storefront/README.md:46-48, packages/cms/README.md:155-157
Summary
The Edge Caching Strategy leverages a sophisticated tag taxonomy and secure revalidation pipelines to balance performance with data freshness. By enforcing tenant and locale scoping at the tag level, the platform ensures that high-traffic multi-tenant environments remain performant and secure, allowing for instantaneous updates across Shopify and CMS data sources without broad cache over-purging.