#Radar Web Analytics & Edge Interception (@xtnd/vantage-radar)

Package: @xtnd/vantage-radar
Source Directory: xtnd-vantage/packages/radar/

#1. Overview

@xtnd/vantage-radar provides dual-layer observability for web applications:

1. Client-Side UX Lifecycle Dispatcher: Non-blocking page arrival orchestration and interaction telemetry.
2. Cloudflare Edge Interceptor: Zero-modification request wrapping that monitors origin websites (such as LaoGPT.com and EvergreenAI.la) directly at Cloudflare's edge DNS layer.

#2. Browser UX Dispatcher (VantageBrowserDispatcher)

#2.1 Coordinated Page Initialization (initPage)

When a user navigates to a Vantage-enabled application:

1. Dispatches Native DOM Event: Fires a CustomEvent('vantage:page:init') on window. Application UI components listen to this event to trigger hero entry animations, typeface swaps, and asset preloads.
2. Writes Non-Blocking Telemetry: Asynchronously logs page:init with route, viewport, referrer, and hostname directly to the local storage adapter as a P2_NORMAL event. The main UI thread experiences zero delay.

import { VantageBrowserDispatcher } from '@xtnd/vantage-radar';

const radar = new VantageBrowserDispatcher(storageManager);

// Called at the top of the application bundle:
radar.initPage({ appName: 'LaoGPT Web', route: '/chat' });

// UI components listen to the DOM event:
window.addEventListener('vantage:page:init', (e) => {
  startHeroAnimations();
});

#2.2 Core Web Vitals & Custom Interactions

• trackInteraction(eventName, data): Emits user:${eventName} (e.g. user:prompt_submit, user:model_toggle).
• recordWebVital(metric): Ingests Google Core Web Vitals metrics (LCP, INP, CLS) with rating badges (good, needs-improvement, poor).

#3. Cloudflare Edge Interceptor (VantageEdgeInterceptor)

The Edge Interceptor enables comprehensive observability of web applications without changing a single line of origin application code.

flowchart LR
    Client["Browser / Visitor"] --> Worker["Cloudflare Edge Worker\n(VantageEdgeInterceptor)"]
    Worker -- "originFetch()" --> Origin["Origin Server\n(e.g. LaoGPT / EvergreenAI)"]
    Origin -- "HTTP 200 / Response" --> Worker
    Worker -- "Return Response (0ms delay)" --> Client
    Worker -- "ctx.waitUntil(recordAsync)" --> Vantage["Central Vantage Ingestion"]

#3.1 Interception Mechanics (handleRequest)

1. High-precision timing begins via performance.now().
2. The original request is forwarded to the origin server using originFetch(request).
3. If the origin server throws an exception or network error:
   • Status is marked 502 Bad Gateway.
   • Priority is escalated to P0_CRITICAL.
   • The error is logged and rethrown.
4. If the origin server responds:
   • High-precision duration (durationMs) is calculated.
   • Metadata is extracted from Cloudflare headers: cf.country, cf.city, cf.colo, user-agent, content-length.
   • Responses with HTTP status >= 500 escalate to P0_CRITICAL; successful responses log as P2_NORMAL.
   • Asynchronous telemetry logging is scheduled via ctx.waitUntil().
   • The untouched origin response is streamed back to the client immediately.

#3.2 Metrics Captured

export interface EdgeRequestMetrics {
  hostname: string;       // e.g. "laogpt.com"
  pathname: string;       // e.g. "/api/v1/chat"
  method: string;         // e.g. "POST"
  status: number;         // e.g. 200, 500, 502
  durationMs: number;     // e.g. 42.6ms
  country: string;        // e.g. "LA" (Laos), "TH" (Thailand)
  city: string;           // e.g. "Vientiane", "Bangkok"
  userAgent?: string;     // Client browser/device
  referrer?: string;      // Traffic source
  contentLength?: number; // Byte volume
}