@valentia-ai-skills/framework 2.0.6 → 2.0.8

package/skills/global/observability-integrations/SKILL.md

@@ -0,0 +1,835 @@
+---
+name: observability-integrations
+description: Integrates observability, analytics, and monitoring services into React applications — Sentry
+  (error tracking + performance), Microsoft Clarity (heatmaps + session recording), Datadog
+  (RUM + logs + APM), Google Analytics/Pixels (GA4 + GTM + conversion tracking), and Syslog
+  (structured logging for SIEM systems). Each service has its own detailed integration guide
+  with healthcare-grade PII protection, consent management, and environment-based feature flags.
+  Use this skill whenever someone asks to: add error tracking, integrate Sentry, add analytics,
+  set up Clarity, add Datadog monitoring, integrate Google Analytics, add GA4, set up conversion
+  pixels, add session recording, configure syslog, send logs to SIEM, add observability, set up
+  monitoring, track errors in production, add heatmaps, or integrate any tracking/analytics
+  service. Also trigger when someone says things like "I need error tracking", "add Sentry to
+  my React app", "set up analytics", "we need session recordings", "integrate Datadog RUM",
+  "add Google Tag Manager", "send logs to our SIEM", "we need observability", "track user
+  behavior", "monitor performance", or "add crash reporting". Works with any React application
+  — Vite, Next.js, Create React App, or custom webpack setups.
+version: 1.0.0
+scope: global
+last_reviewed: 2026-04-02
+---
+
+---
+name: observability-integrations
+description: >
+  Integrates observability, analytics, and monitoring services into React applications — Sentry
+  (error tracking + performance), Microsoft Clarity (heatmaps + session recording), Datadog
+  (RUM + logs + APM), Google Analytics/Pixels (GA4 + GTM + conversion tracking), and Syslog
+  (structured logging for SIEM systems). Each service has its own detailed integration guide
+  with healthcare-grade PII protection, consent management, and environment-based feature flags.
+  Use this skill whenever someone asks to: add error tracking, integrate Sentry, add analytics,
+  set up Clarity, add Datadog monitoring, integrate Google Analytics, add GA4, set up conversion
+  pixels, add session recording, configure syslog, send logs to SIEM, add observability, set up
+  monitoring, track errors in production, add heatmaps, or integrate any tracking/analytics
+  service. Also trigger when someone says things like "I need error tracking", "add Sentry to
+  my React app", "set up analytics", "we need session recordings", "integrate Datadog RUM",
+  "add Google Tag Manager", "send logs to our SIEM", "we need observability", "track user
+  behavior", "monitor performance", or "add crash reporting". Works with any React application
+  — Vite, Next.js, Create React App, or custom webpack setups.
+---
+
+# Observability Integrations
+
+You are a senior frontend platform engineer specializing in observability, monitoring, and analytics integration. You add tracking services to React applications with **healthcare-grade privacy** — every integration automatically scrubs PII, respects user consent, and operates behind environment-based feature flags with instant kill switches.
+
+## Core Principles — Apply to EVERY Integration
+
+1. **Privacy first**: In healthcare applications, patient data (NHI, names, DOB, medical records) MUST NEVER reach any third-party tracking service. Scrub automatically, don't rely on developers remembering.
+
+2. **Consent before tracking**: No tracking service initializes until the user has consented. Provide a consent management layer that all services hook into.
+
+3. **Environment isolation**: Tracking behaves differently per environment — disabled in development, sampled in staging, full in production. Never pollute production analytics with dev/test data.
+
+4. **Kill switch**: Every service can be disabled instantly via environment variable without code changes or redeployment.
+
+5. **Performance budget**: Each tracking script adds load time. Monitor total impact. Warn if combined tracking scripts exceed 100KB gzipped.
+
+6. **Structured, not scattered**: All integrations go through a centralized observability layer — not scattered `window.gtag()` calls throughout the codebase.
+
+---
+
+## Step 0: Understand the Application
+
+### Check for Legacy Intelligence
+
+If legacy project documentation exists (`.ai-skills/legacy-projects/{project}/` or `./{project}-intelligence/`):
+
+1. Read `MASTER_SKILL.md` — understand the application architecture, module map
+2. Read `BUSINESS_RULES.md` — identify which user actions are business-critical (these become tracked events)
+3. Read `API_REGISTRY.md` — identify which API calls should be monitored for performance
+4. Read `DATA_MODELS.md` — identify which fields contain PII/PHI that must be scrubbed from ALL tracking
+
+### Ask the User
+
+1. **Which service(s)?** Present the options:
+   - Sentry (error tracking, performance monitoring, session replay)
+   - Microsoft Clarity (heatmaps, session recording, behavior analytics)
+   - Datadog (RUM, logs, APM, full-stack monitoring)
+   - Google Analytics / Pixels (GA4, GTM, conversion tracking)
+   - Syslog (structured logging → SIEM forwarding)
+
+2. **React setup?** Vite, Next.js, CRA, or custom?
+
+3. **Is this a healthcare/medical application?** If yes, apply maximum PII scrubbing rules automatically.
+
+4. **Does the app handle payments?** If yes, configure e-commerce/conversion event tracking for GA4.
+
+5. **Existing tracking?** Are there any tracking scripts already in the app that need to coexist?
+
+---
+
+## Step 1: Build the Observability Foundation
+
+Before integrating any specific service, build the shared infrastructure that ALL services use.
+
+### 1.1 Folder Structure
+
+```
+src/
+├── observability/
+│   ├── index.ts                    ← Public API — re-exports everything
+│   ├── config.ts                   ← Environment-based configuration
+│   ├── consent.ts                  ← Consent management
+│   ├── pii-scrubber.ts             ← PII/PHI scrubbing engine
+│   ├── performance-budget.ts       ← Script size monitoring
+│   ├── types.ts                    ← Shared types
+│   ├── providers/
+│   │   ├── ObservabilityProvider.tsx  ← React context provider wrapping all services
+│   │   └── ConsentBanner.tsx         ← GDPR/privacy consent UI
+│   ├── hooks/
+│   │   ├── useTrackEvent.ts        ← Unified event tracking hook
+│   │   ├── useTrackPageView.ts     ← SPA page view tracking
+│   │   ├── useConsent.ts           ← Consent state hook
+│   │   └── useErrorBoundary.ts     ← Error boundary hook
+│   └── services/
+│       ├── sentry.ts               ← Sentry service adapter
+│       ├── clarity.ts              ← Clarity service adapter
+│       ├── datadog.ts              ← Datadog service adapter
+│       ├── google-analytics.ts     ← GA4 service adapter
+│       └── syslog.ts               ← Syslog service adapter
+```
+
+### 1.2 Configuration
+
+```typescript
+// src/observability/config.ts
+
+export interface ObservabilityConfig {
+  environment: 'development' | 'staging' | 'production'
+  isHealthcareApp: boolean
+
+  sentry: {
+    enabled: boolean
+    dsn: string
+    tracesSampleRate: number      // 0-1
+    replaySampleRate: number      // 0-1
+    replayOnErrorSampleRate: number
+    release?: string
+  }
+
+  clarity: {
+    enabled: boolean
+    projectId: string
+  }
+
+  datadog: {
+    enabled: boolean
+    applicationId: string
+    clientToken: string
+    site: string                  // e.g., 'datadoghq.com'
+    service: string
+    version?: string
+    sampleRate: number
+  }
+
+  googleAnalytics: {
+    enabled: boolean
+    measurementId: string         // G-XXXXXXXXXX
+    gtmContainerId?: string       // GTM-XXXXXXX
+    enableConversions: boolean
+    debugMode: boolean
+  }
+
+  syslog: {
+    enabled: boolean
+    endpoint: string              // Backend log collector URL
+    level: 'debug' | 'info' | 'warn' | 'error'
+    batchSize: number             // Flush after N logs
+    flushInterval: number         // Flush every N ms
+  }
+
+  consent: {
+    required: boolean             // If true, nothing loads until consent given
+    storageKey: string            // localStorage key for consent state
+    categories: ('necessary' | 'analytics' | 'marketing' | 'performance')[]
+  }
+
+  piiFields: string[]             // Field names to always scrub
+}
+
+export function loadConfig(): ObservabilityConfig {
+  const env = import.meta.env.MODE || process.env.NODE_ENV || 'development'
+  const isProd = env === 'production'
+
+  return {
+    environment: env as any,
+    isHealthcareApp: import.meta.env.VITE_HEALTHCARE_APP === 'true',
+
+    sentry: {
+      enabled: import.meta.env.VITE_SENTRY_ENABLED === 'true',
+      dsn: import.meta.env.VITE_SENTRY_DSN || '',
+      tracesSampleRate: isProd ? 0.2 : 1.0,
+      replaySampleRate: isProd ? 0.1 : 0,
+      replayOnErrorSampleRate: 1.0,
+      release: import.meta.env.VITE_APP_VERSION,
+    },
+
+    clarity: {
+      enabled: import.meta.env.VITE_CLARITY_ENABLED === 'true',
+      projectId: import.meta.env.VITE_CLARITY_PROJECT_ID || '',
+    },
+
+    datadog: {
+      enabled: import.meta.env.VITE_DATADOG_ENABLED === 'true',
+      applicationId: import.meta.env.VITE_DATADOG_APP_ID || '',
+      clientToken: import.meta.env.VITE_DATADOG_CLIENT_TOKEN || '',
+      site: import.meta.env.VITE_DATADOG_SITE || 'datadoghq.com',
+      service: import.meta.env.VITE_DATADOG_SERVICE || '',
+      version: import.meta.env.VITE_APP_VERSION,
+      sampleRate: isProd ? 100 : 0,
+    },
+
+    googleAnalytics: {
+      enabled: import.meta.env.VITE_GA_ENABLED === 'true',
+      measurementId: import.meta.env.VITE_GA_MEASUREMENT_ID || '',
+      gtmContainerId: import.meta.env.VITE_GTM_CONTAINER_ID,
+      enableConversions: import.meta.env.VITE_GA_CONVERSIONS === 'true',
+      debugMode: !isProd,
+    },
+
+    syslog: {
+      enabled: import.meta.env.VITE_SYSLOG_ENABLED === 'true',
+      endpoint: import.meta.env.VITE_SYSLOG_ENDPOINT || '',
+      level: (import.meta.env.VITE_SYSLOG_LEVEL || 'info') as any,
+      batchSize: 10,
+      flushInterval: 5000,
+    },
+
+    consent: {
+      required: true,  // Default: require consent
+      storageKey: 'observability_consent',
+      categories: ['necessary', 'analytics', 'performance'],
+    },
+
+    // Healthcare PII fields — ALWAYS scrub from ALL services
+    piiFields: [
+      'nhi', 'NHI', 'nhi_number', 'nhiNumber',
+      'firstName', 'first_name', 'lastName', 'last_name',
+      'fullName', 'full_name', 'name',
+      'dateOfBirth', 'date_of_birth', 'dob', 'DOB',
+      'email', 'phone', 'mobile', 'address',
+      'ssn', 'socialSecurityNumber',
+      'medicalRecordNumber', 'mrn',
+      'password', 'token', 'apiKey', 'secret',
+      'creditCard', 'cardNumber', 'cvv', 'expiryDate',
+    ],
+  }
+}
+```
+
+### 1.3 PII Scrubber
+
+```typescript
+// src/observability/pii-scrubber.ts
+
+const DEFAULT_REPLACEMENT = '[REDACTED]'
+
+export class PiiScrubber {
+  private sensitiveFields: Set<string>
+  private sensitivePatterns: RegExp[]
+
+  constructor(fields: string[]) {
+    this.sensitiveFields = new Set(fields.map(f => f.toLowerCase()))
+
+    // Patterns that catch PII even in unstructured text
+    this.sensitivePatterns = [
+      /[A-Z]{3}\d{4}/g,                          // NZ NHI number
+      /\b\d{3}[-.]?\d{3}[-.]?\d{4}\b/g,          // Phone numbers
+      /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/gi,  // Email addresses
+      /\b\d{4}[- ]?\d{4}[- ]?\d{4}[- ]?\d{4}\b/g,     // Credit card numbers
+      /\b\d{2}[-/]\d{2}[-/]\d{4}\b/g,            // Date of birth patterns
+    ]
+  }
+
+  // Scrub an object recursively
+  scrubObject<T extends Record<string, any>>(obj: T): T {
+    if (!obj || typeof obj !== 'object') return obj
+
+    const scrubbed = Array.isArray(obj) ? [...obj] : { ...obj }
+
+    for (const key of Object.keys(scrubbed)) {
+      if (this.sensitiveFields.has(key.toLowerCase())) {
+        (scrubbed as any)[key] = DEFAULT_REPLACEMENT
+      } else if (typeof scrubbed[key] === 'object' && scrubbed[key] !== null) {
+        (scrubbed as any)[key] = this.scrubObject(scrubbed[key])
+      } else if (typeof scrubbed[key] === 'string') {
+        (scrubbed as any)[key] = this.scrubString(scrubbed[key])
+      }
+    }
+
+    return scrubbed as T
+  }
+
+  // Scrub PII patterns from a string
+  scrubString(str: string): string {
+    let result = str
+    for (const pattern of this.sensitivePatterns) {
+      result = result.replace(pattern, DEFAULT_REPLACEMENT)
+    }
+    return result
+  }
+
+  // Scrub URL query parameters
+  scrubUrl(url: string): string {
+    try {
+      const parsed = new URL(url, 'http://localhost')
+      for (const [key] of parsed.searchParams) {
+        if (this.sensitiveFields.has(key.toLowerCase())) {
+          parsed.searchParams.set(key, DEFAULT_REPLACEMENT)
+        }
+      }
+      return parsed.pathname + parsed.search
+    } catch {
+      return url
+    }
+  }
+}
+```
+
+### 1.4 Consent Management
+
+```typescript
+// src/observability/consent.ts
+
+export type ConsentCategory = 'necessary' | 'analytics' | 'marketing' | 'performance'
+
+export interface ConsentState {
+  given: boolean
+  timestamp: string | null
+  categories: Record<ConsentCategory, boolean>
+}
+
+const DEFAULT_STATE: ConsentState = {
+  given: false,
+  timestamp: null,
+  categories: {
+    necessary: true,      // Always allowed
+    analytics: false,
+    marketing: false,
+    performance: false,
+  },
+}
+
+export class ConsentManager {
+  private state: ConsentState
+  private storageKey: string
+  private listeners: ((state: ConsentState) => void)[] = []
+
+  constructor(storageKey: string) {
+    this.storageKey = storageKey
+    this.state = this.load()
+  }
+
+  private load(): ConsentState {
+    try {
+      const stored = localStorage.getItem(this.storageKey)
+      return stored ? JSON.parse(stored) : { ...DEFAULT_STATE }
+    } catch {
+      return { ...DEFAULT_STATE }
+    }
+  }
+
+  private save(): void {
+    try {
+      localStorage.setItem(this.storageKey, JSON.stringify(this.state))
+    } catch { /* localStorage unavailable */ }
+  }
+
+  grantAll(): void {
+    this.state = {
+      given: true,
+      timestamp: new Date().toISOString(),
+      categories: { necessary: true, analytics: true, marketing: true, performance: true },
+    }
+    this.save()
+    this.notify()
+  }
+
+  grantSelected(categories: Partial<Record<ConsentCategory, boolean>>): void {
+    this.state = {
+      given: true,
+      timestamp: new Date().toISOString(),
+      categories: { ...this.state.categories, ...categories, necessary: true },
+    }
+    this.save()
+    this.notify()
+  }
+
+  revoke(): void {
+    this.state = { ...DEFAULT_STATE }
+    this.save()
+    this.notify()
+  }
+
+  hasConsent(category: ConsentCategory): boolean {
+    return this.state.categories[category] === true
+  }
+
+  isConsentGiven(): boolean {
+    return this.state.given
+  }
+
+  getState(): ConsentState {
+    return { ...this.state }
+  }
+
+  onChange(listener: (state: ConsentState) => void): () => void {
+    this.listeners.push(listener)
+    return () => { this.listeners = this.listeners.filter(l => l !== listener) }
+  }
+
+  private notify(): void {
+    this.listeners.forEach(l => l(this.getState()))
+  }
+}
+
+// Service → consent category mapping
+export const SERVICE_CONSENT_MAP: Record<string, ConsentCategory> = {
+  sentry: 'necessary',       // Error tracking is necessary for app stability
+  clarity: 'analytics',      // Session recording requires analytics consent
+  datadog: 'performance',    // Performance monitoring
+  googleAnalytics: 'analytics',
+  syslog: 'necessary',       // Operational logging is necessary
+}
+```
+
+### 1.5 Unified Tracking Hook
+
+```typescript
+// src/observability/hooks/useTrackEvent.ts
+
+import { useCallback } from 'react'
+import { useObservability } from '../providers/ObservabilityProvider'
+
+export interface TrackEventOptions {
+  name: string
+  category?: string
+  properties?: Record<string, any>
+  services?: ('sentry' | 'clarity' | 'datadog' | 'ga' | 'syslog')[]  // default: all enabled
+}
+
+export function useTrackEvent() {
+  const { services, scrubber } = useObservability()
+
+  return useCallback((options: TrackEventOptions) => {
+    const scrubbedProps = options.properties
+      ? scrubber.scrubObject(options.properties)
+      : undefined
+
+    const targetServices = options.services || Object.keys(services)
+
+    for (const svc of targetServices) {
+      if (services[svc]?.isEnabled()) {
+        services[svc].trackEvent(options.name, options.category, scrubbedProps)
+      }
+    }
+  }, [services, scrubber])
+}
+```
+
+### 1.6 SPA Page View Tracking
+
+```typescript
+// src/observability/hooks/useTrackPageView.ts
+
+import { useEffect } from 'react'
+import { useLocation } from 'react-router-dom'
+import { useObservability } from '../providers/ObservabilityProvider'
+
+export function useTrackPageView() {
+  const location = useLocation()
+  const { services, scrubber } = useObservability()
+
+  useEffect(() => {
+    const scrubbedPath = scrubber.scrubUrl(location.pathname + location.search)
+
+    for (const svc of Object.values(services)) {
+      if (svc.isEnabled()) {
+        svc.trackPageView(scrubbedPath, document.title)
+      }
+    }
+  }, [location.pathname])
+}
+```
+
+### 1.7 ObservabilityProvider
+
+```typescript
+// src/observability/providers/ObservabilityProvider.tsx
+
+import React, { createContext, useContext, useEffect, useMemo, useState } from 'react'
+import { loadConfig, ObservabilityConfig } from '../config'
+import { ConsentManager, SERVICE_CONSENT_MAP } from '../consent'
+import { PiiScrubber } from '../pii-scrubber'
+
+// Each service adapter implements this interface
+export interface ObservabilityService {
+  name: string
+  init(): void
+  shutdown(): void
+  isEnabled(): boolean
+  trackEvent(name: string, category?: string, properties?: Record<string, any>): void
+  trackPageView(path: string, title: string): void
+  setUser(userId: string, traits?: Record<string, any>): void
+  trackError(error: Error, context?: Record<string, any>): void
+}
+
+interface ObservabilityContextValue {
+  services: Record<string, ObservabilityService>
+  config: ObservabilityConfig
+  consent: ConsentManager
+  scrubber: PiiScrubber
+}
+
+const ObservabilityContext = createContext<ObservabilityContextValue | null>(null)
+
+export function useObservability() {
+  const ctx = useContext(ObservabilityContext)
+  if (!ctx) throw new Error('useObservability must be used within ObservabilityProvider')
+  return ctx
+}
+
+export function ObservabilityProvider({ children }: { children: React.ReactNode }) {
+  const config = useMemo(() => loadConfig(), [])
+  const consent = useMemo(() => new ConsentManager(config.consent.storageKey), [])
+  const scrubber = useMemo(() => new PiiScrubber(config.piiFields), [])
+  const [services, setServices] = useState<Record<string, ObservabilityService>>({})
+
+  useEffect(() => {
+    // Initialize services that have consent
+    const initServices: Record<string, ObservabilityService> = {}
+
+    // Import and init each enabled service
+    // Read the relevant reference file for each service's adapter implementation
+    // See: references/sentry.md, references/clarity.md, etc.
+
+    const handleConsentChange = () => {
+      // Re-evaluate which services should be active
+      for (const [name, svc] of Object.entries(initServices)) {
+        const category = SERVICE_CONSENT_MAP[name]
+        if (category && !consent.hasConsent(category)) {
+          svc.shutdown()
+        } else if (category && consent.hasConsent(category) && !svc.isEnabled()) {
+          svc.init()
+        }
+      }
+    }
+
+    consent.onChange(handleConsentChange)
+    setServices(initServices)
+
+    return () => {
+      Object.values(initServices).forEach(svc => svc.shutdown())
+    }
+  }, [])
+
+  return (
+    <ObservabilityContext.Provider value={{ services, config, consent, scrubber }}>
+      {children}
+    </ObservabilityContext.Provider>
+  )
+}
+```
+
+### 1.8 Environment Variables Template
+
+Generate `.env.example`:
+
+```bash
+# ── Observability Configuration ──
+
+# Healthcare mode — enables maximum PII scrubbing
+VITE_HEALTHCARE_APP=true
+
+# App version — used for release tracking
+VITE_APP_VERSION=1.0.0
+
+# ── Sentry ──
+VITE_SENTRY_ENABLED=false
+VITE_SENTRY_DSN=
+
+# ── Microsoft Clarity ──
+VITE_CLARITY_ENABLED=false
+VITE_CLARITY_PROJECT_ID=
+
+# ── Datadog ──
+VITE_DATADOG_ENABLED=false
+VITE_DATADOG_APP_ID=
+VITE_DATADOG_CLIENT_TOKEN=
+VITE_DATADOG_SITE=datadoghq.com
+VITE_DATADOG_SERVICE=
+
+# ── Google Analytics ──
+VITE_GA_ENABLED=false
+VITE_GA_MEASUREMENT_ID=
+VITE_GTM_CONTAINER_ID=
+VITE_GA_CONVERSIONS=false
+
+# ── Syslog ──
+VITE_SYSLOG_ENABLED=false
+VITE_SYSLOG_ENDPOINT=
+VITE_SYSLOG_LEVEL=info
+```
+
+---
+
+## Step 2: Integrate the Selected Service(s)
+
+After building the foundation, read the appropriate reference file for each service the user selected:
+
+| Service | Reference File | Consent Category |
+|---------|---------------|-----------------|
+| Sentry | `references/sentry.md` | necessary |
+| Microsoft Clarity | `references/clarity.md` | analytics |
+| Datadog | `references/datadog.md` | performance |
+| Google Analytics / Pixels | `references/google-analytics.md` | analytics |
+| Syslog → SIEM | `references/syslog.md` | necessary |
+
+Read the selected reference file(s) and implement the service adapter following the patterns defined there.
+
+Each reference file contains:
+1. NPM packages to install
+2. The service adapter class implementing `ObservabilityService` interface
+3. Initialization code (where and how to init)
+4. Event tracking patterns specific to that service
+5. PII scrubbing rules specific to that service
+6. Testing/verification steps
+7. Healthcare-specific configuration
+
+---
+
+## Step 3: Multi-Service Coexistence
+
+When integrating multiple services simultaneously:
+
+### Load Order
+Services must initialize in this order to avoid conflicts:
+1. **Sentry** first — catches errors from other service init
+2. **Syslog** second — operational logging is always needed
+3. **Datadog** third — performance monitoring before analytics
+4. **Google Analytics** fourth — analytics tracking
+5. **Clarity** last — session recording after everything else is stable
+
+### Performance Budget
+Monitor combined script sizes:
+
+```typescript
+// src/observability/performance-budget.ts
+
+const SCRIPT_SIZES_KB = {
+  sentry: 72,       // @sentry/react + @sentry/browser
+  clarity: 45,      // Clarity script (loaded async)
+  datadog: 55,      // @datadog/browser-rum
+  ga: 30,           // gtag.js
+  syslog: 5,        // Custom, minimal
+}
+
+export function checkPerformanceBudget(enabledServices: string[]): {
+  totalKb: number
+  overBudget: boolean
+  warning: string | null
+} {
+  const totalKb = enabledServices.reduce((sum, svc) => sum + (SCRIPT_SIZES_KB[svc] || 0), 0)
+  const overBudget = totalKb > 100
+
+  return {
+    totalKb,
+    overBudget,
+    warning: overBudget
+      ? `Tracking scripts total ${totalKb}KB gzipped (budget: 100KB). Consider disabling non-essential services or lazy-loading them.`
+      : null,
+  }
+}
+```
+
+### Deduplication
+If both Sentry and Datadog are enabled, errors will be captured twice. The adapters should coordinate:
+- Sentry handles detailed error tracking with stack traces
+- Datadog tracks the error as a RUM event without the full stack trace
+- Both get the same `correlationId` for cross-referencing
+
+---
+
+## Step 4: Wiring into the React App
+
+### App Entry Point
+
+```tsx
+// src/main.tsx or src/App.tsx
+
+import { ObservabilityProvider } from './observability/providers/ObservabilityProvider'
+import { ConsentBanner } from './observability/providers/ConsentBanner'
+
+function App() {
+  return (
+    <ObservabilityProvider>
+      <ConsentBanner />
+      <RouterProvider router={router} />
+    </ObservabilityProvider>
+  )
+}
+```
+
+### In Route Components — Page View Tracking
+
+```tsx
+// src/layouts/AppLayout.tsx
+
+import { useTrackPageView } from '../observability/hooks/useTrackPageView'
+
+function AppLayout() {
+  useTrackPageView()  // Tracks every route change across ALL enabled services
+
+  return (
+    <div>
+      <Outlet />
+    </div>
+  )
+}
+```
+
+### In Components — Event Tracking
+
+```tsx
+// src/features/booking/BookingConfirmation.tsx
+
+import { useTrackEvent } from '../../observability/hooks/useTrackEvent'
+
+function BookingConfirmation() {
+  const trackEvent = useTrackEvent()
+
+  const handleConfirm = async () => {
+    await submitBooking()
+
+    // Tracked in ALL enabled services automatically
+    // PII is scrubbed automatically by the hook
+    trackEvent({
+      name: 'booking_confirmed',
+      category: 'conversion',
+      properties: {
+        appointmentType: booking.type,
+        providerId: booking.providerId,
+        // patientName would be auto-scrubbed if included
+      },
+    })
+  }
+}
+```
+
+### Error Boundaries
+
+```tsx
+// src/observability/hooks/useErrorBoundary.ts
+
+import * as Sentry from '@sentry/react'
+
+// Use Sentry's error boundary for automatic error tracking
+export const ErrorBoundary = Sentry.ErrorBoundary
+
+// Fallback component
+export function ErrorFallback({ error, resetError }: { error: Error; resetError: () => void }) {
+  return (
+    <div className="flex flex-col items-center justify-center min-h-screen p-8">
+      <h1 className="text-2xl font-bold text-gray-900 mb-4">Something went wrong</h1>
+      <p className="text-gray-600 mb-6">We've been notified and are looking into it.</p>
+      <Button onClick={resetError}>Try Again</Button>
+    </div>
+  )
+}
+```
+
+---
+
+## Step 5: Verification
+
+After integrating, verify each service:
+
+### Per-Service Verification Checklist
+
+- [ ] Service initializes only when enabled via env var
+- [ ] Service does NOT initialize until consent is given (for analytics/marketing categories)
+- [ ] Service tracks page views on route changes
+- [ ] Service tracks custom events
+- [ ] PII is scrubbed from all tracked data (test with a fake NHI number — it should appear as [REDACTED] in the service dashboard)
+- [ ] Service respects kill switch (set env var to false, confirm no requests to service)
+- [ ] Service does not error when disabled (graceful no-op)
+- [ ] Source maps uploaded (Sentry/Datadog — for readable stack traces)
+- [ ] No patient names, NHI numbers, or medical data appear in ANY service dashboard
+
+### Integration Test
+
+```typescript
+describe('Observability', () => {
+  it('should scrub PII from tracked events', () => {
+    const scrubber = new PiiScrubber(config.piiFields)
+    const event = {
+      name: 'patient_viewed',
+      patientName: 'John Smith',
+      nhi: 'ABC1234',
+      email: 'john@example.com',
+      appointmentType: 'General Checkup',
+    }
+
+    const scrubbed = scrubber.scrubObject(event)
+
+    expect(scrubbed.patientName).toBe('[REDACTED]')
+    expect(scrubbed.nhi).toBe('[REDACTED]')
+    expect(scrubbed.email).toBe('[REDACTED]')
+    expect(scrubbed.appointmentType).toBe('General Checkup')  // NOT PII, kept
+  })
+
+  it('should not initialize tracking without consent', () => {
+    const consent = new ConsentManager('test_consent')
+    expect(consent.hasConsent('analytics')).toBe(false)
+    // Clarity and GA should NOT be initialized
+  })
+})
+```
+
+---
+
+## Quality Gate
+
+Before delivering:
+
+- [ ] Foundation built: config, consent, PII scrubber, provider, hooks
+- [ ] Selected service(s) integrated via adapter pattern
+- [ ] All PII fields from config are scrubbed in ALL services
+- [ ] Consent management working — services only init after consent
+- [ ] Kill switch working — env var disables each service independently
+- [ ] SPA page views tracked on route changes
+- [ ] Error boundary in place with fallback UI
+- [ ] `.env.example` generated with all required variables
+- [ ] No raw `window.gtag()` or `window.clarity()` calls scattered in components — all through the observability layer
+- [ ] Performance budget checked — combined scripts under 100KB warning threshold
+- [ ] Tests verify PII scrubbing and consent behavior