Aegis Router User Guide

1. Executive Summary

The Aegis Router is the beating heart of the platform. It is a highly optimized Cloudflare Worker that operates at the edge, acting as a reverse proxy. Its primary job is to intercept incoming web requests, determine the appropriate backend destination, patch the HTML in real-time, and serve the content to the user with minimal latency.

2. Dynamic HTML Injection

When routing traffic to Single Page Applications (SPAs) like those built on Lovable.app, the Router performs crucial on-the-fly modifications:

  • Base Href & Basename: It automatically injects React Router variables (like window.__BASENAME__ and <base href="...">) into the HTML so the frontend routing works flawlessly on custom subpaths.
  • Tracking Pixels: It seamlessly injects globally required tracking scripts (like Meta Pixels or Google Analytics) directly into the <head> of the page before the browser even parses it.

3. Server-Side Ad Tracking

The Router is heavily optimized for performance marketing:

  • Ad Subdomain Interception: It securely intercepts traffic sent to specific ad subdomains (e.g., meta.purdyandfigg.com or youtube.purdyandfigg.com).
  • UTM Construction: It intelligently constructs UTM redirect URLs to pass attribution cleanly down the funnel to Shopify.
  • Seamless API Events: It intercepts data-layer clicks and fires seamless, server-side GA4 events via the Measurement Protocol to ensure ad platforms receive accurate, ad-blocker-resistant conversion signals.

4. High-Velocity Telemetry

To ensure proxy speeds are never bottlenecked by database writes:

  • The Router captures raw data-layer proxy clicks and offloads them to an infinitely scalable Cloudflare Queue engine.
  • This allows the Router to return the HTML to the user instantly while the heavy lifting of logging and analytics aggregation happens asynchronously behind the scenes.

5. Hetzner JSON Fallback Mode (No Vendor Lock-in)

Reliability is paramount, and ensuring customers can always access active ad campaigns is the highest priority. If Cloudflare or the underlying D1 database experiences a catastrophic outage:

  • True Redundancy: The Router can safely disconnect from D1 and run purely off local memory using a synced fallbackConfig.json file.
  • Hetzner Failover: Because of this architecture, the Router (alongside the Admin dashboard) can be seamlessly migrated and hosted on external infrastructure like Hetzner at a moment's notice. This prevents vendor lock-in to Cloudflare.
  • Core-Facing Focus: While background modules like Analytics or Nudger are not mirrored to the Hetzner failover to save resources, the Router is prioritized because it is the core customer-facing layer. This guarantees we can still serve pages and protect live media budgets even if secondary internal services temporarily go dark.