Background Jobs

Trovella uses Inngest (self-hosted, open-source) for durable background job execution. Inngest provides step-level checkpointing so that a failure partway through a multi-step pipeline does not re-execute already-completed steps.

Why Background Jobs Exist

The research engine produces content that must be chunked, contextualized, embedded, and indexed across two data stores (pgvector and Typesense). Each of those operations calls a different external service and can fail independently. Running them synchronously in a request handler is fragile and slow. Inngest decouples the write (MCP tool stores a record) from the processing (background function indexes it for search).

Architecture at a Glance

MCP tool (store_research, store_research_output)
  |
  | emitContentCreated()        -- fire-and-forget event
  v
Inngest Dev Server (Go binary, self-hosted on VM)
  |
  | HTTP callback to /api/inngest
  v
Next.js serve() handler
  |
  | dispatches to registered functions
  v
index-content function (4 durable steps)
  Step 1: chunk-content          -- recursive character splitter
  Step 2: generate-context       -- Claude Haiku contextual prefix
  Step 3: embed-chunks           -- Gemini embedding API
  Step 4: store-and-sync         -- pgvector INSERT + Typesense sync

Current Functions

Function ID	Trigger Event	Retries	Concurrency	Status
index-content	search/content.created	2	5	Active -- powers hybrid search indexing
welcome-email	auth/user.created	3	default	Placeholder -- stub for future email sending

Key Packages

• apps/web -- contains the Inngest client, function definitions, and the /api/inngest serve route
• packages/mcp -- contains the event emitter (emitContentCreated) called by MCP tools

Related Pages

• Inngest Decision (ADR-006) -- why Inngest was chosen over Temporal, BullMQ, and DIY
• Job Definitions -- detailed walkthrough of each function
• Event Patterns -- how events flow from MCP tools to Inngest functions
• Retry and Concurrency -- configuration, failure modes, and step-level durability
• Local Development -- running and testing jobs locally
• Query Patterns -- how jobs interact with the database via withTenantContext
• Infrastructure -- Observability -- Inngest dashboard access and monitoring