Theme Structure

The WebbiOS Storefront Engine is an ultra-fast, edge-rendered system designed to serve dynamic content in under 50ms globally.

The Theme Engine Flow

When a user visits a WebbiOS storefront, the following sequence occurs at the Cloudflare Edge:

1. Request Interception: The Cloudflare Worker intercepts the request and extracts the domain.
2. KV Cache Lookup: The system uses the domain to query Cloudflare KV for the theme.json configuration (e.g., cache:theme:config:webbios.dev). This lookup takes single-digit milliseconds.
3. Fallback Mechanism: If the KV cache misses (e.g., a newly linked domain or a temporary failure), the system falls back to a hardcoded theme.json bundled with the Worker to ensure the site never goes down.
4. Routing: Based on the requested path, the engine extracts the specific page configuration from the theme.json.
5. Edge Rendering: WebbiOS uses React’s renderToReadableStream to statically render the content at the edge. A <SectionRenderer> iterates over the page’s sections and maps them to @webbios/storefront-ui components.
6. Edge Caching: The resulting HTML is streamed to the browser with a Cache-Control header (e.g., 5 minutes), instructing the CDN to serve subsequent requests directly from the edge cache without hitting the Worker.

The theme.json Architecture

WebbiOS uses a Headless Architecture for themes. The entire visual structure of a site is defined in a single theme.json file.

{
  "themeName": "Corporate 01",
  "version": "1.0.0",
  "pages": {
    "/": {
      "title": "Home",
      "description": "SEO description for home",
      "sections": [
        {
          "id": "hero-1",
          "type": "hero",
          "props": {
            "headline": "Welcome to WebbiOS",
            "primaryCtaText": "Shop Now"
          }
        }
      ]
    }
  }
}

Sections and Components

Each item in the sections array represents a UI block. The type (e.g., hero) tells the <SectionRenderer> which React component to instantiate, and the props provide the data for that component.

This JSON-driven approach allows for future Theme Builders where merchants can drag-and-drop UI components, and the system simply updates the theme.json in KV without needing to rebuild or redeploy any code.