Project structure

Contents

Note: This page refers to our main product repository, not our website.

Directory tree

text
.
├── bin              # Shell scripts wrapped by hogli, the unified developer CLI
├── common           # Shared code: PostHog SQL parser, HogVM, shared UI packages
├── tools            # Developer/CI tooling (hogli framework, hogli-commands, openapi-codegen, ...)
├── ee               # Enterprise platform package features (separate license)
├── frontend         # React/TypeScript frontend application
│   └── src
│       └── layout   # App layout components (navigation, sidebars)
│       └── lib      # Reusable components and utilities
│       └── scenes   # Page-specific components
│       └── queries  # Query builder components
│       └── toolbar  # PostHog Toolbar code
├── livestream       # Golang service for live events API
├── playwright       # End-to-end tests using Playwright
├── nodejs           # Node.js service for event ingestion and plugins
├── posthog          # Django backend application
│   └── api          # REST API endpoints
│   └── clickhouse   # ClickHouse database interactions
│   └── hogql        # HogQL query language implementation
│   └── models       # Django ORM models
│   └── tasks        # Celery background tasks
├── products         # Product-specific code (vertical slices)
└── rust             # High-performance Rust services


*Selected subdirectories only

Key directories

frontend

The PostHog web application, built with React and TypeScript. Uses Kea for state management.

  • src/lib – Reusable components and utilities
  • src/scenes – Page-specific components organized by feature
  • src/queries – Query builder and data visualization components
  • src/toolbar – Code for the PostHog Toolbar

The app-level Files scene lives in src/scenes/project-files and reuses the project tree from src/layout/panel-layout/ProjectTree. Open /project/<project_id>/files to browse the project, or add ?folder=Research to start in a folder. Starred folders in the sidebar use the same "New..." menu and "Empty folder" state as project folders. With simple-sidepanel enabled, each user gets a public Users/<name> home folder in each project, starred on creation. Names receive a numeric suffix when another folder already uses the path. The home-folder record survives deletion, and later visits do not recreate or restar it. The user's own folder keeps its home icon after a rename or move and shows "Empty home folder" when expanded and empty. An info tooltip explains that everyone in the project can see its contents and shows the folder's current path. Creating an item from a starred folder uses the original folder's full path, including its parent folders. With simple-sidepanel enabled, the Apps and Files tabs use "Filter apps" and "Filter files" to filter their contents. The file filter and options buttons stay beside the filter field; alphabetical and recently added sorting are in the options menu. App tooltips reuse the product descriptions from the scene configuration. Opening Apps or Files from the collapsed sidebar temporarily expands the navigation over the page without changing the saved collapsed setting. Selecting a destination, clicking outside, or pressing Escape closes the temporary navigation.

The app-level terminal lives in src/scenes/terminal and opens with Ctrl+backtick when enabled. It starts without fetching the project tree. Browsing /posthog/files loads and caches each folder's immediate children; /posthog/api loads objects by type. Loading another folder leaves cached folders untouched, and API type directories can be opened directly even if they are not listed yet. Notebook format detection waits until notebooks are browsed, and object contents load only when opened. ph refresh reloads the directories already visited, rebuilds the cached tree once, and reloads the connected tool catalog.

posthog

The Django backend application. Key subdirectories:

  • api – REST API endpoints and serializers
  • clickhouse – ClickHouse schema definitions and migrations
  • hogql – PostHog SQL query language compiler and executor
  • models – Django ORM models (PostgreSQL)
  • tasks – Celery background tasks

products

Product-specific code organized as vertical slices. Each product folder contains its own backend (Django app), frontend (React), and optionally shared code. This structure allows features to evolve independently.

See the products README for detailed conventions.

nodejs

Node.js service responsible for:

  • Event ingestion and processing
  • Running plugins and data pipelines
  • Webhook delivery

rust

High-performance Rust services including:

  • capture – Event capture endpoint
  • feature-flags – Feature flag evaluation
  • cymbal – Error tracking symbolication
  • Various workers and utilities

common

Shared code used across the codebase:

  • hogql_parser – PostHog SQL parser (C++)
  • hogvm – Hog virtual machine
  • tailwind – Shared Tailwind configuration

tools

Developer and CI tooling, not imported by runtime code:

  • hogli – Developer CLI framework (PyPI-publishable)
  • hogli-commands – PostHog-specific hogli commands
  • openapi-codegen – OpenAPI client/spec generation
  • (and others — see tools/)

ee

Enterprise edition licensed features. This directory has a separate license - not MIT. For 100% FOSS code, see PostHog/posthog-foss.

playwright

End-to-end tests using Playwright. Tests live in the e2e/ subdirectory.

livestream

Golang service powering the live events feed in the Activity tab.

Was this page useful?