Project structure

Last updated:

|Edit this page

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

Directory tree

├── .github
├── .platform
├── bin
├── cypress
├── ee
├── frontend
│ └── public
│ └── src
│ └── layout
│ └── lib
│ └── models
│ └── scenes
│ └── style
│ └── toolbar
├── posthog
│ └── api
│ └── management
│ └── migrations
│ └── models
│ └── queries
│ └── tasks
│ └── templates
│ └── test
└── requirements
*Selected subdirectories only


Directory for our GitHub actions and templates for issues and pull requests.


Scripts for deploying to


Executable shell scripts for various purposes, most notably building, testing, and running PostHog.


Hosts our Cypress tests. When writing tests that use Cypress, you will mostly be working on the integration/ subdirectory. Remember that you should always be including tests if you are making a significant change to our frontend.


Enterprise Edition features for PostHog. This subdirectory is the only subdirectory not MIT-Licensed in the PostHog/posthog repository, and a license is needed to use its features. To use PostHog with 100% FOSS code, refer to our PostHog/posthog-foss repository.


Hosts the PostHog frontend, built with React.



PostHog logos to be used by the app.


Code for the frontend.


Components referring to the overall PostHog app layout, such as sections of the app used in most pages, like Sidebar.js.


Various components used all around the PostHog app. Reusable components will most likely be placed in this subdirectory, such as buttons, charts, etc.


Kea models for the app's state.


Components referring to specific pages of the PostHog app. Mostly non-reusable.


Sass files for the PostHog app's style.


All code related exclusively to the PostHog Toolbar.


Hosts the PostHog backend, built with Django.



Subdirectory for PostHog's REST API. Includes its own tests.


Custom Django management commands. Commands defined here are registered as commands and can be called with:

./ <your_command_here>
# or
python <your_command_here>

These commands are for admin use only, and generally refer to the configuration of your Django app.


Hosts the database migrations which occur when there are changes to the models. If you make any changes to the app's ORM, you need to first make migrations:

python makemigrations

And after making your own migrations or running git pull after new migrations, you also need to apply them:

python migrate

ClickHouse Migrations

To create boilerplate for clickhouse migrations use

python create_ch_migration --name <name of migration>

To apply clickhouse migrations use

python migrate_clickhouse


Subdirectory for the models (Django ORM). Interactions with our database are handled by these models.


Hosts the queries used to query data from our database, which will be used by our various features, such as Retention and Trends.


Celery tasks that happen in the "background" of the server to enhance PostHog's performance by preventing long processes from blocking the main thread. An example of task is processing events as they come in.


Django templates used to generate dynamic HTML. We use templates for pages such as /login and /setup_admin.


Subdirectory hosting our backend tests. You should always include tests when you make changes to our backend.


Hosts our backend's dev requirements.


Was this page useful?

Next article

How we review PRs

Almost all PRs made to PostHog repositories will need a review from another engineer. We do this because, almost every time we review a PR, we find a bug, a performance issue, unnecessary code or UX that could have been confusing. Here's how we do it: Have a flick through the code changes What to look for: Does the code fit into our coding conventions? Is the code free of bugs? How will the solution perform at huge scale? Are the database queries scalable (do they use the right indexes)? Are the…

Read next article