Skip to content

: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.

14.8 KB
Raw Blame
# Intent-based developer environment configuration
#
# This file defines the domain model for developer environments:
# - Intent: What the developer is working on (products like error_tracking, session_replay)
# - Capabilities: Stable abstractions (event_ingestion, replay_storage, etc.)
#
# Process definitions (which processes provide which capability) are in bin/mprocs.yaml.
# Each process declares its capability via the `capability` field.

version: '1.0'

# Capabilities are stable abstractions over processes
# - requires: dependencies resolved transitively
# - docker_profiles: docker compose profiles to activate (see docker-compose.profiles.yml)
# - Processes are NOT listed here - they declare their capability in mprocs.yaml
capabilities:
    core_infra:
        description: 'Essential infrastructure (docker, postgres, clickhouse)'
        docker_profiles: []

    event_ingestion:
        description: 'Kafka-based event pipeline for event capture'
        # The combined-mode ingestion server's AI consumer reads persons through PersonHog
        requires: [core_infra, personhog]
        docker_profiles: []

    property_definitions:
        description: 'Track and define event/person properties'
        requires: [event_ingestion]
        docker_profiles: []

    property_values:
        description: 'Aggregate distinct property values for autocomplete'
        requires: [event_ingestion]
        docker_profiles: []

    replay_storage:
        description: 'Session replay blob storage and capture'
        requires: [event_ingestion]
        docker_profiles: [replay]

    browser_rendering:
        description: 'Browserless container for heatmap screenshots and image exports'
        requires: [core_infra]
        docker_profiles: [browserless]

    error_symbolication:
        description: 'Error stack trace symbolication service'
        requires: [event_ingestion]
        docker_profiles: []

    error_notifications:
        description: 'Error tracking ingestion notifications consumer'
        requires: [event_ingestion]
        docker_profiles: []

    flag_evaluation:
        description: 'Fast feature flag evaluation service'
        requires: [core_infra]
        docker_profiles: []

    coordination:
        description: 'etcd-based coordination for PersonHog and Kafka partition assignment'
        requires: [core_infra]
        docker_profiles: [etcd]

    celery_workers:
        description: 'Celery background job processing'
        requires: [core_infra]
        docker_profiles: []

    celery_scheduler:
        description: 'Celery beat scheduler for periodic tasks'
        requires: [celery_workers]
        docker_profiles: []

    temporal_workflows:
        description: 'Temporal workflow orchestration'
        requires: [core_infra]
        docker_profiles: [temporal]

    recording_rasterizer:
        description: 'Temporal worker that records session replays to video'
        requires: [temporal_workflows]
        docker_profiles: []

    dagster_pipelines:
        description: 'Dagster data pipeline orchestration'
        requires: [core_infra]
        docker_profiles: []

    llm_gateway:
        description: 'LLM gateway for AI features'
        requires: [core_infra]
        docker_profiles: []

    agent_proxy:
        description: 'Agent proxy streaming service for live task-run streaming (Tasks product)'
        requires: [core_infra]
        docker_profiles: []

    embedding_service:
        description: 'Vector embedding worker for AI features'
        requires: [core_infra]
        docker_profiles: []

    opensearch_search:
        description: 'OpenSearch reverse index for LLM trace search'
        requires: [core_infra]
        docker_profiles: [opensearch]

    llm_analytics_sentiment:
        description: 'Sentiment classification model for AI observability (installs torch, optimum ~2GB)'
        requires: [temporal_workflows]
        docker_profiles: []
        uv_groups: [sentiment]

    livestream:
        description: 'Real-time event streaming'
        requires: [event_ingestion]
        docker_profiles: []

    cyclotron:
        description: 'Cyclotron job queue infrastructure (includes shadow for testing)'
        requires: [core_infra]
        docker_profiles: []

    ai_gateway:
        description: 'Local Go ai-gateway (sibling ~/Development/ai-gateway) - routes model calls'
        requires: [core_infra]
        docker_profiles: []

    # Node.js capability groups - control which consumers run to reduce event loop contention
    nodejs_cdp:
        description: 'Node.js CDP - destinations, webhooks, and realtime alerts'
        requires: [event_ingestion]
        docker_profiles: []

    nodejs_cdp_workflows:
        description: 'Node.js CDP + Workflows - full CDP with HogFlow workflow automation'
        requires: [event_ingestion]
        docker_profiles: []

    nodejs_realtime_cohorts:
        description: 'Node.js Realtime Cohorts - cohort membership persistence'
        requires: [event_ingestion]
        docker_profiles: []

    nodejs_session_replay:
        description: 'Node.js Session Replay - recording ingestion'
        requires: [event_ingestion]
        docker_profiles: [replay, dynamodb]

    nodejs_logs:
        description: 'Node.js Logs - log ingestion'
        requires: [event_ingestion]
        docker_profiles: [observability]

    nodejs_metrics:
        description: 'Node.js Metrics - metric ingestion'
        requires: [event_ingestion]
        docker_profiles: [observability]

    nodejs_traces:
        description: 'Node.js Traces - trace ingestion'
        requires: [event_ingestion]
        docker_profiles: [observability]

    logs_ingestion:
        description: 'OTEL logs and traces capture service'
        requires: [event_ingestion]
        docker_profiles: [observability]

    metrics_ingestion:
        description: 'OTEL and Prometheus remote-write metrics capture service'
        requires: [event_ingestion]
        docker_profiles: [observability]

    nodejs_feature_flags:
        description: 'Node.js Feature Flags - evaluation scheduler'
        requires: [flag_evaluation]
        docker_profiles: []

    nodejs_error_tracking:
        description: 'Node.js Error Tracking - exception event ingestion'
        requires: [event_ingestion]
        docker_profiles: []

    batch_imports:
        description: 'Batch data import worker'
        requires: [event_ingestion]
        docker_profiles: []

    warehouse_webhook_sink:
        description: 'Kafka → S3 parquet sink for data warehouse webhook sources'
        requires: [event_ingestion]
        docker_profiles: []

    personhog:
        description: 'PersonHog gRPC service (router + replica + leader) for person data access'
        requires: [core_infra, coordination]
        docker_profiles: []

    observability:
        description: 'OpenTelemetry tracing with Jaeger'
        requires: [core_infra]
        docker_profiles: [observability]

    dev_tools:
        description: 'Development debugging tools (Kafka UI, Flower, etc.)'
        requires: [core_infra]
        docker_profiles: [dev_tools]

    webhook_tester:
        description: 'Local HTTP sink for webhook steps and destinations (localhost:2080)'
        requires: [core_infra]
        docker_profiles: [webhook_tester]

    mcp_server:
        description: 'MCP server for AI assistant integration'
        requires: [core_infra]
        docker_profiles: []

    stripe_app:
        description: 'Stripe app for PostHog integration'
        requires: [core_infra]
        docker_profiles: []

    stripe_mock:
        description: 'Local Stripe mock API for data warehouse import testing'
        requires: []
        docker_profiles: []

    duckgres:
        description: 'Duckgres query server (DuckDB with Postgres wire protocol)'
        requires: [core_infra]
        docker_profiles: [duckgres]

    desktop_app:
        description: 'PostHog Desktop app (Electron) and its package watchers'
        requires: [core_infra]
        docker_profiles: []

# Intents map to products/features developers work on
intents:
    product_analytics:
        description: 'Core product analytics (insights, funnels, trends)'
        capabilities: [event_ingestion, property_definitions, property_values, celery_workers, nodejs_cdp]

    error_tracking:
        description: 'Track and analyze application errors'
        capabilities:
            [
                event_ingestion,
                error_symbolication,
                error_notifications,
                embedding_service,
                property_definitions,
                property_values,
                nodejs_cdp,
                nodejs_error_tracking,
            ]

    session_replay:
        description: 'Record and replay user sessions'
        capabilities:
            [
                event_ingestion,
                replay_storage,
                property_definitions,
                property_values,
                celery_workers,
                temporal_workflows,
                nodejs_session_replay,
                recording_rasterizer,
            ]

    feature_flags:
        description: 'Feature flag management and evaluation'
        capabilities: [flag_evaluation, coordination, celery_workers, celery_scheduler, nodejs_feature_flags]

    experiments:
        description: 'A/B testing and experimentation'
        capabilities:
            [
                event_ingestion,
                flag_evaluation,
                property_definitions,
                property_values,
                celery_workers,
                nodejs_feature_flags,
                nodejs_cdp,
                dagster_pipelines,
                temporal_workflows,
            ]

    llm_analytics:
        description: 'LLM/AI observability and analytics'
        capabilities:
            [
                event_ingestion,
                llm_gateway,
                embedding_service,
                property_definitions,
                property_values,
                temporal_workflows,
                llm_analytics_sentiment,
            ]

    mcp_analytics:
        description: 'MCP analytics intent clustering and session summarisation'
        capabilities:
            [event_ingestion, llm_gateway, embedding_service, property_definitions, property_values, temporal_workflows]

    web_analytics:
        description: 'Web analytics, traffic analysis, and heatmaps'
        capabilities:
            [event_ingestion, replay_storage, property_definitions, property_values, livestream, browser_rendering]

    surveys:
        description: 'User surveys and feedback collection'
        capabilities:
            [event_ingestion, property_definitions, property_values, celery_workers, celery_scheduler, nodejs_cdp]

    data_warehouse:
        description: 'Data warehouse queries and saved queries'
        capabilities:
            [
                event_ingestion,
                property_definitions,
                property_values,
                celery_workers,
                temporal_workflows,
                warehouse_webhook_sink,
            ]

    cohorts:
        description: 'User cohort management'
        capabilities:
            [
                event_ingestion,
                property_definitions,
                property_values,
                celery_workers,
                celery_scheduler,
                nodejs_realtime_cohorts,
            ]

    pipelines:
        description: 'Data pipeline transformations and destinations'
        capabilities:
            [
                event_ingestion,
                property_definitions,
                property_values,
                celery_workers,
                temporal_workflows,
                nodejs_cdp_workflows,
                cyclotron,
            ]

    ai_features:
        description: 'AI features'
        capabilities:
            [
                event_ingestion,
                llm_gateway,
                embedding_service,
                opensearch_search,
                property_definitions,
                property_values,
                temporal_workflows,
                agent_proxy,
            ]

    tasks:
        description: 'Tasks: agent task runs and orchestration'
        capabilities: [event_ingestion, llm_gateway, celery_workers, celery_scheduler, temporal_workflows, agent_proxy]

    logs:
        description: 'Log aggregation and viewing'
        capabilities:
            [event_ingestion, property_definitions, property_values, logs_ingestion, nodejs_logs, nodejs_traces]

    metrics:
        description: 'Metric ingestion and viewing'
        capabilities: [event_ingestion, property_definitions, property_values, metrics_ingestion, nodejs_metrics]

    workflows:
        description: 'Workflow automation and orchestration'
        capabilities:
            [
                event_ingestion,
                property_definitions,
                property_values,
                temporal_workflows,
                nodejs_cdp_workflows,
                cyclotron,
                webhook_tester,
            ]

    tracing:
        description: 'OpenTelemetry tracing with Jaeger UI'
        capabilities: [observability]

    debug_tools:
        description: 'Kafka UI, Flower (Celery), maildev, webhook tester'
        capabilities: [dev_tools]

    mcp:
        description: 'MCP server for AI assistant integration'
        capabilities: [mcp_server]

    stripe:
        description: 'Stripe app for PostHog integration'
        capabilities: [stripe_app]

    personhog:
        description: 'PersonHog gRPC service for person data access (replaces direct DB queries)'
        capabilities: [personhog]

    endpoints:
        description: 'Endpoints (the product)'
        capabilities:
            [event_ingestion, property_definitions, property_values, celery_workers, temporal_workflows, duckgres]

    revenue_analytics:
        description: 'Mock Stripe API with seed billing data for revenue analytics testing'
        capabilities:
            [event_ingestion, property_definitions, property_values, celery_workers, temporal_workflows, stripe_mock]

    dagster:
        description: 'Dagster for clickhouse maintenance, system workflows'
        capabilities: [dagster_pipelines]

    desktop:
        description: 'PostHog Desktop app (Electron) with local task runs'
        capabilities: [desktop_app, temporal_workflows, agent_proxy, llm_gateway]

# Always-required processes regardless of intent
# This is the core stack needed for any development
always_required:
    - backend
    - frontend
    - ngrok
    - typegen
    - docker-compose
    # Migrations (DBs created by postgres init scripts, run for everyone)
    - migrate-postgres
    - migrate-clickhouse
    - migrate-persons-db
    - migrate-behavioral-cohorts
    # Core services
    - celery-worker
    - celery-beat
    - nodejs
    - capture
    - feature-flags
    - hypercache-server
    - property-defs-rs
    - personhog-replica
    - personhog-router