| 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 <jeremy@intentsolutions.io> |
| tags | ["saas","posthog","posthog-reference"] |
| compatibility | Designed for Claude Code |
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
= {
: ,
: ,
: ,
: ,
: ,
: ,
: ,
: ,
: ,
: ,
: ,
: ,
: ,
: ,
: ,
: ,
: ,
} ;
{
?: | | ;
?: | | ;
}
= {
[.]: & { : | | };
[.]: & { : ; ?: };
[.]: & { : ; : | ; : };
};
