:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
Architecture guidelines
Each rule is tagged with what catches a violation.
[lint: <id>] means a linter, semgrep rule, or invariant test blocks it, so CI is the check and this text is only the reasoning.
[review] means nothing catches it automatically — a reader is the only control.
Entrypoints and layering
- Keep entrypoints thin.
[review]The runtime calls the entrypoint first: a DRF view, a management commandhandle(), a Celery task body, an HTTP handler, a Rustmain(), a React component. An entrypoint reads the input, connects the dependencies, and formats the output. All other logic goes in a function the entrypoint calls, so a test can call it directly. If the area already has a place for that logic, use it rather than making a new one. - A product under
products/is scaffolded, not hand-rolled.[lint: hogli product:lint --all]Create one withhogli product:bootstrap <name>, because the scaffold emits a product that is isolated from its first commit. See "New products must be isolated" in products/README.md for the isolation rules, and products/architecture.md for facade and contract design. - Code a single product owns belongs under
products/<product>/— backend, frontend, scripts, CLIs, services, packages, MCP tools, skills.[review]Reserve top-leveltools/,services/,packages/,cli/andhog/for cross-product things.product:lintonly scansproducts/, so a single-product feature parked in a top-level directory is invisible to it.
Tenancy and scoping
- Every tenant-data model must have
team_id, as a FK toposthog.Teamor a plainBigIntegerFieldfor multi-DB products.[lint: idor-lookup-without-team, check-idor-model-coverage.py]This is the primary tenant isolation boundary. New models inheritTeamScopedRootMixin(main DB) orProductTeamModel(separate DB) so they start fail-closed — see posthog/models/scoping/README.md. - Classifying a model as unscoped is a review decision, not a checked one.
[review]A model withoutteam_idmust be org-scoped, user-scoped, or instance-global, never silently unscoped.check-idor-model-coverage.pyonly warns when a name lands inNEEDS_TEAM_ID, and passes silently forLEGITIMATELY_UNSCOPED, so a wrongly exempted tenant model reaches master unless a reader catches it. - Reading a fail-closed model outside request context — Temporal activities, Celery tasks, management commands — uses
Model.objects.for_team(team_id).[review]NotModel.all_teams.filter(team_id=...)and notobjects.unscoped().filter(...); those are for genuinely cross-team access and Django internals. In serializers the team comes fromself.context["get_team"](). Caveat:for_team(...).get_or_create(...)and.create(...)still needteam_idpassed explicitly, because a queryset filter does not propagate into row creation. - Do not add domain-specific fields to the
Teammodel.[review]Use a Team Extension model — see posthog/models/team/README.md for the pattern and helpers.
Person and group data
- All person/group access goes through the personhog client.
[review]Never query these via the Django ORM or raw SQL:posthog_person,posthog_persondistinctid,posthog_cohortpeople,posthog_group,posthog_grouptypemapping, and the override tables (posthog_personoverride,posthog_pendingpersonoverride,posthog_flatpersonoverride,posthog_featureflaghashkeyoverride,posthog_personlessdistinctid,posthog_personoverridemapping). Use the routed helpers inposthog/models/person/util.pyandposthog/models/group_type_mapping.py. New access follows the same_personhog_routed()pattern: apersonhog_fnusingget_personhog_client(), plus anorm_fnfallback. See posthog/personhog_client/README.md. - Personhog answers identity questions only.
[review]Use it for resolving distinct IDs, point lookups by person id or UUID, and lifecycle writes. Person properties, list hydration, and search come from ClickHouse (HogQL overpersons,ActorsQueryRunner). Avoid readingpropertiesfrom personhog — the API will stop surfacing it. Single-person lookups that need properties are exempt only while no ClickHouse primitive covers them, never in bulk. See docs/internal/person-data-access.md.
Transactions and locking
- There is no implicit per-request transaction — PostHog does not enable
ATOMIC_REQUESTS.[review]Every operation runs in autocommit unless wrapped. Putwith transaction.atomic():around the specific writes that must succeed or fail together, never around a whole view method. Keep irreversible side effects out of the block: an email sent or an API called before a rollback has already happened. Schedule them after the commit, or dispatch Celery tasks withtransaction.on_commit(). - Do not use
TeamorOrganizationrows as mutexes.[lint: hot-parent-row-select-for-update]PostgreSQL takesKEY SHARElocks on parent rows for foreign-key checks, andFOR UPDATEconflicts with them, so an unrelated child-row write can wait behind a transaction holding a hot parent row. Lock the product'sTeam<Product>Configextension row instead, reached throughget_or_create_team_extensionso the row exists first. For a per-team count limit or number allocation, use a unique constraint, a conditional update, or a dedicated allocation row. Otherwise lock the quiet child row, or take a transaction-scoped advisory lock. LockTeamorOrganizationonly when the transaction updates or deletes that row, and keep it short — no network calls, no input-sized loops. Each exception needs a shortnosemgrepjustification.
API schemas and generated types
- API views declare request/response schemas.
[review]Prefer@validated_requestfromposthog.api.mixins, or@extend_schemafrom drf-spectacular. A plainViewSetmethod that validates manually needs@extend_schema(request=YourSerializer); without it drf-spectacular cannot discover the request body and generated code gets an empty schema. Serializer fields needhelp_text. These flow into both frontend types and MCP tool schemas. - Django serializers are the source of truth for frontend API types.
[lint: build:openapi CI gate, prefer-codegen-api, test_generated_files_are_registered.py]hogli build:openapigenerates TypeScript via drf-spectacular and Orval intofrontend/src/generated/core/andproducts/{product}/frontend/generated/. Never hand-editapi.schemas.ts,api.tsorapi.zod.ts— change the serializer and regenerate. A value list the frontend needs comes from a typed serializer field, not from a side script; other checked-in projections are entries intools/hogli-commands/hogli_commands/projections.py. Type system guide has the full pipeline. - MCP tools and MCP UI apps are generated from the same OpenAPI spec.
[review]See implementing MCP tools covers the YAML config and codegen. MCP UI apps live inproducts/*/mcp/tools.yamlunderui_apps— see services/mcp/CONTRIBUTING.md or/implementing-mcp-ui-apps.
Async, storage and outbound calls
- Do not use
posthoganalytics.capture()in a Celery task — events are silently lost.[review]Useph_scoped_capturefromposthog.ph_client; its docstring explains why. - Temporal activity payloads cap at ~2 MiB — pass large data by reference.
[review]Activity inputs and outputs cross a gRPC boundary the server rejects above that (blobSizeLimitError). As a field-level rule: if a field could exceed ~256 KB serialized (query results, exported file contents, LLM context, rendered HTML, image bytes, unboundedlist[dict[str, Any]]), write it to Postgres or object storage from inside the activity and return only the row ID or S3 key. The workflow already has any ID created earlier in the run. Shuttling large data through the workflow producesPayloadSizeError(TMPRL1103) as soon as the data crosses the limit. - A Python
requestscall to GitHub or Slack undercommon/,ee/,posthog/orproducts/goes throughposthog/egress/.[lint: github-api-calls-go-through-egress, slack-api-calls-go-through-egress]Route it through the gated, recorded transport. - Every other call to those hosts goes through
posthog/egress/too.[lint: github-api-calls-go-through-egress-wide, slack-api-calls-go-through-egress-wide]The wide rules catch a URL bound to a variable or constant,requests.Session,httpx,aiohttp,urllib.request, and an aliased Slack SDK client. Another language, another vendor SDK, or a caller undertools/still passes CI, so a reader is the only control there. - Any other third-party API that needs rate-limiting or egress telemetry belongs there too.
[review]Add a<domain>/incarnation (GitHub is the reference). No semgrep rule covers a new domain, so a raw client for one reaches master unless a reader catches it./routing-outbound-api-callsdecides the route and names the reference domain to copy. - Object storage is SeaweedFS — do not add new MinIO dependencies.
[review]Both S3-compatible stores are SeaweedFS:objectstorage(:19000,OBJECT_STORAGE_*) for general storage,seaweedfs(:8333,SESSION_RECORDING_V2_S3_*) for session replay v2. MinIO survives only as one-off salvage tooling:bin/migrate-storage-hobbystarts a temporary container to read an old hobby MinIO volume. Do not add compose services, scripts, tests or docs that stand up aminio/miniocontainer. Talk to storage through the existing config and a standard S3 client, never a hardcoded endpoint. Noteobjectstorageregisters credentials at runtime and returnsInvalidAccessKeyIduntil that finishes, so wait for its readiness sentinel rather than the container start. - A new DNS-resolution or outbound-host entry point calls the shared out-of-band domain check.
[lint: test_oob_denylist_coverage.py]Every host guard here is IP-based, and an out-of-band interaction domain resolves to an ordinary public IP, so a resolver that skips the check restores the gap in silence. The list and the edit procedure live inposthog/security/crosslang/.
Configuration and secrets
- A key in
posthog/settings/dynamic_settings.pyexists only because operators must change its value live, without a deploy.[review]These instance settings are Postgres rows that staff edit at runtime, and a stored row overrides the environment variable. Kill switches and tuning knobs for incidents qualify. Secrets and static config are environment variables read inposthog/settings/, with values from the deployment secret store and charts. Never store a secret as an instance setting, because the database keeps it as plain text. A per-team rollout or a team allowlist is a feature flag.
Django admin
- A new
ForeignKey/OneToOneFieldon an admin-exposed model needs explicit widget config.[review]List the field inautocomplete_fields,raw_id_fields, orreadonly_fieldson every admin class that renders the model, including inlines attached to a related admin. Otherwise the default<select>loads the entire target table per row on each change-page render. Declare it on a shared base inline so per-parent variants inherit it.
LLM gateway
- App code sends inference through the Go AI gateway.
[review]A provider API key is never the client. - A change to gateway behavior lands in
PostHog/ai-gateway.[review]Read that repo when the change is the gateway itself. This monorepo only calls the gateway. - A monorepo caller builds its client with a helper in
posthog/llm/gateway_client.py.[review]Usebuild_openai_client,build_async_openai_client,build_anthropic_client,build_async_anthropic_client,build_gemini_client,build_ai_gateway_openai_client, orbuild_ai_gateway_anthropic_client. Those helpers readAI_GATEWAY_URLandAI_GATEWAY_API_KEY. Readproducts/tasks/backend/logic/services/title_generator.pyfor a real call. services/llm-gatewayis under an unofficial code freeze.[review]If a task asks you to change it, tell the user about the freeze in your reply. A change needs a documented parity blocker for an active caller and stays limited to that caller. Readservices/llm-gateway/PARITY.mdbefore the change. Read/auditing-llm-gateway-paritywhen the gateway contract changes. Its Postgres role reads only allowlisted tables. A new table read needs the SELECT grant in posthog-cloud-infra for every environment first, then a declaration inrequired_tables.py. The readiness probe checks every declared grant on every probe, so a missing grant holds a rollout instead of serving 500s.