Thanks to visit codestin.com
Credit goes to deepwiki.com

Index your code with Devin
DeepWiki

triggerdotdev/trigger.dev

Menu

Application Architecture

Relevant source files

Purpose and Scope

This document details the architecture of the Trigger.dev web application, focusing on the Express + Remix server setup, middleware chain, route handling, server-side rendering, and the integration of real-time communication layers. This page covers the infrastructure and request flow of the web application itself.

For information about real-time updates and Server-Sent Events, see Realtime Updates and SSE. For Socket.IO and WebSocket specifics, see Socket.IO and WebSocket Communication. For authentication details, see Authentication and Authorization. For UI components and routing, see Navigation and Routing.

Technology Stack Overview

The web application is built on the following core technologies:

ComponentTechnologyVersion/Details
Web FrameworkRemixv2.1.0
HTTP ServerExpressv4.20.0
RuntimeNode.js≥18.19.0 or ≥20.6.0
View LayerReactv18.2.0
StylingTailwindCSSv3.4.1
Real-time (Socket.IO)socket.iov4.7.4
Real-time (WebSocket)wsv8.11.0
ORMPrismav6.14.0
Compressioncompressionv1.7.4
Loggingmorganv1.10.0

Sources: apps/webapp/package.json1-286

Server Architecture

Express Server Setup

The web application runs on an Express HTTP server that wraps the Remix application handler. The server is configured in apps/webapp/server.ts1-269 and provides the foundation for all HTTP and WebSocket traffic.

Server Creation and Port Binding:

Sources: apps/webapp/server.ts91-206

Cluster Mode Support

The server supports horizontal scaling via Node.js cluster mode for improved performance under load.

Cluster Configuration:

Worker Management:

Sources: apps/webapp/server.ts18-89

HTTP Server Configuration

Security Configuration:

Static Asset Configuration:

Request ID Generation:

Sources: apps/webapp/server.ts93-143 apps/webapp/app/root.tsx23-28

Remix Framework Integration

Entry Points

The application has separate entry points for server-side and client-side rendering:

Server Entry (entry.server.tsx):

Context Providers:

Client Entry (entry.client.tsx):

Sources: apps/webapp/app/entry.server.tsx1-258 apps/webapp/app/entry.client.tsx1-16

Root Route Configuration

The root route (root.tsx) establishes the application shell and global configuration:

Root Loader:

Revalidation Strategy:

Meta Tags:

Error Boundary:

Sources: apps/webapp/app/root.tsx1-133

Request Handling Flow

Remix Request Handler:

Conditional Dashboard Access:

Sources: apps/webapp/server.ts113-185

Middleware Chain

The middleware chain processes requests in the following order:

Middleware Components

MiddlewarePurposeConfiguration
compressionCompress HTTP responsesDisabled via DISABLE_COMPRESSION=1
express.staticServe static assets/build (1y), /public (1h)
morganHTTP request loggingFormat: 'tiny'
Security HeadersSet security-related headersHSTS, X-Robots-Tag, etc.
Trailing SlashRedirect trailing slashes301 permanent redirect
Request IDGenerate unique request identifierVia nanoid(), stored in async context
apiRateLimiterRate limit API requestsFrom build.entry.module.apiRateLimiter
engineRateLimiterRate limit engine requestsFrom build.entry.module.engineRateLimiter
createRequestHandlerRemix route handlerMain application logic

Middleware Imports:

Sources: apps/webapp/server.ts93-179

Real-time Communication Architecture

The application supports two parallel real-time communication systems: Socket.IO and raw WebSockets.

WebSocket Upgrade Flow

The server handles WebSocket upgrades via a custom upgrade listener:

  1. Upgrade Event Listener apps/webapp/server.ts228-263

  2. Path-Based Routing apps/webapp/server.ts235-256

  3. Socket.IO Upgrade apps/webapp/server.ts242

  4. WebSocket Upgrade apps/webapp/server.ts260-262

Module Imports:

Sources: apps/webapp/server.ts225-263 apps/webapp/app/entry.server.tsx234-235

Service Architecture

The web application follows a layered architecture pattern separating concerns into distinct layers:

Presenters

Presenters provide a data transformation and aggregation layer between routes and raw data access. They:

  • Fetch data from multiple sources (Prisma, ClickHouse)
  • Transform database models into view models
  • Apply business logic for presentation
  • Cache computed results where appropriate

Example Presenters:

  • RunPresenter - Transforms TaskRun data for display
  • TaskDetailsPresenter - Aggregates task execution details
  • RunStreamPresenter - Prepares real-time run streams
  • SelectBestEnvironmentPresenter - Determines optimal environment selection

For more details, see Run Monitoring and Visualization and Realtime Updates and SSE.

Services

Services contain business logic and orchestrate complex operations. They:

  • Execute transactional operations
  • Coordinate multiple database operations
  • Implement domain business rules
  • Interface with external APIs

Key Services:

Data Access

The data access layer uses specialized clients for each data store:

  • Prisma Client - ORM for PostgreSQL transactional data
  • ClickHouse Client - Direct queries for event data
  • Redis Cache - @unkey/cache for distributed caching

For database schema details, see sections 6.1 through 6.5.

Sources: Inferred from Diagram 5 and architectural patterns throughout the codebase

Environment Configuration

The application uses an extensive environment configuration system defined in apps/webapp/app/env.server.ts1-627

Configuration Categories

Key Configuration Groups

Database Configuration:

Redis Configuration: Each Redis use case can have separate configuration:

Deployment Configuration:

OpenTelemetry Configuration:

Rate Limiting Configuration:

Run Engine Configuration:

Sources: apps/webapp/app/env.server.ts1-627

Build and Deployment

Docker Build Pipeline

The application uses a multi-stage Docker build for optimal image size and layer caching:

Build Stages:

  1. Pruner docker/Dockerfile6-12

    • Uses turbo prune to extract webapp dependencies
    • Removes all node_modules to force clean install

  2. Base docker/Dockerfile15-21

    • Installs system dependencies (openssl, dumb-init)
    • Copies pruned package.json files and lockfile

  3. Dev Dependencies docker/Dockerfile24-29

    • Installs all dependencies including devDependencies
    • Uses pnpm cache mount for faster rebuilds

  4. Production Dependencies docker/Dockerfile32-41

    • Installs only production dependencies
    • Generates Prisma client

  5. Builder docker/Dockerfile44-74

    • Copies full source code
    • Runs pnpm run generate and pnpm run build --filter=webapp...
    • Uploads source maps to Sentry (if configured)

  6. Runner docker/Dockerfile77-114

    • Minimal production image
    • Copies built artifacts and production dependencies
    • Installs goose binary for ClickHouse migrations
    • Runs as non-root node user

Build Arguments:

Sources: docker/Dockerfile1-115

Deployment Entrypoint

The container entrypoint handles initialization and startup:

Initialization Steps:

  1. Database Availability Check docker/scripts/entrypoint.sh4-6

    • Waits for DATABASE_HOST to be reachable if set

  2. Prisma Migrations docker/scripts/entrypoint.sh9-11

    • Runs pnpm --filter @trigger.dev/database db:migrate:deploy

  3. ClickHouse Migrations docker/scripts/entrypoint.sh13-35

    • Runs goose migrations if CLICKHOUSE_URL is set
    • Ensures secure=true parameter is in connection string

  4. Prisma Client Setup docker/scripts/entrypoint.sh38-39

    • Copies schema.prisma and native bindings to webapp directory

  5. Node.js Memory Configuration docker/scripts/entrypoint.sh44-50

    • Sets --max-old-space-size from NODE_MAX_OLD_SPACE_SIZE (default: 8192 MB)

  6. Application Start docker/scripts/entrypoint.sh50

    • Uses dumb-init as PID 1 for proper signal handling
    • Configures NODE_PATH for pnpm resolution
    • Executes build/server.js

Sources: docker/scripts/entrypoint.sh1-51

Bootstrap and Initialization

The application performs several initialization tasks on startup via apps/webapp/app/entry.server.tsx174-258:

Initialization Sequence

Sentry Integration:

Worker Initialization:

Bootstrap Function:

Run Engine Event Bus:

Monitoring:

Remote Builds Logging:

Uncaught Exception Handling:

Sources: apps/webapp/app/entry.server.tsx174-258

Summary

The Trigger.dev web application architecture combines Remix's server-side rendering capabilities with Express's middleware ecosystem to create a robust, scalable platform. Key architectural decisions include:

  • Cluster mode support for horizontal scaling
  • Dual real-time systems (Socket.IO + WebSockets) for different use cases
  • Layered service architecture separating presentation, business logic, and data access
  • Comprehensive environment configuration for flexible deployment
  • Multi-stage Docker builds with optimized layer caching
  • Graceful initialization with migration handling and monitoring setup

The architecture prioritizes observability, security, and performance while maintaining clear separation of concerns and flexibility for different deployment scenarios.