# https://github.com/PostHog/posthog Project Manual

Generated at: 2026-07-21 20:59:59 UTC

## Table of Contents

- [PostHog Overview and Monorepo Architecture](#page-1)
- [AI Agents, Max AI, and Self-Driving Mode](#page-2)
- [Data Ingestion, HogQL, and ClickHouse Backend](#page-3)
- [Frontend Application, LemonUI, and Product Features](#page-4)

<a id='page-1'></a>

## PostHog Overview and Monorepo Architecture

### Related Pages

Related topics: [AI Agents, Max AI, and Self-Driving Mode](#page-2), [Data Ingestion, HogQL, and ClickHouse Backend](#page-3), [Frontend Application, LemonUI, and Product Features](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/PostHog/posthog/blob/main/README.md)
- [docs/internal/monorepo-layout.md](https://github.com/PostHog/posthog/blob/main/docs/internal/monorepo-layout.md)
- [AGENTS.md](https://github.com/PostHog/posthog/blob/main/AGENTS.md)
- [package.json](https://github.com/PostHog/posthog/blob/main/package.json)
- [pnpm-workspace.yaml](https://github.com/PostHog/posthog/blob/main/pnpm-workspace.yaml)
- [posthog/api/__init__.py](https://github.com/PostHog/posthog/blob/main/posthog/api/__init__.py)
- [frontend/package.json](https://github.com/PostHog/posthog/blob/main/frontend/package.json)
- [plugin-server/package.json](https://github.com/PostHog/posthog/blob/main/plugin-server/package.json)
- [packages/browser/README.md](https://github.com/PostHog/posthog/blob/main/packages/browser/README.md)
- [hogvm/README.md](https://github.com/PostHog/posthog/blob/main/hogvm/README.md)
</details>

# PostHog Overview and Monorepo Architecture

## What PostHog Is and What This Repository Contains

PostHog is an open-source developer-focused product analytics suite that bundles product analytics, session recording, feature flags, experimentation, A/B testing, heatmaps, surveys, error tracking, and a data warehouse into a single platform. The `PostHog/posthog` GitHub repository is the canonical home for the project and is structured as a single multi-language monorepo rather than a collection of separate repositories.

The repository holds the cloud platform code, the in-product React application, the plugin server, a Rust-based virtual machine that executes HogQL and feature-flag logic, and the source for nearly every first-party client SDK (JavaScript, Node, React Native, iOS, Android, Go, Python, Ruby, PHP, Flutter, Java, etc.). By keeping these pieces in one tree, the PostHog team coordinates changes to shared schemas, query languages, and protocols across the entire stack. Source: [README.md:1-40]().

## Repository Layout and Workspace Topology

The repo is a `pnpm` workspace (with additional Python and Rust sub-trees) declared at the root in `pnpm-workspace.yaml` and orchestrated through a root `package.json` whose scripts drive the build, lint, and test workflows. Source: [pnpm-workspace.yaml:1-30](). The most important top-level directories are:

| Directory | Purpose | Primary Stack |
|---|---|---|
| `posthog/` | Cloud backend: HTTP API, ingestion, batch processing, Django apps | Python, Django, ClickHouse, Kafka |
| `frontend/` | In-app admin UI and website front-end | React, TypeScript, Kea, PostHog-JS |
| `plugin-server/` | Long-running Node service that loads plugins, processes events | Node.js, TypeScript |
| `hogvm/` | Hog language bytecode VM for evaluating filters, flags, and HogQL | Rust |
| `rust/` | Shared Rust crates reused by Python and Node via FFI/NAPI | Rust |
| `packages/` | First-party client SDKs, CLI, and shared tooling (e.g. `browser`, `node`, `react-native`, `posthog-cli`, `eslint-plugin-posthog`, `schema`) | TypeScript, Kotlin, Swift, Dart, Ruby, etc. |
| `docs/` | User and internal documentation, including monorepo guidance | Markdown |
| `bin/` | Build, release, and ops scripts | Shell |

Source: [docs/internal/monorepo-layout.md:1-80](), [package.json:1-120](), [posthog/api/__init__.py:1-60](), [plugin-server/package.json:1-80]().

The Python backend is a standard Django project; the `posthog/api/` package registers DRF views that expose the public REST API used by every SDK. Source: [posthog/api/__init__.py:1-60]().

## High-Level Architecture

```mermaid
flowchart LR
    SDK[Client SDKs<br/>packages/browser, packages/node,<br/>iOS, Android, RN, Flutter, Go, Python, Ruby, PHP, Java]
    INGEST[Ingestion API<br/>posthog/api]
    PLUGIN[Plugin Server<br/>plugin-server]
    HOOKS[Webhooks & Destinations]
    DB[(ClickHouse / Postgres / Kafka)]
    FRONTEND[React Admin UI<br/>frontend]
    HOGVM[HogVM<br/>hogvm, Rust]
    RUST[Shared Rust Crates<br/>rust]

    SDK -->|capture, identify, feature flag| INGEST
    INGEST --> PLUGIN
    PLUGIN --> DB
    PLUGIN --> HOOKS
    PLUGIN --> HOGVM
    INGEST --> HOGVM
    DB <--> FRONTEND
    RUST --> HOGVM
    RUST --> PLUGIN
    RUST --> INGEST
```

The SDKs collect events and feature-flag decisions on customer devices and forward them to the Python ingestion API; the plugin server then fans the events out to transformations, destinations, and the data warehouse, while the React front-end queries the warehouse for dashboards. Source: [README.md:10-40](), [plugin-server/package.json:1-60](), [hogvm/README.md:1-40](), [packages/browser/README.md:1-60]().

## Build, Development, and Cross-Cutting Tooling

Because the monorepo spans Python, TypeScript, Rust, and several mobile targets, the root `package.json` exposes workspace scripts that wrap the per-language toolchains so contributors only need Node, pnpm, Python, and Cargo installed. Source: [package.json:1-120](). The shared `packages/` tree contains not only SDKs but also lint and schema packages consumed by the front-end and backend; this is how a single change to an event property or feature-flag payload type can be propagated to all consumers in one PR. Source: [docs/internal/monorepo-layout.md:1-80]().

Internal contributors (and AI coding agents) are guided by `AGENTS.md`, which codifies conventions for navigation, testing, and PR hygiene across the workspace. Source: [AGENTS.md:1-80](). The `frontend/package.json` declares the React toolchain (Vite/Webpack, Kea for state, and PostHog-JS for in-app telemetry), and ties into the same lint and type-check scripts defined at the root. Source: [frontend/package.json:1-120]().

## How the Pieces Relate to Community Concerns

The community topics captured in the issue tracker map directly onto this layout: requests such as *React Native Session Recordings* (#13269) and *iOS Session Recordings* (#12344) touch the mobile SDKs under `packages/` and the ingestion pipeline in `posthog/`. The long-running *Product tours / guides* discussion (#25726) extends the React app and the surveys subsystem. *End-user facing analytics* (#14330) is primarily a frontend and query-layer concern that flows through HogVM. *Feature flags for Java* (#16419) lives in the Java SDK package and the shared flag-evaluation code that the Rust VM executes. Source: [docs/internal/monorepo-layout.md:1-80](), [hogvm/README.md:1-40](), [packages/browser/README.md:1-60]().

## Summary

In short, the `posthog` monorepo is a coordinated workspace where a Django/ClickHouse backend, a React front-end, a Node plugin server, a Rust VM, and a large family of SDK packages evolve together through a single `pnpm` workspace and shared Rust and TypeScript libraries. Understanding this layout is the prerequisite for almost every other subsystem page in this wiki.

---

<a id='page-2'></a>

## AI Agents, Max AI, and Self-Driving Mode

### Related Pages

Related topics: [PostHog Overview and Monorepo Architecture](#page-1), [Data Ingestion, HogQL, and ClickHouse Backend](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [ee/hogai/README.md](https://github.com/PostHog/posthog/blob/main/ee/hogai/README.md)
- [ee/hogai/chat_agent/graph.py](https://github.com/PostHog/posthog/blob/main/ee/hogai/chat_agent/graph.py)
- [ee/hogai/core/agent_modes/factory.py](https://github.com/PostHog/posthog/blob/main/ee/hogai/core/agent_modes/factory.py)
- [.agents/skills/implementing-mcp-tools/SKILL.md](https://github.com/PostHog/posthog/blob/main/.agents/skills/implementing-mcp-tools/SKILL.md)
- [ee/hogai/tools/execute_sql/tool.py](https://github.com/PostHog/posthog/blob/main/ee/hogai/tools/execute_sql/tool.py)
</details>

# AI Agents, Max AI, and Self-Driving Mode

## Overview and Scope

PostHog ships an enterprise-edition AI assistant known as **Max AI** that lives in `ee/hogai/`. The module exposes a chat agent that can answer questions, query product data, and execute actions against a user's PostHog workspace. A central design decision is that the agent operates behind a LangGraph-style state graph rather than a single LLM call, which lets the assistant loop through tool invocations, retain intermediate state, and gate side-effects behind human approval. Source: [ee/hogai/README.md:1-40]().

The system is intentionally split into two runtime concerns:

- **Conversation logic** — message routing, tool selection, and reply synthesis, defined in `ee/hogai/chat_agent/graph.py`.
- **Agent modes** — the autonomy policy applied to a turn, defined in `ee/hogai/core/agent_modes/factory.py`.

This separation allows the same chat graph to behave very differently depending on whether the user invoked an assistant, an autonomous research mode, or a fully unsupervised "self-driving" mode.

## Agent Architecture

The chat agent is built as a directed graph where nodes represent processing stages (intent classification, tool selection, tool execution, response drafting) and edges represent transitions between them. Source: [ee/hogai/chat_agent/graph.py:1-80]().

```mermaid
flowchart LR
    A[User Message] --> B[Router Node]
    B --> C{Autonomy Mode}
    C -->|Assistant| D[Suggest Tools]
    C -->|Self-Driving| E[Execute Tools]
    D --> F[Draft Reply]
    E --> F
    F --> G[Final Response]
```

The router node inspects the incoming message, the conversation history, and the active mode, then chooses whether to plan, request clarification, or invoke a tool. Tools themselves are first-class objects with structured input schemas, and each tool call produces a typed result that is fed back into the graph as part of the next state. Source: [ee/hogai/README.md:42-90]().

Because every step is a node, the same graph can be exercised in three ways: interactively in the UI, programmatically via the API, or in batch for evaluation. The evaluation harness reuses the same node functions, which keeps the deployed behavior identical to what is measured offline.

## Agent Modes and Self-Driving Mode

Agent modes are constructed by a factory that returns a mode-specific configuration object containing the autonomy level, the set of allowed tools, and whether destructive actions require confirmation. Source: [ee/hogai/core/agent_modes/factory.py:1-60]().

| Mode | Confirmation Required | Tool Set | Typical Use |
|---|---|---|---|
| Assistant | Yes, per action | Read-only + safe writes | Guided analysis |
| Research | Yes, per group | Read-only | Investigations |
| Self-Driving | No, except flagged dangerous | Full workspace | Autonomous workflows |

**Self-Driving Mode** is the highest-autonomy mode. When activated, the agent is permitted to chain multiple tool calls without waiting for user approval. The factory still flags a small subset of operations — schema migrations, billing changes, and other irreversible side-effects — as "always-confirm" regardless of mode, so self-driving does not mean unconstrained. Source: [ee/hogai/core/agent_modes/factory.py:62-140]().

The mode is selected per-conversation and is surfaced in the UI as a toggle. Internally, each node reads the active mode from the graph state and branches accordingly, which is why the same `graph.py` can power every mode without duplication.

## Tools, MCP, and the Skills System

Tools are Python objects that implement a small interface: a name, a description (consumed by the LLM), an input schema, and a `run` coroutine. PostHog also exposes a subset of its tools through the **Model Context Protocol (MCP)**, letting external MCP-compatible clients reuse the same capabilities. Source: [.agents/skills/implementing-mcp-tools/SKILL.md:1-60]().

The MCP skill documentation is itself stored in the repository at `.agents/skills/`, which is a discoverable playbook that the engineering team — and contributing agents — consult when adding new tools. It prescribes the file layout, schema validation rules, and the registration step that wires a tool into the graph. Source: [.agents/skills/implementing-mcp-tools/SKILL.md:60-140]().

As a concrete example, the SQL execution tool validates the incoming query, applies row and column limits, runs it against the user's data warehouse, and returns a tabular result plus an optional chart suggestion. Source: [ee/hogai/tools/execute_sql/tool.py:1-80](). In self-driving mode the same tool may be called repeatedly to drill from a high-level metric down to its components, with each result feeding the next query.

## Community Signals and Operational Notes

The community evidence shows rapid iteration on the agent skills subsystem — releases `agent-skills-v0.183.0` through `agent-skills-v0.190.0` shipped in quick succession, indicating that tool and skill definitions are evolving faster than the underlying chat graph. This is consistent with the architecture: the graph is stable, while the tool catalogue expands through the documented skill workflow.

Because tools and modes are decoupled, contributors can add capabilities (for example, a new analytics tool) without touching `graph.py`. They register the tool, add an entry to the mode factory if it should be gated, and the existing graph picks it up on the next deployment. Source: [ee/hogai/README.md:90-150]().

For end users, the practical implication is that **Max AI** behaves like a chat assistant by default, becomes a more autonomous analyst in research mode, and only in self-driving mode will it execute multi-step workflows unattended — with the small set of irreversible operations still prompting for confirmation.

---

<a id='page-3'></a>

## Data Ingestion, HogQL, and ClickHouse Backend

### Related Pages

Related topics: [PostHog Overview and Monorepo Architecture](#page-1), [AI Agents, Max AI, and Self-Driving Mode](#page-2)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [common/hogql_parser/README.md](https://github.com/PostHog/posthog/blob/main/common/hogql_parser/README.md)
- [common/ingestion/acceptance_tests/run_tests.py](https://github.com/PostHog/posthog/blob/main/common/ingestion/acceptance_tests/run_tests.py)
- [posthog/clickhouse/client.py](https://github.com/PostHog/posthog/blob/main/posthog/clickhouse/client.py)
- [posthog/clickhouse/kafka.py](https://github.com/PostHog/posthog/blob/main/posthog/clickhouse/kafka.py)
- [posthog/clickhouse/query_tagging.py](https://github.com/PostHog/posthog/blob/main/posthog/clickhouse/query_tagging.py)
- [posthog/hogql/parser.py](https://github.com/PostHog/posthog/blob/main/posthog/hogql/parser.py)
- [posthog/hogql/compiler.py](https://github.com/PostHog/posthog/blob/main/posthog/hogql/compiler.py)
- [posthog/api/capture.py](https://github.com/PostHog/posthog/blob/main/posthog/api/capture.py)
- [posthog/models/event.py](https://github.com/PostHog/posthog/blob/main/posthog/models/event.py)
- [products/README.md](https://github.com/PostHog/posthog/blob/main/products/README.md)
- [products/data_warehouse/README.md](https://github.com/PostHog/posthog/blob/main/products/data_warehouse/README.md)
</details>

# Data Ingestion, HogQL, and ClickHouse Backend

PostHog's analytics pipeline is built on three tightly coupled layers: a high-throughput **event ingestion** path, a SQL-flavored query language called **HogQL** that the rest of the platform compiles against, and a **ClickHouse** cluster that stores petabyte-scale event and person data. Together they power product analytics, feature flags evaluation, session recordings metadata, data warehouse queries, and the in-app insights UI.

## Event Ingestion Pipeline

Ingestion begins at the public HTTP endpoints and is fanned out through Kafka before being materialized into ClickHouse. The capture endpoint validates payload shape, enriches events with team context, and pushes them onto a Kafka topic for asynchronous consumption.

The ingestion API entrypoint accepts both browser-style `POST /capture/` and server-side `POST /batch/` payloads, normalizes them through the shared parser, and produces Kafka messages. Source: [posthog/api/capture.py:1-120]().

Downstream of capture, dedicated Kafka consumers drain the topic into ClickHouse tables such as `events`, `person`, and `groups`. The acceptance test harness exercises the full path end-to-end, replaying JSON fixtures through the real capture → Kafka → ClickHouse flow to detect regressions. Source: [common/ingestion/acceptance_tests/run_tests.py:1-80]().

A simplified view of the data flow:

```mermaid
flowchart LR
    A[Client SDK] --> B[/capture API/]
    B --> C[Kafka topic: events_plugin_ingestion]
    C --> D[Consumer worker]
    D --> E[(ClickHouse: events, person, groups)]
    E --> F[HogQL queries]
    F --> G[Insights / API / Warehouse]
```

## HogQL: From AST to ClickHouse SQL

HogQL is PostHog's internal SQL dialect. It is parsed into an AST, then compiled into ClickHouse SQL with team-scoped filters, virtual field resolution, and dialect translations. The parser module exposes the lexer, parser, and visitors that produce a typed AST. Source: [posthog/hogql/parser.py:1-160]().

The compiler walks the AST and emits a ClickHouse-flavored SQL string, substituting PostHog-specific helpers (e.g. `hogql_value`, property matchers, timestamp transforms) with their native equivalents. Source: [posthog/hogql/compiler.py:1-200]().

The shared parser package documents the supported grammar, including select statements, joins, CTEs, window functions, lambdas, and the dialect extensions PostHog adds on top of ANSI SQL. Source: [common/hogql_parser/README.md:1-60]().

HogQL underpins three call sites: the **insights** endpoint used by the web app's trends and funnels screens, the **data warehouse** SQL editor, and the **HogQL query API** (`/api/environments/:team_id/query/`). Each call site compiles to ClickHouse and tags the query so it can be attributed back to the originating feature in observability dashboards.

## ClickHouse Backend

The ClickHouse layer is the system of record for analytics. The client module owns connection management, query execution, settings propagation, and failure handling. Source: [posthog/clickhouse/client.py:1-150]().

The Kafka integration abstracts producer and consumer setup so that ingestion modules can publish and subscribe without touching driver-level configuration. Source: [posthog/clickhouse/kafka.py:1-120]().

Every query executed through the client is decorated with a `QueryLogEntry` that records the team, the source feature, the HogQL string, and the rendered ClickHouse SQL. Source: [posthog/clickhouse/query_tagging.py:1-100]().

The primary tables mirror the event model:

| Table | Purpose | Key columns |
|-------|---------|-------------|
| `events` | Raw and enriched events | `team_id`, `event`, `timestamp`, `properties`, `person_id` |
| `person` | Materialized person state | `team_id`, `id`, `properties`, `is_identified` |
| `groups` | Group analytics entities | `team_id`, `group_type_index`, `group_key`, `properties` |

Event objects carry denormalized fields used by HogQL such as `person.properties`, `$session_id`, and `$window_id`. Source: [posthog/models/event.py:1-200]().

## Cross-Cutting Concerns

Three concerns cut across ingestion, HogQL, and ClickHouse:

1. **Team isolation** — every row is keyed by `team_id`, and the compiler injects `WHERE team_id = {team_id}` automatically so user code cannot leak data across tenants. Source: [posthog/hogql/compiler.py:200-260]().
2. **Property materialization** — event and person properties live in nested JSON; HogQL exposes them as first-class columns via virtual field mapping so queries read like relational SQL. Source: [posthog/hogql/parser.py:160-260]().
3. **Observability** — every capture and every HogQL execution is logged with structured fields, enabling dashboards that attribute ClickHouse cost back to individual features. Source: [posthog/clickhouse/query_tagging.py:100-160]().

The product layer reflects the same decomposition: ingestion feeds both first-party PostHog products and external data warehouse sources. Source: [products/README.md:1-80](), and the data warehouse product runs user-supplied SQL through the same HogQL compiler used internally. Source: [products/data_warehouse/README.md:1-60]().

Community threads on this topic focus on the practical consequences of this architecture: limits around event payload size, the cost of high-cardinality properties in ClickHouse, and the latency added by the Kafka buffer before events are queryable in trends. The team's general guidance is to keep property keys low-cardinality and to prefer HogQL over raw ClickHouse for application code so tenant filters and query tagging stay consistent.

---

<a id='page-4'></a>

## Frontend Application, LemonUI, and Product Features

### Related Pages

Related topics: [PostHog Overview and Monorepo Architecture](#page-1), [Data Ingestion, HogQL, and ClickHouse Backend](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [frontend/src/index.tsx](https://github.com/PostHog/posthog/blob/main/frontend/src/index.tsx)
- [frontend/src/scenes/sceneLogic.ts](https://github.com/PostHog/posthog/blob/main/frontend/src/scenes/sceneLogic.ts)
- [frontend/src/layout/scenes/SceneLayout.tsx](https://github.com/PostHog/posthog/blob/main/frontend/src/layout/scenes/SceneLayout.tsx)
- [frontend/src/lib/lemon-ui/LemonButton/LemonButton.tsx](https://github.com/PostHog/posthog/blob/main/frontend/src/lib/lemon-ui/LemonButton/LemonButton.tsx)
- [frontend/src/lib/lemon-ui/LemonTable/LemonTable.tsx](https://github.com/PostHog/posthog/blob/main/frontend/src/lib/lemon-ui/LemonTable/LemonTable.tsx)
- [frontend/src/scenes/dashboard/Dashboard.tsx](https://github.com/PostHog/posthog/blob/main/frontend/src/scenes/dashboard/Dashboard.tsx)
- [frontend/src/lib/feature-flags/featureFlagLogic.ts](https://github.com/PostHog/posthog/blob/main/frontend/src/lib/feature-flags/featureFlagLogic.ts)
</details>

# Frontend Application, LemonUI, and Product Features

The PostHog frontend is a React and TypeScript single-page application that ships the entire product (analytics, feature flags, experiments, session recordings, surveys, more) to the browser under a coherent design system called LemonUI. This page summarizes how the application is bootstrapped, how routes map to product surfaces ("scenes"), and how the LemonUI library and feature-flag logic knit those surfaces together.

## Application Bootstrapping and Scene Routing

The browser bundle is bootstrapped from `frontend/src/index.tsx`, which mounts the React tree, wires the kea state container, and initializes cross-cutting providers such as authentication, theme, query clients, and the PostHog analytics client.

Source: [frontend/src/index.tsx:1-80]()

PostHog's frontend uses a kea-based scene model: every product surface is registered as a *scene* under `frontend/src/scenes/`. Scene registration, authentication guards, and 404 fallthrough are coordinated by `frontend/src/scenes/sceneLogic.ts`, which exposes a kea store that maps URL patterns to scene mounts. The mapping is consumed by the main layout to render scenes inside a shared chrome.

Source: [frontend/src/scenes/sceneLogic.ts:1-120]()

The shared chrome is implemented by `frontend/src/layout/scenes/SceneLayout.tsx`, which provides side navigation, breadcrumbs, project switchers, and contextual action slots. Scene-level components populate those slots via props or `useValues` on their own scene logic, so each product surface can contribute its own header actions without owning the surrounding layout.

Source: [frontend/src/layout/scenes/SceneLayout.tsx:1-60]()

## LemonUI Design System

LemonUI is PostHog's internal component library and design system, which unifies the visual language across every scene. It lives under `frontend/src/lib/lemon-ui/` and is consumed directly by scenes and layout code rather than being published as a separate npm package. This lets the team iterate on components alongside the features that depend on them, with the trade-off that components are tightly coupled to the monorepo's tooling.

### Key Components

The library centers on a small set of leaf components that scenes compose into lists, dialogs, and forms:

- `LemonButton`, defined in `frontend/src/lib/lemon-ui/LemonButton/LemonButton.tsx`, replaces ad-hoc `<button>` markup. It exposes a typed `type` union (primary, secondary, tertiary, danger, link), a `size` scale, a `loading` state, and icon-left/icon-right slots. The component is the de-facto action primitive for toolbars, dialogs, and empty-state CTAs.

Source: [frontend/src/lib/lemon-ui/LemonButton/LemonButton.tsx:1-120]()

- `LemonTable`, defined in `frontend/src/lib/lemon-ui/LemonTable/LemonTable.tsx`, provides typed column definitions, inline editing, sorting, embedded tooltips, and a controlled-row pattern. Dashboards, persons, feature flags, experiments, and several admin pages all consume it as their primary data-grid component.

Source: [frontend/src/lib/lemon-ui/LemonTable/LemonTable.tsx:1-160]()

Other shared primitives include `LemonInput`, `LemonSelect`, `LemonDialog`, `LemonTabs`, `LemonTag`, and `LemonSnackbar`. Higher-level patterns (empty states, error boundaries) are also standardized in the same folder, which keeps scene code focused on product behavior rather than chrome.

## Product Features as Scenes

PostHog ships roughly a dozen first-party products, each implemented as a directory under `frontend/src/scenes/`. A scene typically owns its own kea logic, API bindings, and React components, and registers itself with `sceneLogic` so the URL is routable. Representative scenes include:

- `frontend/src/scenes/dashboard/Dashboard.tsx`, which renders the project home screen with tile-based metrics sourced from insights and other scenes.

Source: [frontend/src/scenes/dashboard/Dashboard.tsx:1-100]()

- `frontend/src/scenes/insights/`, the analytics workhorse covering trends, funnels, retention, and paths.
- `frontend/src/scenes/feature-flags/`, the flag management surface.
- `frontend/src/scenes/session-recordings/`, which renders the recording player and lists.
- `frontend/src/scenes/surveys/`, the in-app survey builder (community issue #25726 notes demand for a *product tours* extension on top of these same primitives).

Because each scene is a directory rather than a single file, cross-cutting concerns are extracted to `frontend/src/lib/`. For example, `frontend/src/lib/feature-flags/featureFlagLogic.ts` exposes the cached feature-flag payload used by both server-rendered flags and client-side gating.

Source: [frontend/src/lib/feature-flags/featureFlagLogic.ts:1-80]()

Other shared libraries include `frontend/src/lib/notebooks/`, `frontend/src/lib/hedgehog/`, and similar folders that several scenes consume. This makes the codebase look "feature-folder by scene, library by concern," which scales as more products land on the dashboard.

### Feature Flag Gating

Scenes and LemonUI components can opt into client-side gating via `featureFlagLogic`. Recent community threads (#16419 on Java feature flags, #12344 on iOS session recordings, #13269 on React Native session recordings, #14330 on B2B2B/B2B2C end-user analytics) all describe surfaces whose behavior on the dashboard is ultimately driven by these stored flags, whether the underlying SDK is mobile, server, or browser-based.

Source: [frontend/src/lib/feature-flags/featureFlagLogic.ts:80-200]()

## Architectural Summary

The frontend is organized into well-separated layers. The table below captures the typical request-to-render path:

| Layer | Responsibility | Location |
| --- | --- | --- |
| Bootstrap | React root, providers, error boundaries | `frontend/src/index.tsx` |
| Layout | Chrome, navigation, breadcrumbs, action slots | `frontend/src/layout/` |
| Scenes | One product surface per directory | `frontend/src/scenes/<product>/` |
| LemonUI | Shared primitives and design tokens | `frontend/src/lib/lemon-ui/` |
| Cross-cutting libs | API clients, feature flag logic, notebooks, components used by multiple scenes | `frontend/src/lib/` |

Source: [frontend/src/index.tsx:1-80]()
Source: [frontend/src/layout/scenes/SceneLayout.tsx:1-60]()
Source: [frontend/src/scenes/sceneLogic.ts:1-120]()
Source: [frontend/src/lib/lemon-ui/LemonButton/LemonButton.tsx:1-120]()
Source: [frontend/src/lib/feature-flags/featureFlagLogic.ts:1-200]()

This layering lets teams ship products (dashboards, surveys, experiments, recordings) independently while reusing a consistent component vocabulary and routing machinery. New product surfaces typically follow the same recipe: register the scene in `sceneLogic`, build the scene's React tree, compose LemonUI primitives, and gate client-only behavior through `featureFlagLogic`.

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: PostHog/posthog

Summary: Found 18 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

## 1. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: 0.7.24 — 2026-06-16
- User impact: Upgrade or migration may change expected behavior: 0.7.24 — 2026-06-16
- Evidence: failure_mode_cluster:github_release | https://github.com/PostHog/posthog/releases/tag/posthog-cli/v0.7.24

## 2. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: Renovate: Dependency Status
- User impact: Developers may fail before the first successful local run: Renovate: Dependency Status
- Evidence: failure_mode_cluster:github_issue | https://github.com/PostHog/posthog/issues/54967

## 3. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/PostHog/posthog/issues/54967

## 4. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/PostHog/posthog

## 5. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/PostHog/posthog

## 6. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/PostHog/posthog

## 7. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/PostHog/posthog

## 8. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/PostHog/posthog

## 9. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/PostHog/posthog

## 10. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: Agent skills agent-skills-v0.183.0
- User impact: Upgrade or migration may change expected behavior: Agent skills agent-skills-v0.183.0
- Evidence: failure_mode_cluster:github_release | https://github.com/PostHog/posthog/releases/tag/agent-skills-v0.183.0

## 11. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: Agent skills agent-skills-v0.184.0
- User impact: Upgrade or migration may change expected behavior: Agent skills agent-skills-v0.184.0
- Evidence: failure_mode_cluster:github_release | https://github.com/PostHog/posthog/releases/tag/agent-skills-v0.184.0

## 12. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: Agent skills agent-skills-v0.185.0
- User impact: Upgrade or migration may change expected behavior: Agent skills agent-skills-v0.185.0
- Evidence: failure_mode_cluster:github_release | https://github.com/PostHog/posthog/releases/tag/agent-skills-v0.185.0

## 13. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: Agent skills agent-skills-v0.186.0
- User impact: Upgrade or migration may change expected behavior: Agent skills agent-skills-v0.186.0
- Evidence: failure_mode_cluster:github_release | https://github.com/PostHog/posthog/releases/tag/agent-skills-v0.186.0

## 14. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: Agent skills agent-skills-v0.187.0
- User impact: Upgrade or migration may change expected behavior: Agent skills agent-skills-v0.187.0
- Evidence: failure_mode_cluster:github_release | https://github.com/PostHog/posthog/releases/tag/agent-skills-v0.187.0

## 15. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: Agent skills agent-skills-v0.188.0
- User impact: Upgrade or migration may change expected behavior: Agent skills agent-skills-v0.188.0
- Evidence: failure_mode_cluster:github_release | https://github.com/PostHog/posthog/releases/tag/agent-skills-v0.188.0

## 16. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: Agent skills agent-skills-v0.189.0
- User impact: Upgrade or migration may change expected behavior: Agent skills agent-skills-v0.189.0
- Evidence: failure_mode_cluster:github_release | https://github.com/PostHog/posthog/releases/tag/agent-skills-v0.189.0

## 17. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: Agent skills agent-skills-v0.190.0
- User impact: Upgrade or migration may change expected behavior: Agent skills agent-skills-v0.190.0
- Evidence: failure_mode_cluster:github_release | https://github.com/PostHog/posthog/releases/tag/agent-skills-v0.190.0

## 18. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: posthog-cli latest
- User impact: Upgrade or migration may change expected behavior: posthog-cli latest
- Evidence: failure_mode_cluster:github_release | https://github.com/PostHog/posthog/releases/tag/posthog-cli-latest

<!-- canonical_name: PostHog/posthog; human_manual_source: deepwiki_human_wiki -->