Skip to main content

Source: ocean/docs/adr/0038-posthog-analytics-implementation.md | ✏️ Edit on GitHub

ADR-003: PostHog Analytics Implementation

Date: 2025-01-29 Status: Accepted

Context​

We need comprehensive analytics and feature flag management for Ocean to:

  • Track user behavior and product usage
  • Implement plan-based feature restrictions
  • Monitor API usage and enforce rate limits
  • Enable A/B testing and gradual feature rollouts
  • Understand user journeys and conversion funnels

Decision​

We have chosen PostHog as our analytics and feature flag platform, implementing both client-side and server-side tracking.

Client-Side Implementation​

  • Use posthog-js for React/Vite frontend
  • Automatic user identification on auth state changes
  • Event tracking for forms, buttons, and navigation
  • Client-side feature flag evaluation
  • Session recording and page view tracking

Server-Side Implementation​

  • Use posthog-node for Vercel Edge Functions
  • API request tracking and monitoring
  • Server-side feature flag evaluation for access control
  • Rate limiting enforcement based on user plans
  • Edge middleware for automatic API tracking

Feature Flag Strategy​

Implemented SaaS-focused feature flags:

  • Storage limits: Plan-based storage restrictions (1GB free, configurable)
  • Team limits: Member count restrictions (3 for free, unlimited for enterprise)
  • API access: Disabled for free plans, enabled for paid
  • Rate limits: 100 requests/hour for free, higher for paid plans
  • Advanced features: Export, analytics, SSO gated by plan

Consequences​

Positive​

  • Unified analytics: Single platform for both client and server analytics
  • Real-time insights: Immediate visibility into user behavior and API usage
  • Flexible feature control: Instant feature flag updates without deployments
  • Plan enforcement: Automatic restriction of features based on subscription
  • Privacy compliant: GDPR-ready with user opt-out capabilities
  • Cost effective: PostHog's generous free tier suits our needs

Negative​

  • Additional dependency: Reliance on external service for feature flags
  • Learning curve: Team needs to understand PostHog's concepts
  • Data volume: High-traffic apps may exceed free tier limits
  • Latency: Feature flag checks add minimal API call overhead

Neutral​

  • Data ownership: Events stored in PostHog's US cloud
  • Integration complexity: Requires both client and server implementations
  • Maintenance: Feature flags need regular review and cleanup

Implementation Details​

Environment Variables​

VITE_POSTHOG_API_KEY=phc_hqVEnjLBIdcwVAmYEkTWTHxBaEQVOQ7Mmi31fiUofIp
VITE_POSTHOG_HOST=https://us.posthog.com
VITE_POSTHOG_PROJECT_ID=133001

Key Files​

  • /src/lib/posthog.ts - Client-side service
  • /src/lib/posthog-edge.ts - Server-side service
  • /src/contexts/posthog-context.tsx - React context provider
  • /src/hooks/use-analytics.ts - Analytics hooks
  • /src/hooks/use-posthog-features.ts - Feature flag hooks
  • /middleware.ts - API tracking middleware

Usage Patterns​

Client-side:

const { trackButtonClick } = useAnalytics()
const canExport = useFeatureFlag(FEATURE_FLAGS.DATA_EXPORT_ENABLED)

Server-side:

await trackEdgeEvent(userId, 'api_request', { endpoint: '/api/data' })
const hasAccess = await evaluateFeatureFlag(userId, 'api-access-enabled')

Alternatives Considered​

  1. Google Analytics + LaunchDarkly

    • Pros: Best-in-class individual tools
    • Cons: Two separate services, higher cost, more complex

  2. Mixpanel

    • Pros: Powerful analytics, good cohort analysis
    • Cons: No feature flags, expensive at scale

  3. Custom Solution

    • Pros: Full control, no external dependencies
    • Cons: High development cost, maintenance burden

  4. Segment + Feature Flag Service

    • Pros: Flexible routing, multiple destinations
    • Cons: Complex setup, multiple vendors

References​