All Docs
FeaturesCSI Teachable Replacement AppUpdated March 13, 2026

Background Job Infrastructure with Inngest

Background Job Infrastructure with Inngest

Overview

Starting in v1.0.6, the platform uses Inngest as its background job and event-driven workflow runtime. This underpins asynchronous operations such as the course import engine, content processing pipelines, and any other tasks that must run outside the HTTP request/response cycle.

Architecture

Inngest Client

A single shared Inngest client instance is initialized at startup and used across all background job definitions. This client is responsible for:

  • Publishing events that trigger background functions.
  • Connecting functions to the Inngest execution runtime.
  • Providing context (event payload, step utilities, logging) to each job function.

Next.js API Route Handler

An API route is registered in the Next.js application to serve as the Inngest endpoint. Inngest communicates with your application through this route to:

  • Discover registered functions during the sync step.
  • Deliver event payloads to trigger function execution.
  • Handle retries and step-level checkpointing.

The handler is mounted at a well-known path that must be accessible to the Inngest infrastructure (cloud or self-hosted).

Event Naming Conventions

All events follow a consistent dot-separated naming scheme:

<domain>/<action>

Examples:

Event NameDescription
import/course.requestedA new course import has been triggered
import/lesson.processA single lesson is queued for processing
import/asset.downloadA media asset is queued for download

Using a shared naming convention ensures that events are predictable, searchable, and easy to trace across the system.

Error Handling

All background job functions follow a standard error handling pattern:

  • Typed errors are thrown with descriptive messages to surface meaningful failure reasons in the Inngest dashboard.
  • Unrecoverable errors halt execution and are not retried, preventing wasted compute on known-bad inputs.
  • Transient errors (e.g. network timeouts, upstream service unavailability) propagate naturally and are subject to Inngest's built-in retry policy.
  • Failures are logged with structured context (event ID, job type, affected resource) to aid debugging.

Relationship to the Import Engine

The background job infrastructure introduced in this release is a direct dependency of the Teachable course import engine. The import engine submits events through the Inngest client, and each stage of the import pipeline (course structure extraction, lesson content processing, asset downloading) runs as a discrete Inngest function with its own retry and error handling configuration.

Developer Notes

  • All new background job functions must be registered with the Inngest client before the API route is mounted, or they will not be discovered during the sync step.
  • Event payload schemas should be defined with strict types to catch mismatches at compile time.
  • Use Inngest's step.run() utility to break long-running jobs into individually retriable steps rather than a single monolithic function body.