Overview

Relevant source files

Trigger.dev is a background jobs framework for executing long-running tasks in a distributed system. The codebase consists of:

Control Plane: A Remix application (apps/webapp) that provides the API and dashboard for managing deployments, runs, and task definitions
Execution Engine: The RunEngine class (internal-packages/run-engine/src/engine/index.ts) orchestrates task lifecycle, queueing, and state transitions
Worker Runtime: Containerized worker processes execute tasks using the TaskExecutor class (packages/core/src/v3/workers/taskExecutor.ts)
Developer Tools: The CLI (packages/cli-v3) and SDK (packages/trigger-sdk) provide task definition, deployment, and triggering capabilities

The system uses PostgreSQL for transactional data, ClickHouse for analytics, nine separate Redis clusters for specialized operations (rate limiting, caching, queuing, locking, etc.), and S3-compatible storage for artifacts. Workers are orchestrated using Kubernetes (apps/kubernetes-provider) or Docker (apps/docker-provider) providers.

System Purpose and Core Components

Trigger.dev operates as a distributed task orchestration platform with the following primary components:

Control Plane: The apps/webapp application serves as the central coordination hub, providing a Remix-based UI/API server that manages deployments, task definitions, and run orchestration.

Execution Layer: The Run Engine (internal-packages/run-engine) manages task lifecycle, queueing, and state transitions. Workers execute tasks in isolated containers managed by Supervisor applications.

Developer Interface: The CLI (packages/cli-v3) and SDK (packages/trigger-sdk) provide the development experience for defining tasks, deploying applications, and triggering runs.

Infrastructure: PostgreSQL stores persistent data, ClickHouse stores analytics, multiple Redis clusters handle rate limiting, caching, real-time streams, pub/sub, and run engine operations, and S3-compatible object storage manages artifacts.

Sources: pnpm-lock.yaml1-100 package.json1-113 apps/webapp/package.json1-290 packages/trigger-sdk/package.json1-131 packages/cli-v3/package.json1-162

High-Level Architecture

System Component Topology with Code Entity Mapping

The diagram maps system components to code entities. The CLI binary trigger is defined in packages/cli-v3/package.json32-34 The SDK's task() function is exported from packages/trigger-sdk/src/v3/index.ts The Remix server in apps/webapp/server.ts handles API routes that delegate to the RunEngine class (internal-packages/run-engine/src/engine/index.ts). Task execution occurs in the TaskExecutor class (packages/core/src/v3/workers/taskExecutor.ts).

Sources: apps/webapp/server.ts packages/cli-v3/package.json32-34 packages/trigger-sdk/package.json24-28 internal-packages/run-engine apps/supervisor apps/coordinator packages/core/package.json509-520

Monorepo Package Organization

The codebase is organized as a pnpm workspace monorepo with three distinct package layers:

Package Dependency Graph with Key Classes

The monorepo has three layers:

Apps (apps/*) are deployable services that import internal packages
Internal Packages (internal-packages/*) provide infrastructure not published to npm
Public Packages (packages/*) are published to npm for developer consumption

Sources: package.json1-113 pnpm-lock.yaml38-100 turbo.json1-91

Key Package Descriptions

Package	Location	Purpose
`@trigger.dev/core`	packages/core	Shared schemas, utilities, and OpenTelemetry integration used across all packages
`@trigger.dev/sdk`	packages/trigger-sdk	Public API for defining tasks using `task()`, `scheduled.task()`, and triggering runs
`trigger.dev`	packages/cli-v3	Command-line interface providing `init`, `dev`, `deploy`, `whoami`, and other commands
`@trigger.dev/build`	packages/build	Build extensions like `prismaExtension()`, `puppeteerExtension()`, `syncEnvVars()`
`@trigger.dev/database`	internal-packages/database	Prisma client and schema for PostgreSQL database access
`@internal/run-engine`	internal-packages/run-engine	Core orchestration logic including `RunEngine`, queue management, and checkpoint systems

Sources: packages/core/package.json1-50 packages/trigger-sdk/package.json1-50 packages/cli-v3/package.json1-50 packages/build/package.json1-50 internal-packages/database internal-packages/run-engine

Infrastructure Layer

The platform relies on multiple specialized data stores and services:

Infrastructure Components and Environment Variables

The system uses nine Redis clusters configured via *_REDIS_HOST environment variables. Each supports optional read replicas (*_REDIS_READER_HOST), TLS configuration (*_REDIS_TLS_DISABLED), and cluster mode (*_REDIS_CLUSTER_MODE_ENABLED). PostgreSQL connections use PrismaClient (internal-packages/database) with pooling controlled by DATABASE_CONNECTION_LIMIT and DATABASE_POOL_TIMEOUT. Container orchestration providers are implemented in apps/docker-provider and apps/kubernetes-provider

Sources: apps/webapp/app/env.server.ts116-260 apps/webapp/app/env.server.ts440-472 docker/Dockerfile1-95 apps/webapp/package.json28-60 internal-packages/database internal-packages/redis

Database Architecture

The system uses two database engines:

PostgreSQL (internal-packages/database/prisma/schema.prisma): Stores TaskRun, TaskRunExecution, WorkerDeployment, Organization, Project, RuntimeEnvironment, and other core entities. Connections are managed through PrismaClient and PrismaReplicaClient with connection pooling.

ClickHouse (internal-packages/clickhouse): Stores analytics events, OTEL traces, and usage metrics. Migrations are managed using Goose (docker/scripts/entrypoint.sh13-35).

Sources: apps/webapp/app/env.server.ts52-67 internal-packages/database internal-packages/clickhouse docker/scripts/entrypoint.sh1-48

Redis Cluster Configuration

Nine separate Redis clusters handle different concerns:

Cluster	Environment Variable Prefix	Package/Purpose
Rate Limit Redis	`RATE_LIMIT_REDIS_*`	API rate limiting via `@upstash/ratelimit`
Cache Redis	`CACHE_REDIS_*`	`@internal/cache` using `@unkey/cache`
Realtime Streams Redis	`REALTIME_STREAMS_REDIS_*`	Run event streams with `REALTIME_STREAM_MAX_LENGTH` and `REALTIME_STREAM_TTL`
PubSub Redis	`PUBSUB_REDIS_*`	`@socket.io/redis-adapter` for apps/coordinator scaling
Alert Rate Limiter Redis	`ALERT_RATE_LIMITER_REDIS_*`	Alert throttling with `ALERT_RATE_LIMITER_EMISSION_INTERVAL`
Run Engine Worker Redis	Configured in RunEngine	Job coordination via `@internal/run-engine`
Run Engine Queue Redis	Configured in RunEngine	Task queue management with `RUN_ENGINE_RUN_QUEUE_SHARD_COUNT`
Run Engine Lock Redis	Configured in RunEngine	Distributed locks using `redlock`
Run Engine Presence Redis	Configured in RunEngine	Worker registration and heartbeats

Each cluster supports optional read replica configuration with *_READER_HOST and *_READER_PORT variables, TLS configuration via *_TLS_DISABLED, and cluster mode via *_CLUSTER_MODE_ENABLED. The Run Engine clusters use dedicated instances to isolate task execution from web traffic.

Sources: apps/webapp/app/env.server.ts116-260 apps/webapp/app/env.server.ts440-472 internal-packages/redis internal-packages/cache internal-packages/run-engine pnpm-lock.yaml28-37

Developer Workflow

The typical development and deployment flow:

Developer Interaction Flow

Development mode runs a local server that connects via WebSocket for hot module reloading. Production deployment builds a Docker image and pushes to a registry. The RunEngine class dequeues runs and coordinates worker execution.

Sources: packages/cli-v3/package.json32-34 packages/trigger-sdk/package.json24-28 apps/webapp/app/env.server.ts81-82

Build and Deployment System

The deployment process transforms developer code into containerized workers:

Build and Deployment Pipeline

The CLI supports three build modes via command-line flags. Build extensions (packages/build/src/extensions) modify Docker images to include dependencies. The WorkerDeployment table tracks deployment state transitions.

Sources: packages/cli-v3/package.json83-148 packages/build/package.json1-50 apps/webapp/app/env.server.ts288-331 docker/Dockerfile1-95

Build Extensions

Build extensions enable customization of the worker container image:

prismaExtension(): Generates Prisma client with three modes (legacy, engine-only, modern)
puppeteerExtension(): Installs Chromium and Puppeteer dependencies
playwrightExtension(): Installs Playwright browsers
syncEnvVars(): Syncs environment variables to Trigger.dev platform
aptGet(), ffmpegExtension(): Install system packages

Extensions are defined in trigger.config.ts and processed during the build phase.

Sources: packages/build/package.json1-216 packages/build/CHANGELOG.md1-350

Observability and Telemetry

The platform integrates OpenTelemetry for comprehensive observability:

Observability Architecture

OpenTelemetry instrumentation exports traces, logs, and metrics to configurable endpoints. The internal-packages/tracing package provides structured logging utilities.

Sources: apps/webapp/package.json65-83 apps/webapp/app/env.server.ts405-421 internal-packages/tracing packages/core/package.json168-183

Real-time Communication

The platform provides real-time updates through multiple channels:

Server-Sent Events (SSE): The RunStreamPresenter class streams run execution events to clients. React hooks like useRealtimeRun() consume these streams.

Socket.IO: The apps/coordinator application provides WebSocket-based bidirectional communication using Socket.IO with Redis adapter for horizontal scaling.

Electric SQL: The @electric-sql/react package provides real-time database synchronization for PostgreSQL data, enabling live updates of run status without polling.

Sources: apps/webapp/package.json52-54 apps/coordinator packages/react-hooks/package.json1-76

Configuration Management

System configuration is managed through multiple mechanisms:

Environment Variables: The apps/webapp/app/env.server.ts1-600 file defines a comprehensive Zod schema validating 200+ environment variables controlling database connections, Redis clusters, deployment registries, OTEL configuration, and feature flags.

Trigger Config: Developers define trigger.config.ts files specifying build extensions, runtime configuration, and telemetry settings using defineConfig() from @trigger.dev/sdk/v3.

Deployment Configuration: Registry configuration, image tags, and platform settings are managed through environment variables with prefixes like DEPLOY_REGISTRY_* and V4_DEPLOY_REGISTRY_*.

Sources: apps/webapp/app/env.server.ts1-600 packages/trigger-sdk/CHANGELOG.md1-350