Qaxal sGTM Platform

Appearance

Qaxal sGTM Platform — Canonical Business Logic ​

1. System Purpose ​

The Qaxal sGTM Platform exists to improve the quality, reliability, and compliance of client-side data tracking by enforcing controlled execution, consent-aware state handling, and server-side mediation at the edge.

Specifically, the platform addresses three critical business problems:

  1. Tracking Prevention Recovery: Modern browsers (Safari ITP, Firefox ETP) and ad blockers actively break first-party tracking. This system intercepts and recovers tracking requests that would otherwise be lost, ensuring accurate analytics and attribution.
  2. First-Party Cookie Lifecycle Extension: Browser privacy features limit cookie lifetimes to 7 days (ITP) or less. The platform extends first-party cookie TTLs server-side, maintaining user identity continuity across visits without relying on third-party cookies.
  3. Server-Side Google Tag Manager (sGTM) Hosting: Rather than requiring clients to manage their own sGTM infrastructure, the platform provisions, operates, and scales server-side GTM containers as a managed service with per-container billing and usage enforcement.

The architecture separates the Control Plane (Supabase: configuration, billing, user management) from the Data Plane (Cloudflare Workers: real-time request processing, edge routing, analytics collection).

2. Core Concepts & Terminology ​

2.1 Container ​

A Container is the primary unit of service delivery. It represents a provisioned server-side GTM instance with its own:

  • Billing subscription (plan limits, usage tracking).
  • Configuration (GTM container config, modules, custom domains).
  • Identity (loader_token for request authentication, edge_hostname for routing).

A Container belongs to exactly one Client.

2.2 Client ​

A Client is a billing and organizational entity. Clients:

  • Own one or more Containers.
  • Have team members with role-based access.

2.3 Site ​

A Site represents a tracked website within a Container. Sites have:

  • Primary Host: The canonical hostname (e.g., example.com).
  • Tracked Domains: Additional hostnames routed to the same Container.
  • Cookie Domain: The domain scope for first-party cookies.
  • Container Token: Site-specific authentication for the Loader.

A Container may have multiple Sites (Multi-Domain), enabling cross-domain tracking strategies.

2.4 Loader Token ​

A unique identifier issued per Container. The Loader Token:

  • Appears in the tracking snippet URL (/l/{loader_token}.js).
  • Authenticates requests to the edge infrastructure.
  • Maps to Container configuration in the LOADER_TOKEN_MAP KV namespace.

2.5 Edge Hostname ​

The Cloudflare-proxied hostname (e.g., abc123.trqaxal.com) that receives all tracking requests for a Container. All requests to this hostname are touted via the ROUTING_MAP KV to the correct sGTM origin.

2.6 Custom Domain ​

A client-owned hostname (e.g., data.example.com) pointed via DNS to the platform. Custom Domains:

  • Require DNS verification before activation.
  • Are synced to ROUTING_MAP (for routing) and SITE_REGISTRY (for config lookup).

2.7 Modules ​

Optional features enabled per Container, gated by plan entitlements and runtime config:

Module KeyPurpose
adblock_itp_detectionDetect and report tracking prevention signals.
cookie_keeperExtend first-party cookie TTLs server-side.
custom_domainSupport for vanity domains.
gtm_recoveryRecover GTM requests blocked by client-side blockers.
sgtm_proxyProxy requests to the sGTM origin.

2.8 Config Version ​

A monotonically increasing integer tracking configuration changes.

  1. Supabase increments config_version.
  2. sync-edge-config writes the new config to Cloudflare KV.
  3. Edge Workers detect the version change and refresh their internal cache (TTL ~60s).

3. High-Level Execution Flow ​

Request Path Summary ​

  1. Entry: Browser loads tracking snippet or sends a tracking request.
  2. Token/Host Resolution:
    • Loader: Resolves loader_token via LOADER_TOKEN_MAP.
    • Router: Resolves Host header via ROUTING_MAP.
  3. Config Lookup: Fetches runtime config from EDGE_CONFIG KV (with Supabase container-config as fallback).
  4. Module Execution: Active modules (Cookie Keeper, Recovery) modify the request/response.
  5. Origin Proxy: The request is proxied to the sGTM container (Docker container on edge server).
  6. Response: The response is returned to the browser, often with Set-Cookie headers for persistence.

4. Active Logical Components ​

4.1 Cloudflare Router Worker (sgtm-router) ​

  • Responsibility: Primary request handler. Proxies traffic, enforces routing, handles CORS, and logs analytics.
  • Inputs: HTTP requests (Host, Cookies, Query Params).
  • Outputs: Proxied responses, AE/R2 Access Logs.
  • Dependencies: ROUTING_MAP, EDGE_CONFIG, SITE_REGISTRY.

4.2 Cloudflare Loader Worker (sst-loader) ​

  • Responsibility: Serves the dynamic JavaScript loader and handles boot/session logic.
  • Inputs: /l/{token}.js, /boot payload.
  • Outputs: Dynamic JS, JSON boot config.
  • Dependencies: LOADER_TOKEN_MAP, EDGE_CONFIG.

4.3 sync-edge-config (Edge Function) ​

  • Responsibility: The authoritative writer to Cloudflare KV. Syncs Supabase state to the Edge.
  • Trigger: Config changes, domain verification, nightly drift checks.
  • Writes To: EDGE_CONFIG, LOADER_TOKEN_MAP, SITE_REGISTRY.

4.4 container-config (Edge Function) ​

  • Responsibility: Fallback origin for Workers when KV is empty or stale.
  • Security: Protected by X-Edge-Auth shared secret.
  • Trigger: Router Worker cache miss.

4.5 Billing & Usage (Cron) ​

  • Responsibility: Enforces plan limits.
  • Action: Pauses containers or triggers upgrades based on daily usage (from sgtm_usage_daily_cf).

4.6 Nightly KV Drift Check (Cron) ​

  • Responsibility: Ensures Supabase and KV match.
  • Action: Re-runs sync-edge-config if versions mismatch.

5. Consent & State Model ​

The platform is consent-aware but consent-agnostic. It does not collect consent itself; it enforces the client's consent state.

5.1 State Storage ​

  • First-Party Cookies: Session identity and tracking IDs (FPID, _ga). Extended by cookie_keeper module.
  • Loader Session: Short-lived, session-scoped state (fingerprint, detection results) stored in Supabase (loader_sessions) via /mark-session-detection.
  • Runtime Config: Cached at the edge (KV) for performance.

5.2 Cookie Lifecycle ​

The Cookie Keeper module:

  1. Reads incoming cookies (FPID, _ga, etc.).
  2. Checks cookie_restoration entitlement.
  3. Refreshes the Set-Cookie header on the response to extend TTL (up to 395 days), combating ITP 7-day limits.

6. Tracking Prevention Recovery (gtm_recovery) ​

The Tracking Prevention Recovery module ensures data completeness by intercepting requests blocked by client-side privacy tools (e.g., ad blockers, ITP).

6.1 Recovery Mechanism ​

  1. Interception: The Loader installs XMLHttpRequest and fetch interceptors.
  2. Detection: It identifies tracking endpoints that are commonly blocked.
  3. Encapsulation: The request path and query parameters are base64-encoded.
  4. Routing: The request is rewritten to the Proxy Path (/k/{token}) and sent to the detailed edge router (sgtm-router).
  5. Reconstruction: The Router decodes the payload, validates the upstream destination (security), and proxies the request to the sGTM origin.

6.2 Recovered Endpoints ​

The following endpoints are automatically detected and recovered:

  • Google Analytics 4: /g/collect, /collect
  • Universal Analytics: /collect
  • DoubleClick: /r/collect
  • Google Consent Mode: /ccm/collect

6.3 Security ​

  • Open Proxy Prevention: The /k/ endpoint strictly prohibits absolute URLs in the payload. It only proxies to the configured sGTM origin.
  • Signature: Requests are authenticated via the container_token in the path.

6. Single-Domain vs Multi-Domain Behavior ​

6.1 Single-Domain ​

  • Setup: One Site, One Container.
  • Routing: All traffic uses the Site's primary host (or Edge Hostname).
  • Cookies: Scoped to the single domain.

6.2 Multi-Domain ​

  • Setup: Multiple Sites pointing to One Container.
  • Routing: SITE_REGISTRY KV distinguishes config (GTM ID, Token) based on X-Public-Host.
  • Isolation:
    • Shared: Container Billing, Usage, Runtime Config.
    • Isolated: Cookies (scoped per domain), Web GTM ID (can differ per Site).

7. Failure Modes & Guardrails ​

7.1 Fail-Closed Behaviors ​

  • Invalid Token: Requests to /l/{invalid}.js return 404.
  • Missing Config: If KV is missing AND fallback fails, Router returns 500 (does not proxy blindly).
  • Plan Limits: If a subscription is paused, the Router returns 402 Payment Required (JSON) to stop accumulating costs.

7.2 Fail-Open Behaviors ​

  • Config Cache: Workers use stale cache if KV/Supabase is unreachable (within TTL limits).
  • Logging: Analytics Engine/R2 logging failures are caught and logged to console; they never block the main request flow.

7.3 Usage Enforcement ​

  • Hard Limit: Containers exceeding their plan limits (without auto-upgrade) are paused.
  • Recovery: Upgrading the plan or paying the invoice immediately resumes service/unpauses the container.

8. Explicitly Out of Scope ​

  • Infrastructure Provisioner: The separate service that updates ROUTING_MAP when containers are created/deleted.
  • GTM Container Internals: The platform treats the GTM container's base64 config as opaque data.
  • Client-Side Consent UI: The platform does not render cookie banners.
  • Stripe Webhooks: Payment processing detail (handled by stripe-webhook function) is implementation detail, not core tracking logic.

Documentation Index ​

Released under proprietary license.

Copyright © 2024 Qaxal