Skip to content

Commit ce3f062

Browse files
Copilotpauldambra
Copilot
and
pauldambra
committed
Update project structure documentation with current PostHog/posthog repo layout
Co-authored-by: pauldambra <984817+pauldambra@users.noreply.github.com>
1 parent 25e6cb5 commit ce3f062

File tree

1 file changed

+59
-135
lines changed

1 file changed

+59
-135
lines changed

‎contents/handbook/engineering/project-structure.md‎

Lines changed: 59 additions & 135 deletions
Original file line numberDiff line numberDiff line change
@@ -10,164 +10,88 @@ showTitle: true
1010

1111
```
1212
.
13-
├── .github
14-
├── .platform
15-
├── bin
16-
├── cypress
17-
├── ee
18-
├── frontend
19-
│ └── public
13+
├── bin # Shell scripts for building, testing, and running PostHog
14+
├── common # Shared code: HogQL parser, HogVM, shared UI packages
15+
├── ee # Enterprise Edition features (separate license)
16+
├── frontend # React/TypeScript frontend application
2017
│ └── src
21-
│ └── layout
22-
│ └── lib
23-
│ └── models
24-
│ └── scenes
25-
│ └── style
26-
│ └── toolbar
27-
├── livestream
28-
├── posthog
29-
│ └── api
30-
│ └── management
31-
│ └── migrations
32-
│ └── models
33-
│ └── queries
34-
│ └── tasks
35-
│ └── templates
36-
│ └── test
37-
└── requirements
18+
│ └── layout # App layout components (navigation, sidebars)
19+
│ └── lib # Reusable components and utilities
20+
│ └── scenes # Page-specific components
21+
│ └── queries # Query builder components
22+
│ └── toolbar # PostHog Toolbar code
23+
├── livestream # Golang service for live events API
24+
├── playwright # End-to-end tests using Playwright
25+
├── plugin-server # Node.js service for event ingestion and plugins
26+
├── posthog # Django backend application
27+
│ └── api # REST API endpoints
28+
│ └── clickhouse # ClickHouse database interactions
29+
│ └── hogql # HogQL query language implementation
30+
│ └── models # Django ORM models
31+
│ └── tasks # Celery background tasks
32+
├── products # Product-specific code (vertical slices)
33+
└── rust # High-performance Rust services
3834
3935
*Selected subdirectories only
40-
4136
```
4237

43-
## `.github`
44-
45-
Directory for our GitHub actions and templates for issues and pull requests.
46-
47-
## `.platform`
48-
49-
Scripts for deploying to Platform.sh.
50-
51-
## `bin`
52-
53-
Executable shell scripts for various purposes, most notably building, testing, and running PostHog.
54-
55-
## `cypress`
56-
57-
Hosts our [Cypress](https://www.cypress.io/) 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.
58-
59-
## `ee`
60-
61-
Enterprise Edition features for PostHog. This subdirectory is the only subdirectory not MIT-Licensed in the [PostHog/posthog](https://github.com/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](https://github.com/PostHog/posthog-foss) repository.
62-
63-
## `frontend`
64-
65-
Hosts the PostHog frontend, built with React.
66-
67-
### Subdirectories
68-
69-
#### `public`
70-
71-
PostHog logos to be used by the app.
72-
73-
#### `src`
74-
75-
Code for the frontend.
76-
77-
##### `src/layout`
78-
79-
Components referring to the overall PostHog app layout, such as sections of the app used in most pages, like `Sidebar.js`.
80-
81-
##### `src/lib`
82-
83-
Various components used all around the PostHog app. Reusable components will most likely be placed in this subdirectory, such as buttons, charts, etc.
84-
85-
##### `src/models`
86-
87-
[Kea](https://github.com/keajs/kea) models for the app's state.
38+
## Key directories
8839

89-
##### `src/scenes`
40+
### `frontend`
9041

91-
Components referring to specific pages of the PostHog app. Mostly non-reusable.
42+
The PostHog web application, built with React and TypeScript. Uses [Kea](https://github.com/keajs/kea) for state management.
9243

93-
##### `src/styles`
44+
- `src/lib` – Reusable components and utilities
45+
- `src/scenes` – Page-specific components organized by feature
46+
- `src/queries` – Query builder and data visualization components
47+
- `src/toolbar` – Code for the [PostHog Toolbar](/docs/user-guides/toolbar)
9448

95-
[Sass](https://sass-lang.com/) files for the PostHog app's style.
49+
### `posthog`
9650

97-
##### `toolbar`
51+
The Django backend application. Key subdirectories:
9852

99-
All code related exclusively to the [PostHog Toolbar](/docs/user-guides/toolbar).
53+
- `api` – REST API endpoints and serializers
54+
- `clickhouse` – ClickHouse schema definitions and migrations
55+
- `hogql` – HogQL query language compiler and executor
56+
- `models` – Django ORM models (PostgreSQL)
57+
- `tasks` – Celery background tasks
10058

101-
## `livestream`
59+
### `products`
10260

103-
The live events API, a Golang service (used in the Live tab of Activity in the app).
61+
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.
10462

105-
## `posthog`
106-
107-
Hosts the PostHog backend, built with Django.
108-
109-
### Subdirectories
110-
111-
#### `api`
112-
113-
Subdirectory for PostHog's REST API. Includes its own tests.
114-
115-
#### `management`
116-
117-
Custom [Django management commands](https://docs.djangoproject.com/en/3.1/howto/custom-management-commands/). Commands defined here are registered as `manage.py` commands and can be called with:
118-
119-
```bash
120-
./manage.py <your_command_here>
121-
# or
122-
python manage.py <your_command_here>
123-
```
124-
125-
These commands are for admin use only, and generally refer to the configuration of your Django app.
126-
127-
#### `migrations`
128-
129-
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:
130-
```
131-
python manage.py makemigrations
132-
```
133-
134-
And after making your own migrations or running `git pull` after new migrations, you also need to apply them:
135-
```
136-
python manage.py migrate
137-
```
138-
139-
#### `ClickHouse Migrations`
140-
141-
To create boilerplate for clickhouse migrations use
142-
```
143-
python manage.py create_ch_migration --name <name of migration>
144-
```
145-
146-
To apply clickhouse migrations use
147-
```
148-
python manage.py migrate_clickhouse
149-
```
63+
See the [products README](https://github.com/PostHog/posthog/blob/master/products/README.md) for detailed conventions.
15064

151-
#### `models`
65+
### `plugin-server`
15266

153-
Subdirectory for the models ([Django ORM](https://docs.djangoproject.com/en/3.1/topics/db/models/)). Interactions with our database are handled by these models.
67+
Node.js service responsible for:
68+
- Event ingestion and processing
69+
- Running plugins and data pipelines
70+
- Webhook delivery
15471

155-
#### `queries`
72+
### `rust`
15673

157-
Hosts the queries used to query data from our database, which will be used by our various features, such as [Retention](/docs/user-guides/retention) and [Trends](/docs/user-guides/trends).
74+
High-performance Rust services including:
75+
- `capture` – Event capture endpoint
76+
- `feature-flags` – Feature flag evaluation
77+
- `cymbal` – Error tracking symbolication
78+
- Various workers and utilities
15879

159-
#### `tasks`
80+
### `common`
16081

161-
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.
82+
Shared code used across the codebase:
83+
- `hogql_parser` – HogQL parser (C++)
84+
- `hogvm` – Hog virtual machine
85+
- `tailwind` – Shared Tailwind configuration
16286

163-
#### `templates`
87+
### `ee`
16488

165-
[Django templates](https://docs.djangoproject.com/en/3.1/topics/templates/) used to generate dynamic HTML. We use templates for pages such as `/login` and `/setup_admin`.
89+
Enterprise Edition features. This directory has a [separate license](https://github.com/PostHog/posthog/blob/master/ee/LICENSE) - not MIT. For 100% FOSS code, see [PostHog/posthog-foss](https://github.com/PostHog/posthog-foss).
16690

167-
#### `test`
91+
### `playwright`
16892

169-
Subdirectory hosting our backend tests. You should always include tests when you make changes to our backend.
93+
End-to-end tests using [Playwright](https://playwright.dev/). Tests live in the `e2e/` subdirectory.
17094

171-
### `requirements`
95+
### `livestream`
17296

173-
Hosts our backend's dev requirements.
97+
Golang service powering the live events feed in the Activity tab.

0 commit comments

Comments
 (0)