Architecture

Technical architecture of SOG Knives BigCommerce site with Contentful CMS and custom engraving tool

Platform Overview

SOG Knives is built on BigCommerce using the Stencil theme framework. The architecture follows a hybrid approach with BigCommerce handling e-commerce operations while Contentful manages editorial content.

┌─────────────────────────────────────────────────────┐
│                  SOG Knives Site                    │
├─────────────────────────────────────────────────────┤
│                                                     │
│  ┌──────────────┐         ┌──────────────┐        │
│  │  BigCommerce │◄────────►│  Contentful  │        │
│  │  (E-commerce)│         │     (CMS)     │        │
│  └──────────────┘         └──────────────┘        │
│         ▲                         ▲                │
│         │                         │                │
│         ▼                         ▼                │
│  ┌────────────────────────────────────────┐       │
│  │      SOG-Rhino Custom Theme            │       │
│  │  (Cornerstone v5.0.19 + Extensions)    │       │
│  └────────────────────────────────────────┘       │
│         ▲                         ▲                │
│         │                         │                │
│         ▼                         ▼                │
│  ┌──────────────┐         ┌──────────────┐        │
│  │   Engraving  │         │  Instagram   │        │
│  │     Tool     │◄────────►│     Feed     │        │
│  │   (Preact)   │         │  (Elfsight)  │        │
│  └──────────────┘         └──────────────┘        │
│         │                                          │
│         ▼                                          │
│  ┌──────────────────────┐                         │
│  │  GSM Outdoors API    │                         │
│  │  (Engraving Orders)  │                         │
│  └──────────────────────┘                         │
│                                                     │
└─────────────────────────────────────────────────────┘

BigCommerce Stencil Framework

Theme Structure

The SOG-Rhino theme follows the standard Stencil directory layout with custom extensions:

sog-theme/
├── assets/                    # Static assets
│   ├── fonts/                 # Stratum2 and custom fonts
│   ├── icons/                 # SVG icons
│   ├── img/                   # Images
│   └── scss/                  # Sass stylesheets
├── lang/                      # Internationalization
├── templates/                 # Handlebars templates
│   ├── components/            # Reusable components
│   ├── layout/                # Layout templates
│   └── pages/                 # Page templates
│       ├── product.html       # Product detail (engraving tool)
│       ├── category.html      # Category (Contentful sections)
│       └── home.html          # Homepage (Contentful hero)
├── config.json                # Theme configuration
├── meta/                      # Theme metadata
├── schema.json                # Customizer schema
└── webpack.config.js          # Custom Webpack config

Stencil CLI

Version: 8.10.5

The theme is developed and deployed using BigCommerce Stencil CLI:

# Local development
stencil start

# Bundle for upload
stencil bundle

# Push to BigCommerce
stencil push

Theme Configuration

Theme configuration is managed in config.json:

{
  "name": "SOG-Rhino",
  "version": "6.0.34",
  "meta": {
    "composed_image": "composed.png",
    "screenshot": "screenshot.png"
  },
  "settings": {
    "engraving_enabled": true,
    "contentful_space": "zg6h9gisshv3",
    "contentful_access_token": "{secure}",
    "instagram_feed_enabled": true
  }
}

Contentful CMS Integration

Architecture Pattern

SOG uses a content API architecture where Contentful serves as a headless CMS alongside BigCommerce:

1. Content authors create/edit content in Contentful
2. Contentful API delivers JSON to the theme
3. Theme templates render Contentful data with Handlebars
4. Client-side JavaScript handles dynamic content updates

API Integration

Contentful Configuration

• Space ID: zg6h9gisshv3
• Environment: master
• API: Content Delivery API (CDA)
• Access: Read-only delivery token

API Calls

Content is fetched during page render and cached:

// assets/js/contentful.js
const contentfulClient = contentful.createClient({
  space: 'zg6h9gisshv3',
  accessToken: window.contentfulToken,
  environment: 'master'
});

// Fetch homepage hero
async function getHomepageHero() {
  const entries = await contentfulClient.getEntries({
    content_type: 'homepageHero',
    limit: 1,
    order: '-sys.createdAt'
  });
  return entries.items[0];
}

Caching Strategy

• Server-side: BigCommerce caches Contentful responses (5 minutes)
• Client-side: LocalStorage cache with TTL
• Invalidation: Webhook from Contentful on publish triggers cache clear

Engraving Tool Architecture

Technology Stack

• Framework: Preact (lightweight React alternative)
• Rendering: HTML5 Canvas API
• State Management: Preact hooks (useState, useEffect)
• API Integration: GSM Outdoors engraving API

Component Structure

Engraving Tool (Preact App)
├── EngraveForm
│   ├── FontSelector (15 fonts)
│   ├── TextInput (with validation)
│   ├── PositionControl
│   └── PreviewCanvas
├── EngraveAPI
│   ├── submitEngraving()
│   ├── validateText()
│   └── generatePreview()
└── GSMApiClient
    └── POST /api/engraving/orders

Data Flow

1. Customer enters engraving text and selects font
2. Preact renders preview on canvas in real-time
3. On submit, data sent to GSM Outdoors API
4. API validates and creates engraving order
5. Order ID attached to BigCommerce cart item
6. Confirmation displayed to customer

Integration Points

GSM Outdoors API

Base URL: https://api.gsmoutdoors.com/v1

Engraving Endpoint

POST /api/engraving/orders
Content-Type: application/json
Authorization: Bearer {api_key}

{
  "product_id": "12345",
  "engraving_text": "John Smith",
  "font": "stratum2-bold",
  "position": "centered",
  "line_spacing": 1.2
}

Response:

{
  "engraving_id": "eng_abc123",
  "preview_url": "https://cdn.gsmoutdoors.com/previews/eng_abc123.png",
  "status": "pending"
}

Instagram Feed (Elfsight)

Widget Type: Instagram Feed
Integration: JavaScript embed

<script src="https://apps.elfsight.com/p/platform.js" defer></script>
<div class="elfsight-app-{widget-id}"></div>

Content updates automatically via Elfsight service.

Security Considerations

API Keys

• Contentful tokens: Server-side only, never exposed to client
• GSM API keys: Backend proxy handles authentication
• Instagram: Public widget, no sensitive data

Data Validation

• Engraving text sanitized server-side
• SQL injection prevention (parameterized queries)
• XSS protection (escaped template output)
• Rate limiting on engraving API (10 requests/min)

HTTPS/TLS

• All API calls over HTTPS
• BigCommerce enforces TLS 1.2+
• Contentful CDN uses TLS 1.3

Performance Optimization

Caching Layers

1. CDN: BigCommerce CDN caches static assets
2. API: Contentful responses cached 5 minutes
3. Browser: LocalStorage for content, SessionStorage for cart

Asset Optimization

• Fonts: WOFF2 format, subset to used glyphs
• Images: WebP with JPG fallback, lazy loading
• JavaScript: Code splitting, async loading
• CSS: Critical CSS inlined, rest deferred

Metrics

• Time to Interactive (TTI): ~2.5s
• First Contentful Paint (FCP): ~1.2s
• Largest Contentful Paint (LCP): ~2.0s

Deployment Architecture

Environments

Environment	URL	Purpose
Production	sogknives.com	Live customer site
Staging	staging.sogknives.com	QA testing
Development	localhost:3000	Local development

Deployment Process

1. Develop locally using Stencil CLI
2. Test on localhost:3000
3. Bundle theme with stencil bundle
4. Push to staging with stencil push
5. QA approval on staging
6. Deploy to production via BigCommerce admin

Version Control

• Theme code in private Git repository
• Semantic versioning (v6.0.34)
• Changelog maintained for releases
• Rollback capability via theme backups

Monitoring & Analytics

Analytics Platforms

• Google Analytics 4: E-commerce tracking
• BigCommerce Analytics: Built-in metrics
• Contentful Analytics: Content performance

Custom Tracking

• Engraving tool interactions (start, preview, submit)
• Instagram feed clicks
• Contentful content impressions
• Error tracking (Sentry integration)

Health Checks

• Uptime monitoring: Pingdom
• API health: GSM Outdoors API status endpoint
• Contentful status: https://www.contentfulstatus.com

Disaster Recovery

Backup Strategy

• Theme backups: Automated daily via BigCommerce
• Contentful: Built-in versioning and backups
• Database: BigCommerce handles automatically

Recovery Procedures

1. Theme rollback: Revert to previous version in BigCommerce admin
2. Content rollback: Restore from Contentful version history
3. API failure: Graceful degradation (engraving disabled with notice)

Failover

• CDN: Multiple edge locations for redundancy
• API: Retry logic with exponential backoff
• Content: Cached fallback if Contentful unavailable