Temporal cluster

Nexus runs a self-hosted Temporal cluster on Railway. It provides durable, fault-tolerant workflow execution for long-running multi-system operations (provisioning, convergence, wipe).

Cluster components

Service	Port	Description
temporal-server	7233 (gRPC)	Core workflow engine — stores history, dispatches activities
temporal-ui	8080 (HTTP)	Web dashboard for monitoring workflows
temporal-postgres	5432	Temporal’s internal state database (Railway managed template)

All three run on Railway private networking. temporal-postgres is not managed by Pulumi (it was provisioned as a Railway managed template and must not be deleted).

Connectivity

scheduler-api connects to Temporal via:

temporal-server.railway.internal:7233

This is a Railway private DNS name — only reachable from within the same Railway project. The Temporal worker (built into scheduler-api) registers and receives activity dispatches over this connection.

No local Temporal

Temporal is typically skipped in local development. Workflows that require it (provisioning, convergence, wipe) will fail locally unless you run a local Temporal server. Run temporal server start-dev if you need to test workflow code locally.

Workflows

Workflow	Trigger	What it does
business-provisioning	Admin creates a business in portal	Creates records across scheduler DB, WorkOS (org + invite), Stripe (customer), Directus (tenant setup), Vendure (channel)
business-convergence	Directus webhook or manual trigger	Idempotently syncs state across WorkOS, Stripe, Vendure, and scheduler mirrors
business-wipe	Admin wipes a business in portal	Deletes across Stripe, WorkOS, scheduler; clears mirror caches; streams SSE progress

Activities

Activities are the individual steps within a workflow. Each activity is retried independently if it fails — the workflow resumes from the last successful activity.

Example activities in business-provisioning:

1. createSchedulerBusiness — insert business row
2. createWorkOsOrg — provision WorkOS organization
3. inviteOwner — send WorkOS invite
4. createStripeCustomer — create Stripe customer
5. provisionDirectusTenant — set up Directus roles + content space
6. provisionVendureChannel — create Vendure channel

Versioning

Temporal workflows must be versioned carefully — running workflows carry their original code version. Changing workflow code while executions are in flight can break deterministic replay or stall those executions mid-run. See the Temporal workflow versioning runbook.

Monitoring

The Temporal UI at port 8080 shows:

• Active and completed workflow runs
• Failed workflows + error messages
• Activity retry counts
• Workflow history replay for debugging

The portal health dashboard surfaces high-level Temporal stats (active count, recent failures) without requiring access to the Temporal UI directly.