Skip to main content

Platform Architecture

Muddy uses a headless commerce architecture where WordPress serves as the content management and presentation layer while BigCommerce handles the e-commerce backend (products, cart, checkout, orders).

System Overview​

┌──────────────────────────────────────────────────────────────┐
│                      Customer Browser                         │
└────────────┬─────────────────────────────────────────────────┘
             │
             │ HTTPS
             │
┌────────────▼─────────────────────────────────────────────────┐
│                     WordPress Frontend                        │
│  ┌────────────────┐  ┌────────────────┐  ┌────────────────┐ │
│  │  Suma Elementor│  │   FacetWP      │  │    Algolia     │ │
│  │  Theme v2.5.0  │  │   v4.3.3       │  │    v2.8.1      │ │
│  └────────────────┘  └────────────────┘  └────────────────┘ │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  BigCommerce for WordPress (Suma v5.0.7.10)            │ │
│  │  - Product sync                                         │ │
│  │  - Cart API proxy                                       │ │
│  │  - Checkout redirect                                    │ │
│  └──────────────────┬─────────────────────────────────────┘ │
└─────────────────────┼───────────────────────────────────────┘
                      │
                      │ REST API + GraphQL
                      │ (OAuth + API Token)
                      │
┌─────────────────────▼───────────────────────────────────────┐
│                  BigCommerce Backend                         │
│  ┌────────────────┐  ┌────────────────┐  ┌────────────────┐│
│  │   Products     │  │   Cart API     │  │   Customers    ││
│  │   (Catalog)    │  │                │  │   (Accounts)   ││
│  └────────────────┘  └────────────────┘  └────────────────┘│
│  ┌────────────────┐  ┌────────────────┐  ┌────────────────┐│
│  │   Orders       │  │   Checkout     │  │   Payments     ││
│  │                │  │   (Optimized)  │  │                ││
│  └────────────────┘  └────────────────┘  └────────────────┘│
└─────────────────────────────────────────────────────────────┘

Data Flow​

Product Data Synchronization​

BigCommerce is the single source of truth for product data. WordPress maintains a cached copy for display and search purposes.

BigCommerce Products
      │
      │ 1. Webhook triggers on product update
      │
      ▼
WordPress Import Queue
      │
      │ 2. BC4WP imports via REST API
      │
      ▼
WordPress Products (CPT)
      │
      │ 3. FacetWP indexes product attributes
      │    Algolia indexes search data
      │
      ▼
Frontend Product Display

Import Process:

  • Initial Import: Bulk import via WP-CLI or admin panel
  • Incremental Updates: Webhooks trigger real-time sync
  • Scheduled Sync: Daily cron job for full reconciliation

Synced Data:

  • Product names, descriptions, SKUs
  • Pricing (regular, sale, tax)
  • Inventory levels
  • Images and media
  • Custom fields and attributes
  • Categories and tags

Shopping Cart Flow​

Cart operations use BigCommerce's Cart API with WordPress as a proxy.

1. Customer adds product to cart
   └─> WordPress AJAX request
       └─> BC4WP creates/updates cart via BC API
           └─> Returns cart ID (cookie stored)

2. Customer views cart
   └─> WordPress loads cart data via BC API
       └─> Renders cart with WP template

3. Customer clicks checkout
   └─> WordPress redirects to BC checkout
       └─> bigcommerce.com/checkout/[cart_id]

4. Customer completes purchase
   └─> BigCommerce processes payment
       └─> Webhook notifies WordPress
           └─> BC4WP imports order

Cart Features:

  • Persistent cart (cookie-based)
  • Guest checkout support
  • Saved cart for logged-in users
  • Cart abandonment tracking (Klaviyo)

Order Processing​

BigCommerce Checkout (Payment)
      │
      │ Customer completes purchase
      │
      ▼
BigCommerce Order Created
      │
      │ Webhook: store/order/created
      │
      ▼
WordPress Order Import
      │
      │ BC4WP creates WooCommerce order
      │
      ▼
Order Fulfillment
      │
      ├─> Narvar Middleware (tracking)
      ├─> Email notifications (Klaviyo)
      └─> Analytics events (GTM)

Customer Account Flow​

Customer accounts are managed in BigCommerce with WordPress acting as a frontend.

Customer Registration/Login
      │
      │ WordPress form submission
      │
      ▼
BigCommerce Customer API
      │
      │ Create/authenticate customer
      │
      ▼
WordPress User Creation
      │
      │ Sync customer data to WP user
      │
      ▼
Frontend Account Dashboard
      (WordPress template)

Integration Points​

HuntStand Integration​

HuntStand is a hunting app platform. The integration enables cross-platform product recommendations.

Implementation:

  • Custom API endpoint in WordPress
  • Product data export to HuntStand format
  • OAuth authentication
  • Real-time inventory sync

Data Exchange:

// Example endpoint: /wp-json/huntstand/v1/products
{
  "products": [
    {
      "id": 12345,
      "name": "Apex Hang-On Stand",
      "sku": "MUD-APEX-001",
      "price": 229.99,
      "inventory": 45,
      "category": "tree-stands",
      "image_url": "https://cdn.gomuddy.com/..."
    }
  ]
}

Promo Flags System​

Custom promotional messaging system for product callouts.

Architecture:

  • Custom post type: promo_flag
  • Product association via custom fields
  • Priority-based display rules
  • Time-based scheduling

Display Logic:

// Get active promo flags for product
$promo_flags = get_product_promo_flags( $product_id );

// Display highest priority flag
if ( ! empty( $promo_flags ) ) {
    $flag = $promo_flags[0];
    echo '<div class="promo-flag ' . esc_attr( $flag->type ) . '">';
    echo esc_html( $flag->message );
    echo '</div>';
}

Flag Types:

  • sale - Sale/discount promotion
  • new - New product launch
  • exclusive - Limited availability
  • featured - Featured product

Performance Architecture​

Caching Strategy​

Page Caching:

  • WP Rocket or similar for full-page caching
  • Exclude cart/checkout pages
  • Vary cache by customer login state

Object Caching:

  • Redis or Memcached for WordPress object cache
  • Cache BigCommerce API responses (5-15 min TTL)
  • Transient API for temporary data storage

CDN:

  • Cloudflare or similar for static asset delivery
  • Image optimization and lazy loading
  • Cache product images (long TTL)

Database Optimization​

Custom Tables:

  • bc_import_queue - Product import queue
  • bc_sync_log - Synchronization history
  • promo_flags - Promotional flag assignments

Indexes:

-- Product meta lookups
CREATE INDEX idx_product_bc_id ON wp_postmeta(meta_key, meta_value(50)) 
WHERE meta_key = 'bigcommerce_id';

-- Fast category queries
CREATE INDEX idx_term_relationships ON wp_term_relationships(object_id, term_taxonomy_id);

Security Architecture​

API Authentication​

BigCommerce API:

  • OAuth 2.0 authentication
  • API credentials stored in wp-config.php
  • Rate limiting: 20,000 requests/hour
  • IP whitelisting recommended

WordPress REST API:

  • JWT authentication for custom endpoints
  • Nonce verification for AJAX requests
  • Rate limiting via plugin (e.g., WP Limit Login Attempts)

Data Protection​

PCI Compliance:

  • No credit card data stored in WordPress
  • All payment processing on BigCommerce
  • SSL/TLS encryption for all connections

Customer Data:

  • Minimal PII stored in WordPress
  • Password hashing (bcrypt)
  • GDPR compliance features
  • Data export/deletion tools

Monitoring & Logging​

Application Monitoring​

Error Tracking:

  • PHP error logging
  • JavaScript error tracking (Sentry or similar)
  • BigCommerce API error logging

Performance Monitoring:

  • Query Monitor plugin for database queries
  • New Relic or similar APM tool
  • Server resource monitoring

Sync Monitoring​

Import Queue Status:

// Check import queue health
$pending = get_import_queue_count('pending');
$failed = get_import_queue_count('failed');

if ( $failed > 10 ) {
    trigger_alert('High number of failed imports');
}

Webhook Health:

  • Monitor webhook delivery success rate
  • Alert on webhook failures
  • Retry failed webhooks

Scalability Considerations​

Horizontal Scaling​

WordPress:

  • Multiple web servers behind load balancer
  • Shared session storage (Redis/Memcached)
  • Shared file storage (NFS/S3)

Database:

  • Read replicas for product queries
  • Master for write operations
  • Connection pooling

BigCommerce Limits​

API Rate Limits:

  • 20,000 requests/hour per store
  • Implement request queuing
  • Cache API responses aggressively

Webhook Limits:

  • Maximum 50 webhooks per store
  • Consolidate webhook handlers
  • Use single endpoint with routing

Disaster Recovery​

Backup Strategy​

WordPress:

  • Daily database backups (retained 30 days)
  • Weekly full backups (retained 90 days)
  • File backups (wp-content only)

BigCommerce:

  • BigCommerce manages backend backups
  • Export order data regularly
  • Maintain product data export

Recovery Procedures​

Data Loss Scenarios:

  1. WordPress database corruption → Restore from backup, re-sync products
  2. Plugin failure → Rollback plugin, clear caches
  3. BigCommerce downtime → Display maintenance message, queue cart operations

Failover:

  • Static site generation for critical pages
  • Maintenance mode with custom messaging
  • Order notification system for offline orders