Architecture Overview

Commerce Connect bridges WordPress and BigCommerce, combining WordPress content/SEO strengths with BigCommerce commerce capabilities. This guide explains how the system works under the hood.

System Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         Customer Request                          │
└─────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────┐
│                        WordPress (Frontend)                       │
│  • FSE Blocks render cached product data                        │
│  • SEO metadata generated from product cache                    │
│  • Content pages with embedded product displays                 │
└─────────────────────────────────────────────────────────────────┘
                                  │
                    Browse Products │ Add to Cart / Checkout
                                  │
                    ┌─────────────┴─────────────┐
                    ▼                           ▼
┌──────────────────────────────┐   ┌──────────────────────────────┐
│   Commerce Connect Plugin    │   │   BigCommerce Checkout       │
│                              │   │   (Hosted)                   │
│  • Product sync engine       │   │                              │
│  • API client                │   │  • Secure payment processing │
│  • Block renderer            │   │  • Order management          │
│  • Webhook processor         │   │  • Fraud protection          │
│  • Cache management          │   │  • PCI compliance            │
└──────────────────────────────┘   └──────────────────────────────┘
                │                                   │
                ▼                                   ▼
┌──────────────────────────────┐   ┌──────────────────────────────┐
│   WordPress Database         │   │   BigCommerce API            │
│   (Product Cache)            │   │   (Source of Truth)          │
│                              │   │                              │
│  • cc_products CPT           │◀──│  • Products catalog          │
│  • cc_product_meta           │   │  • Inventory                 │
│  • cc_categories             │   │  • Pricing                   │
│  • Transients (temp cache)   │   │  • Orders                    │
└──────────────────────────────┘   └──────────────────────────────┘
                ▲
                │
         Webhook Events
        (Real-time sync)

---

Core Components

1. Sync Engine

Purpose: Keep WordPress product cache synchronized with BigCommerce.

How it works:

┌──────────────┐
│ Sync Trigger │ (Manual, cron, or webhook)
└──────┬───────┘
       │
       ▼
┌──────────────────────────────────────────┐
│ Fetch products from BigCommerce API     │
│ • Paginated requests (50 products/page) │
│ • Include variants, images, categories  │
└──────┬───────────────────────────────────┘
       │
       ▼
┌──────────────────────────────────────────┐
│ Transform to WordPress data structure   │
│ • Map BigCommerce fields → WP fields    │
│ • Handle variants as post meta          │
│ • Process images for WP media library   │
└──────┬───────────────────────────────────┘
       │
       ▼
┌──────────────────────────────────────────┐
│ Upsert to WordPress database            │
│ • Create/update cc_products CPT         │
│ • Store metadata in cc_product_meta     │
│ • Create category terms                 │
└──────┬───────────────────────────────────┘
       │
       ▼
┌──────────────┐
│ Cache Clear  │ (Invalidate transients)
└──────────────┘

Sync frequency:

• Manual: On-demand via Settings → Data → Sync Products
• Webhooks: Real-time when products change in BigCommerce
• Cron: Fallback daily sync (configurable)

Performance notes:

• Batch size: 50 products per API request
• Rate limiting: 20,000 requests per hour (BigCommerce limit)
• First sync: ~1 product per second (~1 hour for 3,600 products)
• Subsequent syncs: Only changed products processed

---

2. Webhook System

Purpose: Receive real-time notifications from BigCommerce when products change.

Webhook registration flow:

WordPress Admin
    │
    ▼
Settings → Webhooks → Register Webhooks
    │
    ▼
Commerce Connect sends webhook registration to BigCommerce API:
POST /v3/hooks
{
  "scope": "store/product/*",
  "destination": "https://yoursite.com/wp-json/cc/v1/webhook",
  "is_active": true
}
    │
    ▼
BigCommerce confirms registration and returns hook ID
    │
    ▼
Commerce Connect stores hook ID in WordPress options

Webhook processing:

BigCommerce product change event
    │
    ▼
POST to https://yoursite.com/wp-json/cc/v1/webhook
{
  "scope": "store/product/updated",
  "data": { "id": 123, "type": "product" }
}
    │
    ▼
Commerce Connect webhook endpoint:
1. Validate webhook signature (HMAC)
2. Queue product ID for sync
3. Return 200 OK immediately
    │
    ▼
Background process fetches product 123 from API
    │
    ▼
Product data updated in WordPress cache
    │
    ▼
Page cache cleared for affected pages

Supported events:

• store/product/created - New product added
• store/product/updated - Product details changed
• store/product/deleted - Product removed
• store/product/inventory/updated - Stock level changed

---

3. Block Renderer

Purpose: Display product data in WordPress pages using FSE blocks.

Block rendering lifecycle:

1. Editor Load (Edit mode)
   ├─ Block registered via block.json
   ├─ Edit component loads (React)
   ├─ Product data fetched via @wordpress/data store
   └─ Inspector controls render settings panel

2. Block Save (Static markup)
   ├─ Save function generates static HTML structure
   ├─ Product ID stored as data attribute
   └─ Placeholder content for SEO crawlers

3. Frontend Render (Dynamic PHP)
   ├─ render_callback invoked by WordPress
   ├─ Product data fetched from cache (CPT)
   ├─ Template populated with actual data
   └─ HTML output returned

Example block render flow:

// Block registration
register_block_type(__DIR__ . '/blocks/product-title', [
    'render_callback' => 'cc_render_product_title',
]);

// Render callback
function cc_render_product_title($attributes, $content, $block) {
    // 1. Get product ID from block context or attributes
    $product_id = $block->context['commerce-connect/productId'] ?? 0;

    // 2. Fetch from cache (no API call)
    $product = get_post($product_id);

    // 3. Render template
    return sprintf(
        '<h1 class="cc-product-title">%s</h1>',
        esc_html($product->post_title)
    );
}

Block categories:

Category	Count	Purpose
Product Display	7	Single product information (title, price, images, etc.)
Product Collections	9	Product grids, filters, search
Reviews	6	Product reviews and ratings
Account	7	Customer login, registration, orders
Category	5	Category navigation
Utility	3	Cart icon, related products

---

Data Flow Scenarios

Scenario 1: Customer Browses Product

1. Customer visits https://yoursite.com/shop/
   │
   ▼
2. WordPress loads page template
   │
   ▼
3. Products Grid block renders
   │
   ▼
4. Block queries WordPress database (cc_products CPT)
   │
   ▼
5. Cached product data returned (NO API call)
   │
   ▼
6. Block renders HTML with product cards
   │
   ▼
7. Page served to customer (<300ms typical load)

Performance: Fast because no BigCommerce API calls during page render.

---

Scenario 2: Product Updated in BigCommerce

1. Merchant changes product price in BigCommerce admin
   │
   ▼
2. BigCommerce triggers webhook
   POST https://yoursite.com/wp-json/cc/v1/webhook
   │
   ▼
3. Commerce Connect validates webhook signature
   │
   ▼
4. Product ID queued for sync
   │
   ▼
5. Background process fetches updated product from API
   GET /v3/catalog/products/123
   │
   ▼
6. WordPress cache updated (cc_products CPT)
   │
   ▼
7. Page cache cleared for affected pages
   │
   ▼
8. Next customer page load shows new price

Latency: Latency: Typically 5-10 seconds from BigCommerce change to WordPress cache update..

---

Scenario 3: Customer Adds to Cart

1. Customer clicks "Add to Cart" on product
   │
   ▼
2. JavaScript captures click event
   │
   ▼
3. Product data sent to BigCommerce Cart API
   POST /v3/carts
   │
   ▼
4. BigCommerce returns cart ID and checkout URL
   │
   ▼
5. Customer redirected to checkout.yourdomain.com
   │
   ▼
6. BigCommerce hosted checkout loads
   │
   ▼
7. Customer completes purchase on BigCommerce
   │
   ▼
8. Order stored in BigCommerce (not WordPress)

Why redirect to BigCommerce?

• PCI compliance handled by BigCommerce
• Fraud protection built-in
• Payment gateway integrations maintained by BigCommerce
• Reduces WordPress security surface area

---

Database Schema

Custom Post Type: cc_products

wp_posts
├─ post_type = 'cc_product'
├─ post_title = Product name
├─ post_content = Product description (HTML)
├─ post_status = 'publish' | 'draft'
└─ post_name = Product slug (for URLs)

wp_postmeta (cc_product_meta)
├─ bigcommerce_id (int) - BC product ID
├─ sku (string) - Product SKU
├─ price (decimal) - Regular price
├─ sale_price (decimal) - Sale price
├─ calculated_price (decimal) - Final price
├─ inventory_level (int) - Stock quantity
├─ weight (decimal) - Product weight
├─ variants (json) - Product variants
├─ images (json) - Product images array
└─ custom_fields (json) - Additional metadata

Custom Taxonomy: cc_product_category

wp_terms
├─ name = Category name
└─ slug = Category slug

wp_term_taxonomy
├─ taxonomy = 'cc_product_category'
└─ description = Category description

wp_term_relationships
└─ Links products to categories

Options Table

wp_options
├─ cc_bigcommerce_store_hash
├─ cc_bigcommerce_access_token
├─ cc_webhook_secret
├─ cc_registered_webhooks (json)
└─ cc_sync_last_run (timestamp)

---

Performance Optimization

Caching Strategy

1. Object Cache (Transients)

// Cache product data for 1 hour
set_transient('cc_product_' . $product_id, $product_data, HOUR_IN_SECONDS);

2. Full Page Cache

• WP Engine Full Page Cache enabled
• Cache invalidation on product sync
• Cache key includes product version

3. Image Optimization

• BigCommerce CDN for product images
• Lazy loading via native browser API
• Responsive image sizes via srcset

Query Optimization

Avoid N+1 queries:

// BAD: N+1 query (1 query per product)
foreach ($product_ids as $id) {
    $product = get_post($id);
    // ...
}

// GOOD: Single query for all products
$products = get_posts([
    'post_type' => 'cc_product',
    'post__in' => $product_ids,
    'posts_per_page' => -1,
]);

Use meta query optimization:

// Indexed meta query
$products = new WP_Query([
    'post_type' => 'cc_product',
    'meta_query' => [
        [
            'key' => 'bigcommerce_id',
            'value' => [123, 456, 789],
            'compare' => 'IN',
        ],
    ],
]);

---

Security Considerations

Webhook Validation

HMAC signature verification:

function verify_webhook_signature($payload, $signature) {
    $secret = get_option('cc_webhook_secret');
    $expected = hash_hmac('sha256', $payload, $secret);
    return hash_equals($expected, $signature);
}

API Credentials Storage

• Access tokens: Encrypted in wp_options table
• Webhook secrets: Hashed before storage
• Never log credentials: Redacted in debug logs

User Permissions

// Require admin permissions for settings
if (!current_user_can('manage_options')) {
    wp_die('Unauthorized');
}

---

Debugging

Enable Debug Mode

wp-config.php

define('CC_DEBUG', true);
define('WP_DEBUG_LOG', true);

View Debug Logs

tail -f wp-content/debug.log | grep 'Commerce Connect'

Debug Webhook Delivery

# Check webhook registration
wp option get cc_registered_webhooks

# Test webhook manually
curl -X POST https://yoursite.com/wp-json/cc/v1/webhook \
  -H "Content-Type: application/json" \
  -H "X-BC-Webhook-Signature: test" \
  -d '{"scope":"store/product/updated","data":{"id":123}}'

---

Extensibility Points

Hooks for Developers

Filter product data before display:

add_filter('commerce_connect_product_data', function($product) {
    // Modify product data
    return $product;
});

Customize sync behavior:

add_action('commerce_connect_before_product_sync', function($product_ids) {
    // Run custom logic before sync
});

Modify block output:

add_filter('commerce_connect_block_render', function($html, $block_name, $attributes) {
    // Customize block HTML
    return $html;
}, 10, 3);

Full reference: Hooks & Filters

---

Next Steps

• API Reference - PHP classes and REST endpoints
• Custom Blocks - Build your own blocks
• Hooks & Filters - 27+ extensibility hooks
• Quick Start (Developer) - Build first customization

Questions? Contact WP Engine Support