The Origin Story

Wranglr started as an edge hosting platform. The original idea was simple: let anyone deploy a static website to Cloudflare R2 and have it served instantly from 300+ global locations. No server, no SSH, no complicated configs — just upload and your site is live worldwide.

The platform evolved from there. Static hosting led to a Dispatcher Worker that routes traffic based on custom domains. The Dispatcher led to A/B testing and dynamic theming at the edge. And the theming engine made it possible to build multi-tenant e-commerce — one shared storefront that looks different for every merchant.

Today, Wranglr handles two types of sites: static sites (HTML/CSS/JS deployed via CLI to R2) and e-commerce stores (a shared React SPA with products, checkout, and order management). Both run on the same edge infrastructure.

Two Site Types, One Platform

Understanding this distinction is critical — the Dispatcher handles both types differently:

// User deploys via CLI or dashboard
// Files uploaded to R2 bucket:
BUCKET/{userId}/{siteId}/index.html
BUCKET/{userId}/{siteId}/style.css
BUCKET/{userId}/{siteId}/app.js

// Dispatcher serves directly from R2
// with SPA fallback + custom 404
// + A/B variant path prefix
// + visual builder injection

Wranglr vs The Competition

Wranglr competes differently depending on the use case — as an edge hosting platform and as an e-commerce platform:

The Key Architectural Insight

Check Your Understanding

The Five Actors

The Project Structure

How They Talk: A Group Chat

Check Your Understanding

Traditional Architecture: The Old Way

In a traditional web app, you rent a server — usually a virtual machine in a data center in the US or EU. Let's say you pick AWS us-east-1 (Virginia, USA). Here's what happens when a customer in Johannesburg visits your store:

Edge Architecture: The Wranglr Way

Now here's what happens on Wranglr when that same Johannesburg customer visits the same store:

The Latency Math: SA Perspective

Speed of light through fiber optic cable is ~200,000 km/s. These are the physical distances and round-trip times for a South African customer:

Cold Starts: The Silent Killer

A cold start is when a serverless function hasn't been called recently, so the cloud provider needs to boot it up. Here's how different platforms compare:

Why are Cloudflare Workers cold-start-free? Because they use V8 Isolates — tiny, sandboxed environments that spin up in under 1 millisecond. Compare this to Lambda, which boots an entire Node.js runtime in a container. It's like the difference between opening a new browser tab (instant) versus booting a new computer (slow).

The Dispatcher: Master of the Edge

The Dispatcher is the single most important piece of Wranglr. It runs on every one of Cloudflare's 300+ edge locations and handles every single request to any Wranglr-hosted domain. Here's what it does, step by step:

// 1. Read the incoming hostname
let hostname = request.headers
  .get('host').toLowerCase();

// 2. Bypass for admin portal
if (hostname === 'admin.wranglr.co.za')
  return fetch(request);

// 3. Query D1 for the site record
let site = await env.DB.prepare(`
  SELECT s.id, s.blueprint_id,
    u.subscription_expiry,
    ss.theme_colors, ss.font_family
  FROM sites s JOIN users u
  LEFT JOIN site_settings ss
  WHERE s.domain_name = ?`
).bind(hostname).first();

// 4. Check subscription
if (new Date(site.subscription_expiry)
    < new Date())
  return expiredPage;

// 5. Route based on blueprint
if (site.blueprint_id ===
    'ecommerce-store') {
  // Proxy to shared storefront
  targetUrl.hostname =
    'wranglr-stores.pages.dev';
  return applyAesthetics(
    await fetch(proxyReq), site
  );
} else {
  // Serve static from R2
  const obj = await env.BUCKET
    .get(`${site.user_id}/${site.id}/..`);
  return serveObject(obj, site);
}

HTMLRewriter: Painting Brands at the Speed of Light

This is the most clever part of Wranglr's edge architecture. Every store on Wranglr shares the exact same React application. But each store looks completely different — different colors, fonts, logos, and layouts. How?

The answer is HTMLRewriter — a streaming HTML transformer that runs at the edge. Think of it like a painter standing between the factory and the delivery truck, painting each product a different color as it comes off the assembly line.

function applyAesthetics(response, site) {
  let cssVars = ':root {\n';
  cssVars += `  --primary: ${site.primary};\n`;
  cssVars += `  --bg: ${site.background};\n`;
  cssVars += `  --surface: ${site.surface};\n`;
  cssVars += '}\n';

  return new HTMLRewriter()
    .on('head', {
      element(el) {
        el.append(
          `<style>${cssVars}</style>`,
          { html: true }
        );
      }
    })
    .on('title', {
      element(el) {
        el.setInnerContent(
          site.store_name
        );
      }
    })
    .transform(response);
}

Why Edge is Fundamentally Better

The edge isn't just faster — it changes the economics and reliability of running a platform:

The Trade-offs (Nothing Is Free)

Edge computing isn't magic. There are real constraints that shaped Wranglr's architecture:

Check Your Understanding

The Checkout Journey

Imagine a customer on a Wranglr store adds a T-shirt to their cart and clicks checkout. The data travels through multiple actors — let's trace it.

Multi-Tenant API Routing

Every storefront API call includes a siteId — the unique identifier for that merchant's store. This is how one API serves thousands of stores without mixing up data. Think of it like a hotel concierge who asks for your room number before doing anything.

const segments = path.split('/');
const siteId = segments[0];
const resource = segments[1];

// Verify site exists
const site = await env.DB.prepare(`
  SELECT s.id FROM sites s
  WHERE s.id = ? AND s.status != 'deleted'
`).bind(siteId).first();

Cloudflare D1 + R2: The Storage Duo

Wranglr uses two types of storage — each optimized for a different job:

Check Your Understanding

The Yoco Integration

Here's the clever part: Wranglr doesn't process payments. Each merchant has their own Yoco account with their own API keys. When a customer pays, the money goes directly from customer → Yoco → merchant's bank. Wranglr is just the plumbing that connects them.

Think of it like a shopping mall: the mall provides the building and foot traffic, but each shop has its own cash register. Wranglr provides the storefront and checkout UI, but each merchant's own Yoco handles the money.

Webhook Signature Verification

When Yoco says "payment succeeded," how does Wranglr know it's really Yoco and not someone faking the request? Through HMAC signature verification — like a secret handshake.

const signature = request.headers
  .get('X-Yoco-Signature');

if (!await verifyYocoSignature(
    body, signature, env.YOCO_WEBHOOK_SECRET
)) {
  return new Response(
    'Invalid signature', { status: 401 }
  );
}

Password Security

Wranglr uses PBKDF2 with 100,000 iterations for password hashing — plus constant-time comparison to prevent timing attacks.

Check Your Understanding

The Strengths

The Weaknesses

Wranglr vs The Competition

Check Your Understanding

14 Route Files, One Worker

The API Worker (apps/workers/api) is one Cloudflare Worker with 14 route modules. Every request lands in index.ts, which reads the URL path and delegates to the right handler. Think of it like a switchboard operator — one phone line, 14 departments.

The Router Pattern

Here's how the main index.ts routes requests — it's a simple if/else chain that strips the prefix and passes the remaining path to each handler:

const path = url.pathname;

if (path.startsWith('/api/auth'))
  response = await authRoutes(
    request, env,
    path.replace('/api/auth', '')
  );
else if (path.startsWith('/api/sites'))
  response = await sitesRoutes(...);
else if (path.startsWith('/api/payments'))
  response = await paymentsRoutes(...);
// ... 11 more route handlers
else if (path === '/api/store-lookup')
  // PUBLIC endpoint — no auth
  // Resolves hostname → site_id
  // Used by the storefront React app

Environment Bindings

The API Worker has access to 12 environment bindings — secrets and services injected by Cloudflare:

Check Your Understanding

Step 1: Registration

When a merchant signs up at dashboard.wranglr.co.za/register, the following chain of events begins:

// POST /api/auth/register
const { email, password, name } = body;

// Generate salt + hash password
const salt = crypto.getRandomValues(
  new Uint8Array(16)
);
const hash = await crypto.subtle
  .deriveBits(
    { name: 'PBKDF2',
      salt, iterations: 100000,
      hash: 'SHA-256' },
    key, 256
  );

// Set 14-day free trial
const trialEnd = new Date();
trialEnd.setDate(
  trialEnd.getDate() + 14
);

// Insert user into D1
await env.DB.prepare(`
  INSERT INTO users
  (id, email, password_hash,
   salt, name, plan_tier,
   subscription_expiry)
  VALUES (?,?,?,?,?,?,?)`
).bind(id, email, hashHex,
  saltHex, name, 'trial',
  trialEnd.toISOString()
).run();

Step 2: Create a Site

After login, the merchant creates a "site" — the container for their store, domain, and settings:

Step 3: Custom Domain Setup

When a merchant brings their own domain (e.g., "ronins-gear.co.za"), Wranglr automates the DNS setup:

Check Your Understanding

One App, Infinite Stores

The storefront (templates/ecommerce-store) is a single React SPA deployed once to Cloudflare Pages at wranglr-stores.pages.dev. When a customer visits ANY Wranglr store, they're loading the same React app. Here's how it knows which store to render:

The Page Builder Rendering

Merchants can customize their storefront using a drag-and-drop page builder in the dashboard. The builder produces a JSON array of "sections" stored in D1. The storefront's BuilderSections.tsx reads this JSON and renders matching React components:

[
  {
    "type": "hero",
    "title": "Welcome to Ronin's",
    "subtitle": "Premium Gear",
    "bg_image": "https://..."
  },
  {
    "type": "product-grid",
    "columns": 3,
    "limit": 6
  },
  {
    "type": "trust-badges",
    "badges": [
      { "icon": "truck",
        "text": "Free Shipping" },
      { "icon": "shield",
        "text": "Secure Checkout" }
    ]
  }
]

Check Your Understanding

The Login Flow

When a merchant logs in, here's the complete chain — from typing their password to receiving a JWT that authenticates every subsequent request:

JWT Middleware — The Bouncer

The auth middleware (middleware/auth.ts) sits between the request and every protected route. It verifies the JWT token before the route handler ever sees the request:

export async function
verifyAuth(request, env) {
  const authHeader =
    request.headers.get(
      'Authorization'
    );
  if (!authHeader?.
      startsWith('Bearer '))
    return null;

  const token =
    authHeader.slice(7);
  const key = await
    crypto.subtle.importKey(
      'raw',
      encode(env.JWT_SECRET),
      { name: 'HMAC',
        hash: 'SHA-256' },
      false, ['verify']
    );

  const valid = await
    crypto.subtle.verify(
      'HMAC', key,
      signature, payload
    );

  return valid ? user : null;
}

Security Layers

Check Your Understanding

A/B Testing at the Edge

Wranglr's A/B testing runs in the Dispatcher — not in JavaScript, not in a third-party tool. The Dispatcher splits traffic before the page loads. Here's exactly how:

// Check for active A/B test
const abTest = await env.DB
  .prepare(`SELECT * FROM ab_tests
    WHERE site_id = ?
    AND status = 'running'
    LIMIT 1`)
  .bind(site.id).first();

// Check existing cookie
const existing =
  cookies[`wranglr_ab_${abTest.id}`];

if (existing === 'A' || existing === 'B')
  variant = existing;
else
  variant = Math.random() * 100
    < abTest.split_ratio
      ? 'B' : 'A';

// Prepend variant path
filePath =
  `${variantPath}${filePath}`;

// Track view (fire-and-forget)
ctx.waitUntil(
  trackABView(
    env.DB, abTest.id,
    variant, today
  )
);

Preview Subdomains

Before configuring a custom domain, merchants can preview their site at {siteId}-preview.wranglr.co.za. The Dispatcher handles these automatically:

const previewMatch =
  hostname.match(
    /^([a-f0-9-]+)-preview
     \.wranglr\.co\.za$/
  );

if (previewMatch) {
  const siteId =
    previewMatch[1];
  return handlePreviewRequest(
    request, env, siteId, url
  );
}

The Visual Builder

For static sites, the Dispatcher injects an entire visual editor into the page when viewed inside the dashboard's iframe. This 200-line JavaScript toolkit enables click-to-select, drag-to-reorder, and inline editing — all without any browser extension.

Check Your Understanding

The Complete Architecture

Here's every actor, every connection, every data flow in one mental model:

Why This Knowledge Matters for AI

When you ask an AI assistant (like me!) to modify Wranglr, knowing these actors and flows is the difference between a 5-minute fix and an hour of debugging.

🎉 Course Complete!

You now understand how Wranglr works — from the edge network to payment webhooks. You can confidently direct AI assistants when building features for the platform.