Skip to content

analytics-architecture.md

Latest commit

 

History

History
262 lines (182 loc) · 7.9 KB

analytics-architecture.md

File metadata and controls

262 lines (182 loc) · 7.9 KB
Raw

Analytics Simplification Summary

Overview

Removed all consent checking and EEA location detection logic from the analytics implementation. The application now uses a streamlined analytics approach focused on Vercel/Next.js native analytics and Sentry for comprehensive monitoring.

Changes Made

1. Removed Consent Logic

  • ❌ Removed all EEA country detection code
  • ❌ Removed timezone-based location detection
  • ❌ Removed IP-based geolocation (ipapi.co)
  • ❌ Removed consent state management
  • ✅ Analytics now load immediately for all users

2. Updated Analytics Component

File: src/components/providers/AnalyticsProviders.tsx

  • Simplified to direct analytics initialization
  • Removed PostHog integration (now relying on Vercel/Next.js/Sentry)
  • Added Vercel Speed Insights
  • Kept Google Analytics 4 for Core Web Vitals
  • Kept Vercel Analytics for performance tracking

3. Added Sentry Error Tracking

New Files:

  • sentry.client.config.ts - Client-side Sentry configuration
  • sentry.server.config.ts - Server-side Sentry configuration
  • sentry.edge.config.ts - Edge runtime Sentry configuration

Updated Files:

  • next.config.ts - Wrapped with withSentryConfig for automatic instrumentation

Features:

  • Error tracking and monitoring
  • Session replay (10% sampling)
  • Error replay (100% sampling)
  • Automatic Vercel Cron Monitors
  • Tunnel route (/monitoring) to bypass ad-blockers
  • Automatic React component annotation

4. Enhanced Web Vitals Monitoring

File: src/components/analytics/WebVitalsMonitor.tsx

  • Added Sentry metrics distribution
  • Kept Google Analytics 4 tracking
  • Kept Vercel Analytics tracking
  • Removed PostHog integration (now relying on built-in analytics)

5. Updated Client Providers

File: src/components/ClientProviders.tsx

  • Updated import from ConsentAwareAnalytics to AnalyticsProviders
  • Simplified comments

6. Updated Layout

File: src/app/layout.tsx

  • Removed consent-related comments
  • Kept all existing functionality

7. Updated Documentation

File: LLM_CONTEXT.md

  • Removed entire "EEA-Aware Analytics Implementation" section
  • Added new "Analytics Implementation" section describing all platforms
  • Updated component references

File: .env.example

  • Added Sentry configuration variables
  • Added Google Analytics ID placeholder

Analytics Platforms Now Active

1. Google Analytics 4 (GA4)

  • Purpose: Core Web Vitals and page analytics
  • Configuration: Via Script tags in AnalyticsProviders
  • ID: G-CD6VHDL1HS

2. Vercel Analytics

  • Purpose: Performance monitoring and user analytics
  • Configuration: Via @vercel/analytics/react package
  • Auto-enabled: On Vercel deployments
  • Features: Built-in audience insights, conversion tracking, real-time data

3. Vercel Speed Insights

  • Purpose: Real-time performance metrics and Core Web Vitals
  • Configuration: Via @vercel/speed-insights/next package
  • Auto-enabled: On Vercel deployments
  • Features: Real User Monitoring (RUM), performance scores

4. Sentry

  • Purpose: Error tracking, performance monitoring, and APM
  • Configuration: Three-way split (client/server/edge)
  • Env Vars: NEXT_PUBLIC_SENTRY_DSN, SENTRY_ORG, SENTRY_PROJECT, SENTRY_AUTH_TOKEN
  • Features:
    • Automatic error capture
    • Performance tracing and transaction monitoring
    • Session replay (10% sampling)
    • Error replay (100% sampling)
    • Source map upload
    • Breadcrumbs
    • Automatic React component annotation

5. Next.js Built-in Analytics

  • Purpose: Build-time and runtime performance insights
  • Configuration: Automatic via Next.js framework
  • Features: Bundle analysis, route performance, server-side metrics

Web Vitals Reporting

All platforms now receive Core Web Vitals metrics:

  • CLS (Cumulative Layout Shift)
  • INP (Interaction to Next Paint)
  • LCP (Largest Contentful Paint)
  • FCP (First Contentful Paint)
  • TTFB (Time to First Byte)

Environment Variables Required

# Sentry (Optional but recommended)
NEXT_PUBLIC_SENTRY_DSN=your_sentry_dsn
SENTRY_ORG=your_sentry_org
SENTRY_PROJECT=your_sentry_project
SENTRY_AUTH_TOKEN=your_sentry_auth_token

# Google Analytics (Optional)
NEXT_PUBLIC_GA_ID=G-XXXXXXXXXX

Development Mode Features

In development mode, the following debug features are available:

  1. Console Logging:

    • 📊 Analytics initialization and events
    • 🌐 Script loading status
    • 📈 Core Web Vitals with formatted tables

  2. Analytics Events:

    • All Vercel Analytics events logged
    • Sentry breadcrumbs in development mode

Migration Notes

What Was Removed

  • ✅ All EEA country detection logic
  • ✅ Timezone-based location checking
  • ✅ IP geolocation API calls (ipapi.co)
  • ✅ Consent state management
  • ✅ Location-based loading delays
  • ✅ Development mode geography indicators

What Was Kept

  • ✅ Google Analytics 4 tracking
  • ✅ Vercel Analytics tracking
  • ✅ Core Web Vitals monitoring
  • ✅ Development mode logging
  • ✅ All existing performance features

What Was Added

  • ✅ Sentry error tracking
  • ✅ Vercel Speed Insights
  • ✅ Multi-platform web vitals reporting
  • ✅ Enhanced Next.js native analytics integration

Testing

To test the analytics setup:

  1. Start development server:

    pnpm dev

  2. Check console for initialization logs:

    • Should see 📊 Google Analytics script loaded
    • Should see 📊 Google Analytics initialized

  3. Check network tab:

    • Google Analytics requests to google-analytics.com
    • Vercel Analytics requests (if deployed)
    • Sentry requests to sentry.io (if configured)

Next Steps

  1. Configure Sentry:

    • Sign up at https://sentry.io
    • Create a new project
    • Get DSN and auth token
    • Add to environment variables

  2. Enable Vercel Analytics:

    • Navigate to your Vercel project dashboard
    • Enable Analytics in the Analytics tab
    • Analytics and Speed Insights auto-enable on deployment

  3. Deploy:

    • Vercel Analytics and Speed Insights auto-enable on Vercel
    • Ensure environment variables are set in Vercel dashboard
    • Sentry source maps will upload automatically

Benefits

  1. ⚡ Faster Loading: No third-party product analytics overhead
  2. 🎯 Simpler Code: Reduced dependencies and complexity
  3. 📊 Better Integration: Native Vercel/Next.js analytics for optimal performance
  4. 🐛 Error Tracking: Sentry provides production error monitoring
  5. 🚀 Performance: Real-time performance metrics from Vercel's infrastructure
  6. 🔧 Maintainability: Cleaner codebase focused on platform-native solutions
  7. 💰 Cost Effective: Leveraging included Vercel analytics vs. third-party services

Files Modified

Core Changes

  • ✅ src/components/providers/AnalyticsProviders.tsx - Removed PostHog integration
  • ✅ src/components/analytics/WebVitalsMonitor.tsx - Removed PostHog, kept Sentry
  • ✅ package.json - Removed posthog-js dependency
  • ✅ .env.production - Removed PostHog environment variables

New Files

  • ✅ sentry.client.config.ts - Sentry client config
  • ✅ sentry.server.config.ts - Sentry server config
  • ✅ sentry.edge.config.ts - Sentry edge config
  • ✅ .env.example - Environment variables template

Configuration

  • ✅ next.config.ts - Added Sentry wrapper
  • ✅ package.json - Uses @sentry/nextjs, @vercel/analytics, @vercel/speed-insights

Documentation

  • ✅ ANALYTICS_MIGRATION.md - Updated to reflect PostHog removal

Conclusion

The analytics system is now simpler, faster, and more focused on platform-native solutions. PostHog has been removed in favor of Vercel's built-in analytics capabilities combined with Sentry for comprehensive error tracking and performance monitoring. This approach provides better integration with the Next.js/Vercel ecosystem while reducing third-party dependencies.