isolating-product-facade-contracts

Original：🇺🇸 English

Translated

Plan and execute incremental product isolation migrations to a facade plus contract layer in PostHog, following the Visual review architecture. Use when a product still exposes internals (models/logic/views) across boundaries and needs a safe, multi-PR migration toward contracts.py + facade/api.py + presentation separation.

2installs

Sourceposthog/posthog

Added on2026-03-21

NPX Install

npx skill4agent add posthog/posthog isolating-product-facade-contracts

SKILL.md Content

View Translation Comparison →

Isolating a product with facade and contracts

Use this skill to migrate an existing product to the isolated architecture used by Visual review. Keep migrations incremental, with narrow PRs that avoid broad breakage.

Prerequisite: the product must already live under

products/<name>/

. This skill does not cover moving code out of

posthog/

,

ee/

, or other shared directories — do that first.

Core docs to load first

Read these before changing code:

products/architecture.md
products/README.md
docs/internal/monorepo-layout.md
posthog/models/team/README.md (team extension model rule)
docs/published/handbook/engineering/type-system.md (serializer/OpenAPI type flow)
docs/published/handbook/engineering/ai/implementing-mcp-tools.md (schema quality and team isolation expectations)

Use Visual review as the concrete reference implementation:

products/visual_review/backend/facade/contracts.py
products/visual_review/backend/facade/api.py
products/visual_review/backend/presentation/views.py
products/visual_review/backend/presentation/serializers.py
products/visual_review/backend/logic.py
products/visual_review/backend/tests/test_api.py
products/visual_review/backend/tests/test_presentation.py

For detailed sequencing, load references/phased-migration-plan.md.

Guardrails

Keep facades thin; put business rules in
```
logic.py
```
.
Never return ORM models across product boundaries.
Keep contracts pure (no Django/DRF imports).
Filter by
```
team_id
```
in querysets.
Do not add product-specific fields to
```
Team
```
; use a Team Extension model.
Add request/response schema annotations on viewset endpoints (
```
@validated_request
```
or
```
@extend_schema
```
).
Regenerate OpenAPI/types (
```
hogli build:openapi
```
) when serializer/view changes affect API schema.

Required migration workflow

Build an import map for the target product.
- Find cross-product imports into target internals (
```
models
```
  ,
```
logic
```
  ,
```
presentation
```
  , non-facade modules).
- Classify each usage by capability (read/list, detail/read, create/update/delete, async/task, webhook/event).
Define the minimal contract surface.
- Start from currently consumed fields only.
- Create frozen dataclasses in
```
backend/facade/contracts.py
```
  .
Introduce a thin facade in
```
backend/facade/api.py
```
.
- Map ORM instances to contracts with explicit mapper functions.
- Keep method names capability-oriented and stable.
Migrate callers in small batches.
- Replace one caller cluster at a time (single endpoint, single task, or single service area).
- Keep compatibility shims only when needed; remove promptly.
Move presentation to consume the facade.
- Serializers convert JSON <-> contracts.
- Views call facade methods only.
Enforce boundaries and verify.
- Update
```
tach.toml
```
  interfaces/dependencies when applicable.
- Run focused tests for changed files, then product-level backend tests.

PR slicing strategy

Default to several PRs instead of one big migration:

PR 1: Add contracts + facade methods without changing external callers.
PR 2-N: Migrate caller clusters one-by-one to the facade.
Final PR: Remove deprecated internal import paths, tighten tach boundaries, and clean dead adapters.

If a product has many endpoints, migrate in this order:

Read-only list/detail APIs (lowest risk)
Internal service-to-service call sites
Write paths (create/update/delete)
Background tasks / async entrypoints
Remaining edge endpoints and cleanup

Done criteria

Treat migration as complete only when:

Cross-product imports use
```
backend/facade
```
only.
Facade returns/accepts contracts, not ORM.
Presentation layer no longer encodes business logic.
Tests cover facade and presentation boundaries.
Turbo/tach config reflects intended product isolation.