Application Architecture

Relevant source files

• .cursor/rules/webapp.mdc
• .dockerignore
• apps/webapp/app/entry.client.tsx
• apps/webapp/app/entry.server.tsx
• apps/webapp/app/env.server.ts
• apps/webapp/app/root.tsx
• apps/webapp/app/routes/api.v1.projects.$projectRef.background-workers.$envSlug.$version.ts
• apps/webapp/app/utils/httpErrors.ts
• apps/webapp/app/utils/queryPerformanceMonitor.server.ts
• apps/webapp/package.json
• apps/webapp/server.ts
• apps/webapp/start.sh
• docker/Dockerfile
• docker/scripts/entrypoint.sh
• internal-packages/database/.gitignore
• internal-packages/database/package.json
• package.json
• patches/@[email protected]
• pnpm-lock.yaml
• turbo.json

This document describes the architecture of the Trigger.dev web application, which serves both the dashboard UI and API endpoints. The webapp is a Remix 2.1.0 application running on an Express server, built as a containerized service that can run standalone or in a clustered configuration.

For information about the navigation system and routing patterns, see Navigation and Routing. For details on real-time updates and SSE, see Realtime Updates and SSE. For Socket.IO and WebSocket communication, see Socket.IO and WebSocket Communication.

---

Technology Stack

The web application is built on the following core technologies:

Component	Technology	Version	Purpose
Framework	Remix	2.1.0	Server-side rendering, routing, data loading
HTTP Server	Express	4.20.0	HTTP server, middleware pipeline
Runtime	Node.js	≥18.19.0 or ≥20.6.0	JavaScript runtime
UI Library	React	18.2.0	Component rendering
Database ORM	Prisma	6.14.0	Database access via @trigger.dev/database
Build Tool	esbuild	0.15.10+	TypeScript compilation, bundling
Monorepo	pnpm + Turborepo	8.15.5 + 1.10.3	Package management, build orchestration
Container	Docker	Multi-stage	Production deployment

Sources: apps/webapp/package.json1-289 package.json1-95

---

Server Architecture

Express + Remix Integration

The web application combines Express as the HTTP server with Remix as the application framework. This integration is managed in apps/webapp/server.ts1-269 which:

1. Configures Express middleware
2. Sets up static asset serving
3. Integrates Socket.IO and WebSocket servers
4. Delegates dynamic requests to Remix request handler

Sources: apps/webapp/server.ts91-269

Server Startup Sequence

The server initialization follows this sequence:

1. Import Sentry - Load error tracking (apps/webapp/server.ts1)
2. Configure Express - Set up middleware (apps/webapp/server.ts91-107)
3. Load Build Artifacts - Require compiled Remix app (apps/webapp/server.ts114-115)
4. Extract Services - Get Socket.IO, WebSocket, rate limiters from build (apps/webapp/server.ts120-124)
5. Configure Middleware - Set up request pipeline (apps/webapp/server.ts126-186)
6. Start HTTP Server - Listen on configured port (apps/webapp/server.ts187-199)
7. Attach Real-time Services - Connect Socket.IO and WebSocket (apps/webapp/server.ts225-263)

Sources: apps/webapp/server.ts1-269

---

Request Handling Pipeline

Middleware Stack

Requests flow through the following middleware in order:

Middleware Configuration:

Middleware	Purpose	Configurable	File Reference
compression()	Gzip compression	DISABLE_COMPRESSION	server.ts93-95
Static assets	Serve /build and /public	Cache headers	server.ts101-105
morgan()	Request logging	Always enabled	server.ts107
Security headers	XSS, robots, HSTS	Based on hostname	server.ts126-143
Request ID	Unique ID per request	Always enabled	server.ts145-153
Route filtering	Restrict to /realtime	ALLOW_ONLY_REALTIME_API	server.ts156-167
API rate limiter	Public API throttling	See API Authentication	server.ts169
Engine rate limiter	Internal API throttling	Configuration in env	server.ts170
Remix handler	Application logic	N/A	server.ts172-179

Sources: apps/webapp/server.ts93-186

Request Context Tracking

Each request receives a unique request ID and HTTP context stored in async local storage:

This context is accessible throughout the request lifecycle via httpAsyncStorage. The context includes:

• requestId: Unique identifier (generated by nanoid())
• path: Request URL path
• host: Request hostname
• method: HTTP method

Sources: apps/webapp/server.ts145-153 apps/webapp/app/services/httpAsyncStorage.server.ts (referenced)

---

Clustering and Horizontal Scaling

The webapp supports optional clustering to utilize multiple CPU cores. When enabled, it runs in a primary-worker model.

Cluster Architecture

Cluster Configuration

Environment Variable	Default	Description
ENABLE_CLUSTER	"0"	Enable clustering mode
CLUSTER_WORKERS	CPU count	Number of worker processes
WEB_CONCURRENCY	CPU count	Alternative worker count variable
GRACEFUL_SHUTDOWN_TIMEOUT	30000 ms	Max time to wait for graceful shutdown

Cluster Behavior:

1. Worker Count Determination:

   • Uses CLUSTER_WORKERS or WEB_CONCURRENCY if set
   • Falls back to os.availableParallelism() (CPU count)

2. Primary Process Responsibilities:

   • Fork worker processes (server.ts23-27)
   • Handle signals and forward to workers (server.ts29-71)
   • Monitor worker exits and respawn if unintentional (server.ts78-88)
   • Set process title: "node webapp-server primary" (server.ts74)

3. Worker Process Responsibilities:

   • Run Express + Remix application
   • Handle HTTP requests
   • Set process title: "node webapp-worker-{id}" (server.ts109-111)

4. Graceful Shutdown:

   • Primary forwards SIGTERM/SIGINT to all workers
   • Waits for workers to exit cleanly (max timeout)
   • Primary exits once all workers have stopped

Sources: apps/webapp/server.ts15-90

---

Build and Deployment Pipeline

Multi-Stage Docker Build

The production build uses a multi-stage Dockerfile optimized for layer caching and minimal image size.

Build Stage Purposes:

Stage	Base Image	Purpose	Key Files
goose_builder	golang:1.23-alpine	Build Goose migration tool	ClickHouse migrations
pruner	Node	Use Turborepo to prune workspace	turbo prune --scope=webapp
base	Node	Set up base dependencies	.gitignore, package.json, lock file
dev-deps	base	Install dev dependencies	For building TypeScript
production-deps	base	Install production deps only	For runtime
builder	base + dev-deps	Build webapp, generate Prisma	Compiled assets
runner	base + production-deps	Final runtime image	Built artifacts only

Build Commands:

Sources: docker/Dockerfile1-116 apps/webapp/package.json7-11

Turborepo Build Pipeline

The monorepo uses Turborepo to orchestrate builds with dependency tracking:

Sources: turbo.json1-147 apps/webapp/package.json7-11

---

Environment Configuration System

Centralized Configuration with Zod

All environment variables are validated and typed using Zod schemas in apps/webapp/app/env.server.ts1-685 This provides:

• Type-safe access to environment variables
• Runtime validation on server startup
• Default values and transformations
• Clear documentation of required vs. optional variables

Configuration Pattern:

Environment Variable Categories

Category	Example Variables	Purpose
Core Application	NODE_ENV, APP_ORIGIN, LOGIN_ORIGIN	Basic app configuration
Database	DATABASE_URL, DIRECT_URL, DATABASE_READ_REPLICA_URL	PostgreSQL connections
Redis (Segmented)	REDIS_HOST, CACHE_REDIS_HOST, PUBSUB_REDIS_HOST	Different Redis instances
Authentication	SESSION_SECRET, MAGIC_LINK_SECRET, ENCRYPTION_KEY	Auth and encryption
External Services	RESEND_API_KEY, OPENAI_API_KEY, DEPOT_TOKEN	Third-party integrations
Deployment	DEPLOY_REGISTRY_HOST, DEPOT_ORG_ID	Docker registry config
Observability	INTERNAL_OTEL_TRACE_EXPORTER_URL, POSTHOG_PROJECT_KEY	Telemetry and analytics
Run Engine	RUN_ENGINE_WORKER_COUNT, RUN_ENGINE_TIMEOUT_EXECUTING	Task execution tuning
Rate Limiting	API_RATE_LIMIT_MAX, API_RATE_LIMIT_REFILL_RATE	API throttling
Feature Flags	MARQS_WORKER_ENABLED, V2_MARQS_ENABLED	Feature toggles

Redis Segmentation:

The system uses multiple logical Redis instances for different purposes:

• Primary Redis: REDIS_HOST, REDIS_PORT - Default instance
• Rate Limiting: RATE_LIMIT_REDIS_HOST - Token bucket rate limiting
• Caching: CACHE_REDIS_HOST - Application caching
• Real-time Streams: REALTIME_STREAMS_REDIS_HOST - SSE event streams
• Pub/Sub: PUBSUB_REDIS_HOST - Event bus communication
• Run Engine: RUN_ENGINE_WORKER_REDIS_HOST - Run engine coordination
• Marqs: MARQS_REDIS_HOST - Message queue system

Each Redis instance supports separate reader/writer hosts for read replica configurations.

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

---

Middleware Stack Details

Security Headers

Security headers are set on all responses:

Additional headers from root.tsx:

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

Compression

Gzip compression is enabled by default for all responses (unless DISABLE_COMPRESSION=1):

Sources: apps/webapp/server.ts93-95

Trailing Slash Handling

Trailing slashes are removed via 301 redirects:

Sources: apps/webapp/server.ts136-142

---

Real-time Communication Infrastructure

WebSocket Upgrade Handling

The server handles WebSocket upgrades for both Socket.IO and plain WebSocket connections:

Upgrade Logic:

Sources: apps/webapp/server.ts225-263

Socket.IO Integration

Socket.IO is attached to the HTTP server and configured with Redis adapter for multi-instance support:

1. Attachment: socketIo?.io.attach(server) (server.ts225)
2. Redis Adapter: Configured in separate module (see Socket.IO and WebSocket Communication)
3. Upgrade Prevention: Remove duplicate upgrade listeners (server.ts226)

Sources: apps/webapp/server.ts120-226 apps/webapp/app/v3/handleSocketIo.server.ts (referenced)

---

Static Asset Management

Asset Caching Strategy

The webapp uses different caching strategies for different asset types:

Path	Cache Duration	Immutable	Purpose
/build/*	1 year	Yes	Remix fingerprinted assets (CSS, JS)
/public/*	1 hour	No	Static files (favicon, images)

Configuration:

Remix automatically fingerprints assets during build, allowing aggressive caching with immutable flag. This means:

• CSS/JS bundles have content hashes in filenames: entry.client-ABC123.js
• Browsers can cache indefinitely without revalidation
• Cache invalidation is automatic when content changes (new hash)

Sources: apps/webapp/server.ts101-105

Build Output Structure

apps/webapp/
├── build/
│   ├── server.js              # Compiled server entry point
│   ├── server.js.map          # Source map
│   └── index.js               # Remix build output
├── public/
│   ├── build/                 # Fingerprinted assets
│   │   ├── entry.client-*.js
│   │   ├── root-*.css
│   │   └── routes/            # Route-specific bundles
│   └── [static files]         # favicon, images, etc.
└── prisma/
    └── seed.js                # Database seeding script

Sources: docker/Dockerfile85-88 turbo.json8-14

---

Entry Points and Bootstrapping

Server Entry Point

The server bootstraps in this order:

Application Entry Points

Entry Point	Purpose	Execution Context
server.ts	HTTP server setup, Express config	Node.js main process
entry.server.tsx	Server-side rendering	Per-request (server)
entry.client.tsx	Client-side hydration	Browser
root.tsx	Root Remix route, HTML shell	Both server and client
sentry.server.ts	Error tracking initialization	Server startup

Server-Side Rendering Flow:

Client-Side Hydration:

Sources: apps/webapp/server.ts1-269 apps/webapp/app/entry.server.tsx1-258 apps/webapp/app/entry.client.tsx1-16 apps/webapp/app/root.tsx1-133

---

Bootstrap and Initialization

Bootstrap Sequence

The webapp performs initialization tasks in apps/webapp/app/entry.server.tsx190-257:

Background Services:

1. Worker System - Graphile Worker for background jobs (apps/webapp/app/services/worker.server.ts)
2. Event Bus Handlers - React to run lifecycle events (apps/webapp/app/v3/runEngineHandlers.server.ts)
3. Event Loop Monitor - Detect event loop blocking (optional) (apps/webapp/app/eventLoopMonitor.server.ts)
4. Resource Monitor - Track memory and CPU usage (optional) (apps/webapp/app/services/resourceMonitor.server.ts)

Feature Flags on Startup:

Sources: apps/webapp/app/entry.server.tsx190-257

Graceful Shutdown

The server handles graceful shutdown on SIGTERM and SIGINT:

In clustered mode, the primary process:

1. Forwards signals to all workers
2. Waits for workers to exit (with timeout)
3. Exits the primary process

Sources: apps/webapp/server.ts207-223 apps/webapp/server.ts29-71

---

Error Handling

Server-Side Error Handling

Errors during request handling are caught by:

1. Sentry Integration - Wraps handleError export
2. Custom Error Logging - Logs to console with context
3. Uncaught Exception Handler - Exits process on fatal errors

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

Client-Side Error Boundary

The root ErrorBoundary component provides a fallback UI for React errors:

Sources: apps/webapp/app/root.tsx83-106

---

Deployment Architecture

Container Entrypoint

The Docker container uses a multi-step entrypoint script:

Entrypoint Script Steps:

1. Database Health Check - Wait for PostgreSQL to be ready
2. Prisma Migrations - Apply database schema changes
3. ClickHouse Migrations - Apply event store schema changes (if configured)
4. Copy Runtime Files - Copy Prisma schema and engine binaries
5. Set Memory Limits - Configure Node.js heap size
6. Start Application - Run server.js via dumb-init (PID 1 reaper)

Sources: docker/scripts/entrypoint.sh1-51

Build Arguments and Metadata

The Docker build captures metadata via build arguments:

Build Arg	Purpose	Used At Runtime
BUILD_APP_VERSION	Application version	Yes (env var)
BUILD_GIT_SHA	Git commit hash	Yes (env var)
BUILD_GIT_REF_NAME	Git branch/tag	Yes (env var)
BUILD_TIMESTAMP_SECONDS	Build timestamp	Yes (env var)
SENTRY_RELEASE	Sentry release ID	Build time only
SENTRY_ORG	Sentry organization	Build time only
SENTRY_PROJECT	Sentry project	Build time only

These values are used for:

• Version display in UI
• Sentry error tracking correlation
• Deployment tracking and debugging

Sources: docker/Dockerfile51-103

---

Configuration Files

Key Configuration Files

File	Purpose	Format
turbo.json	Turborepo build pipeline	JSON
package.json	Workspace and script definitions	JSON
apps/webapp/package.json	Webapp dependencies and scripts	JSON
remix.config.js	Remix framework configuration	JavaScript
tailwind.config.ts	Tailwind CSS design system	TypeScript
tsconfig.json	TypeScript compiler options	JSON
.dockerignore	Docker build exclusions	Text
pnpm-workspace.yaml	pnpm workspace packages	YAML

Sources: turbo.json1-147 package.json1-95 apps/webapp/package.json1-289 .dockerignore1-50

---

Performance Considerations

Database Query Monitoring

The webapp includes query performance monitoring:

This monitors both writer and replica connections and logs queries exceeding the threshold defined by VERY_SLOW_QUERY_THRESHOLD_MS.

Sources: apps/webapp/app/utils/queryPerformanceMonitor.server.ts1-65

Server Configuration Tuning

Performance-related configuration options:

Setting	Environment Variable	Default	Purpose
Keep-alive timeout	(hardcoded)	65s	Prevent premature connection closure
Max headers	server.maxHeadersCount	0 (unlimited)	Uses maxHeaderSize instead
Max old space	NODE_MAX_OLD_SPACE_SIZE	8192 MB	Node.js heap size limit
Worker count	CLUSTER_WORKERS	CPU count	Number of cluster workers
Compression	DISABLE_COMPRESSION	Enabled	Gzip response compression

Sources: apps/webapp/server.ts201-205 docker/scripts/entrypoint.sh44-50

---

Summary:

The Trigger.dev web application is a production-grade Remix application running on Express, designed for containerized deployment with optional clustering support. It provides both the dashboard UI and API endpoints, with comprehensive middleware, real-time communication capabilities, validated environment configuration, and graceful shutdown handling. The architecture supports horizontal scaling through clustering and integrates deeply with the run engine, background job processing, and event streaming systems.