Background Jobs & Triggers
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Background Jobs & Triggers within the Tuturuuu platform represent the automation layer responsible for executing non-interactive tasks, scheduled operations, and event-driven logic. This system is integrated into the core architecture to handle complex business processes—such as workforce management, calendar synchronization, and AI-driven optimizations—without blocking the primary user interface.
The scope of this module includes background job processing via external providers like Trigger.dev, internal cron-like scheduling for recurring tasks, and reactive triggers based on database or API events. These components work together to provide features like scheduled workflow execution, automated payroll calculations, and real-time AI response processing.
Sources: README.md, apps/web/src/app/[locale]/(marketing)/products/workflows/page.tsx:1-50, conductor/tracks/workforce_20251225/spec.md:1-20
Workflow Automation & Execution
The platform provides a dedicated workflow automation system designed to transform business processes into intelligent, automated sequences. This system utilizes triggers to initiate execution based on time, specific events, or custom conditions.
Trigger Mechanisms
Workflows can be initiated through various trigger types:
- Scheduled Triggers: Execution based on predefined time intervals or advanced timing controls.
- Event-Based Triggers: Reactive execution triggered by system events or user actions.
- One-Click Manual Execution: Direct user-initiated triggers with real-time monitoring.
Sources: apps/web/src/app/[locale]/(marketing)/products/workflows/page.tsx:142-160
Workflow Architecture
The following diagram illustrates the flow from a trigger event to the execution of automated workflow steps:
The diagram shows how triggers lead to conditional analysis and subsequent execution of tasks, with results logged for future AI-driven optimization.
Sources: apps/web/src/app/[locale]/(marketing)/products/workflows/page.tsx:162-185
AI Processing Triggers
Background processing is heavily utilized in AI interactions, where long-running requests to various model providers (OpenAI, Anthropic, Google) are handled through streaming and asynchronous completion triggers.
Asynchronous AI Lifecycle
When a user sends a message, a series of background operations are triggered to maintain session state and manage credits:
- Pre-flight Triggers: AI credit checks and token capping are executed before the request is sent to the provider.
- Stream Processing: Content is streamed back to the user while background logic handles file analysis and context aggregation.
- Completion Triggers: Upon completion (
onFinish), a background task saves the assistant's response to the database and asynchronously deducts credits.
Sources: packages/ai/src/chat/google/route.ts:250-320, packages/ai/src/chat/google/route.ts:340-370
AI Credit and Storage Trigger Flow
| Component | Trigger Point | Action |
|---|---|---|
| Credit Manager | Pre-Request | Validates workspace balance and applies token caps. |
| Message Saver | Post-Response | Inserts AI response into ai_chat_messages table. |
| Credit Deductor | Post-Response | Calculates usage and updates workspace credits. |
| File Processor | Message Start | Moves files from temporary storage to the chat thread. |
Sources: packages/ai/src/chat/google/route.ts:180-230, packages/ai/src/chat/google/route.ts:375-400
Specialized Background Operations
Workforce and Payroll Engine
The Workforce system utilizes background processing to calculate financial distributions based on activity triggers.
- Time-Tracker Integration: The system aggregates approved time logs to calculate dues.
- Calculation Triggers: Payroll runs can be triggered manually as a "Period-Based Run" or act as a "Continuous/Real-time" process that updates balances as logs are approved.
- Audit Logging: Every compensation change triggers a background audit record to track historical values and timestamps.
Sources: conductor/tracks/workforce_20251225/spec.md:52-78
Infrastructure & CI Triggers
The development lifecycle is governed by a strict set of triggers defined in the project's CI configuration.
Centralized control of all CI workflows is maintained via tuturuuu.ts, ensuring all main jobs depend on a successful check-ci trigger.
Sources: GEMINI.md:310-325, conductor/workflow.md:150-180
Technical Implementation Details
External Integration
The platform leverages @tuturuuu/trigger as a bridge to Trigger.dev for managing background jobs that require persistence and retry logic, such as Google Calendar synchronization.
| Package | Integration | Purpose |
|---|---|---|
@tuturuuu/trigger | Trigger.dev | Background jobs and calendar sync management. |
@tuturuuu/google | Google APIs | Analytics and Calendar event triggers. |
@tuturuuu/supabase | PostgREST/RLS | Data-level triggers and secure transaction logging. |
Sources: README.md:100-115
Development Guidelines for Triggers
The project enforces a "Non-Interactive & CI-Aware" principle for all background and tool-based triggers. This ensures that scripts and migrations are idempotent and safe to re-run in various environments without manual intervention.
Sources: conductor/workflow.md:10-25, GEMINI.md:120-135
Summary
Background Jobs & Triggers serve as the backbone for Tuturuuu's automation capabilities, ranging from high-level business workflow execution to low-level system maintenance and AI credit management. By decoupling these intensive operations from the user request cycle, the platform maintains performance while ensuring data integrity through auditable logs and asynchronous completion triggers.