posthog-reference-architecture

name	posthog-reference-architecture
description	Production PostHog architecture: event taxonomy, SDK layering, feature flag strategy, analytics module layout, and data pipeline integration patterns. Trigger: "posthog architecture", "posthog best practices", "posthog project structure", "how to organize posthog", "posthog design".
allowed-tools	Read, Grep
version	1.12.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","posthog","posthog-reference"]
compatibility	Designed for Claude Code, also compatible with Codex and OpenClaw

PostHog Reference Architecture

Overview

Production-grade architecture for PostHog analytics in a web application. Covers file structure, event taxonomy design, SDK initialization layers, feature flag management, group analytics for B2B, and data pipeline integration.

Prerequisites

• PostHog Cloud or self-hosted instance
• posthog-js and posthog-node SDKs
• Next.js or React application (patterns adapt to other frameworks)

Architecture

┌─────────────────────────────────────────────────────┐
│  Browser (posthog-js)                                │
│  $pageview, $autocapture, custom events, identify   │
│  Feature flag evaluation, session recordings         │
└────────────┬────────────────────────────────────────┘
             │ HTTPS (direct or reverse proxy)
             ▼
┌─────────────────────────────────────────────────────┐
│  PostHog Cloud (us.i.posthog.com)                    │
│  ┌──────────┐  ┌──────────┐  ┌───────────────────┐  │
│  │ Events   │  │ Feature  │  │ Session Replay    │  │
│  │ Pipeline │  │ Flags    │  │ & Recordings      │  │
│  └────┬─────┘  └────┬─────┘  └───────────────────┘  │
│       │              │                                │
│  ┌────┴──────────────┴────────────────────────────┐  │
│  │  Analytics: Trends, Funnels, Retention, Paths  │  │
│  │  HogQL (SQL), Dashboards, Cohorts              │  │
│  └────────────────────────────────────────────────┘  │
│  ┌────────────────────────────────────────────────┐  │
│  │  CDP: Destinations (Webhook, Slack, S3, etc.)  │  │
│  └────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────┘
             ▲
             │ posthog-node (server events, local flag eval)
┌────────────┴────────────────────────────────────────┐
│  Backend (API routes, webhooks, crons)               │
│  Server-side capture, group identify, flag eval      │
└─────────────────────────────────────────────────────┘

Instructions

Step 1: Project File Structure

src/
├── analytics/
│   ├── posthog.ts           # Browser SDK init (singleton)
│   ├── posthog-server.ts    # Server SDK init (singleton)
│   ├── events.ts            # Typed event constants
│   ├── flags.ts             # Feature flag key constants
│   └── hooks/
│       ├── useFeatureFlag.ts    # React hook for boolean flags
│       └── useExperiment.ts     # React hook for A/B variants
├── app/
│   ├── providers.tsx        # PostHogProvider wrapper
│   └── layout.tsx           # Root layout with provider
└── lib/
    └── analytics.ts         # High-level tracking functions

Step 2: Event Taxonomy

// analytics/events.ts
// Naming convention: object_action (noun_verb)
   = {
  
  : ,
  : ,
  : ,
  : ,

  
  : ,           
  : ,
  : ,
  : ,
  : ,
  : ,

  
  : ,
  : ,
  : ,
  : ,
  : ,

  
  : ,
  : ,
}  ;


  {
  ?:  |  | ;
  ?:  |  | ;
}


  = {
  [.]:  & { :  |  |  };
  [.]:  & { : ; ?:  };
  [.]:  & { : ; :  | ; :  };
};