📝 Add docstrings to codex/implement-web-vitals-tracking-and-api-jt9zi9

Docstrings generation was requested by @shayancoin.

* #125 (comment)

The following files were modified:

* `frontend/src/app/api/otel/webvital/route.ts`
* `frontend/src/app/providers.tsx`
* `frontend/src/app/web-vitals.ts`

Author: coderabbitai[bot]

frontend/src/app/api/otel/webvital/route.ts

@@ -27,15 +27,34 @@ const DEFAULT_SCOPE = {
   version: '1.0.0',
 };
 
+/**
+ * Converts a millisecond timestamp to a string representing nanoseconds since the Unix epoch.
+ *
+ * @param ms - Milliseconds since Unix epoch; negative values are treated as zero and fractional milliseconds are floored.
+ * @returns The timestamp in nanoseconds as a decimal string.
+ */
 function toUnixNano(ms: number) {
   const time = BigInt(Math.max(0, Math.floor(ms))) * NANOSECONDS_IN_MILLISECOND;
   return time.toString();
 }
 
+/**
+ * Generate a base64-encoded cryptographic random identifier.
+ *
+ * @param bytes - Number of random bytes to generate
+ * @returns A base64-encoded string containing `bytes` cryptographically secure random bytes
+ */
 function randomId(bytes: number) {
   return randomBytes(bytes).toString('base64');
 }
 
+/**
+ * Determines the OTLP collector endpoint URL from environment variables.
+ *
+ * Prefers `OTEL_EXPORTER_OTLP_ENDPOINT` or `OTEL_COLLECTOR_URL` when present. If those are not set, builds a URL from `OTEL_COLLECTOR_HOST` with optional `OTEL_COLLECTOR_PROTOCOL` (default `http`), `OTEL_COLLECTOR_PORT`, and `OTEL_COLLECTOR_PATH` (default `/v1/traces`).
+ *
+ * @returns The collector endpoint URL as a string, or `undefined` if no configuration is available.
+ */
 function resolveCollectorEndpoint() {
   const explicit =
     process.env.OTEL_EXPORTER_OTLP_ENDPOINT || process.env.OTEL_COLLECTOR_URL;
@@ -56,6 +75,13 @@ function resolveCollectorEndpoint() {
   return `${protocol}://${host}${portSegment}${path}`;
 }
 
+/**
+ * Create an OTLP span object representing a single web-vital event.
+ *
+ * @param event - Web-vital event data whose fields are mapped to span attributes (e.g., `webvital.value`, `webvital.delta`, `webvital.rating`, `webvital.id`, `webvital.type`, `webvital.navigation_type`, `navigation.*`, and truncated `webvital.attribution`)
+ * @param fallbackTime - Fallback timestamp in milliseconds since epoch used to compute the span's start and end times when precise timing is not provided by the event
+ * @returns An OTLP-compatible span object containing `traceId`, `spanId`, `name`, `kind`, `startTimeUnixNano`, `endTimeUnixNano`, `traceState`, `flags`, and an `attributes` array describing the web-vital and navigation details
+ */
 function createSpan(event: IncomingEvent, fallbackTime: number) {
   const duration =
     typeof event.detail?.duration === 'number' && event.detail.duration > 0
@@ -150,6 +176,17 @@ function createSpan(event: IncomingEvent, fallbackTime: number) {
   };
 }
 
+/**
+ * HTTP POST handler that ingests a JSON payload of web-vital events and exports them as OTLP spans to a configured collector.
+ *
+ * Processes an incoming payload of events, transforms each event into an OTLP span, sends the batch to the resolved collector endpoint, and returns a JSON response describing the result.
+ *
+ * @returns A JSON response:
+ * - `{ accepted: number }` when spans were successfully exported (number is the count of accepted spans).
+ * - `{ error: 'Invalid JSON payload', details: string }` with HTTP status 400 if the request body is invalid JSON.
+ * - `{ error: 'Collector endpoint is not configured' }` with HTTP status 500 if no collector endpoint is available.
+ * - `{ error: 'Failed to export web vitals', status: number, body: string }` with HTTP status 502 if the collector responds with a non-OK status.
+ */
 export async function POST(request: Request) {
   let payload: IncomingPayload;
   try {
@@ -227,4 +264,3 @@ export async function POST(request: Request) {
 
   return NextResponse.json({ accepted: spans.length });
 }
-

frontend/src/app/providers.tsx

@@ -21,10 +21,18 @@ const theme = extendTheme({
   },
 });
 
+/**
+ * Wraps the application UI with a ChakraProvider using the project theme and initializes web vitals on mount.
+ *
+ * Calls `initWebVitals` once when mounted to start web vitals collection.
+ *
+ * @param children - The React node(s) to render within the themed provider
+ * @returns The React element tree where `children` are wrapped by a `ChakraProvider` configured with the module theme
+ */
 export function Providers({ children }: { children: React.ReactNode }) {
   useEffect(() => {
     initWebVitals();
   }, []);
 
   return <ChakraProvider theme={theme}>{children}</ChakraProvider>;
-}
+}

frontend/src/app/web-vitals.ts

@@ -37,6 +37,11 @@ const queue: WebVitalPayload[] = [];
 let flushTimeout: number | undefined;
 let initialized = false;
 
+/**
+ * Schedules a batch flush of queued web-vital events to occur after the configured interval if none is already scheduled.
+ *
+ * When the timer fires, the queued events are flushed and the scheduled handle is cleared.
+ */
 function scheduleFlush() {
   if (flushTimeout) {
     return;
@@ -48,6 +53,13 @@ function scheduleFlush() {
   }, BATCH_INTERVAL_MS);
 }
 
+/**
+ * Adds a web vital or navigation timing payload to the in-memory queue and triggers batching behavior.
+ *
+ * If the queue reaches the configured maximum batch size, a flush is initiated immediately; otherwise a flush is scheduled.
+ *
+ * @param payload - The WebVitalEvent or NavigationTimingEvent to enqueue for later delivery
+ */
 function enqueue(payload: WebVitalPayload) {
   queue.push(payload);
 
@@ -59,6 +71,13 @@ function enqueue(payload: WebVitalPayload) {
   scheduleFlush();
 }
 
+/**
+ * Sends all queued web-vital and navigation-timing events to the server and clears the in-memory queue.
+ *
+ * If the queue is empty this is a no-op. Attempts to deliver using `navigator.sendBeacon` when available;
+ * otherwise falls back to a POST request with `keepalive`. On network failure, logs a warning in non-production
+ * environments and restores the events to the front of the queue so they are not lost.
+ */
 async function flushQueue() {
   if (!queue.length) {
     return;
@@ -98,6 +117,14 @@ async function flushQueue() {
   }
 }
 
+/**
+ * Collects navigation timing metrics from the Performance API and enqueues a navigation-timing payload.
+ *
+ * If the Performance API is not available or no navigation entry exists, this function is a no-op.
+ *
+ * The enqueued payload contains the navigation `duration`, `navigationType`, and a `detail` object with
+ * `domContentLoaded`, `firstByte`, `responseTime`, `loadEvent`, and `duration` deltas.
+ */
 function collectNavigationTimings() {
   if (typeof performance === 'undefined' || !performance.getEntriesByType) {
     return;
@@ -129,6 +156,12 @@ function collectNavigationTimings() {
   });
 }
 
+/**
+ * Convert a web-vitals Metric into a WebVitalEvent payload suitable for batching and transmission.
+ *
+ * @param metric - Metric object from the web-vitals library to convert
+ * @returns A WebVitalEvent containing the metric's name, value, identifiers, rating, and optional `navigationType` and `attribution` when present
+ */
 function metricToPayload(metric: Metric): WebVitalEvent {
   const payload: WebVitalEvent = {
     type: 'web-vital',
@@ -152,6 +185,11 @@ function metricToPayload(metric: Metric): WebVitalEvent {
   return payload;
 }
 
+/**
+ * Starts observing core web-vital metrics and enqueues each metric as a telemetry payload.
+ *
+ * Registers observers for CLS, LCP, INP, FCP, and TTFB; each observed metric is converted to a payload and added to the batching queue for delivery.
+ */
 function registerWebVitalObservers() {
   const handleMetric = (metric: Metric) => {
     enqueue(metricToPayload(metric));
@@ -164,6 +202,11 @@ function registerWebVitalObservers() {
   onTTFB(handleMetric);
 }
 
+/**
+ * Register page lifecycle listeners that trigger an immediate flush of the web-vitals queue.
+ *
+ * Adds handlers for `beforeunload` and `pagehide`, and for `visibilitychange` when the document becomes `hidden`, causing the queued events to be sent before the page is unloaded or hidden.
+ */
 function setupLifecycleFlushes() {
   const immediateFlush = () => {
     void flushQueue();
@@ -178,6 +221,12 @@ function setupLifecycleFlushes() {
   });
 }
 
+/**
+ * Initializes collection and reporting of web-vitals and navigation timing data.
+ *
+ * This function is idempotent: calling it multiple times has no additional effect.
+ * It is a no-op outside of a browser environment.
+ */
 export function initWebVitals() {
   if (initialized || typeof window === 'undefined') {
     return;
@@ -189,4 +238,3 @@ export function initWebVitals() {
   registerWebVitalObservers();
   setupLifecycleFlushes();
 }
-