Introduction & Getting Started
Relevant source files
The following files were used as context for generating this wiki page:
Recoup Tasks is a background processing engine built on Trigger.dev v4 designed to handle integrations for the Recoup API. Its primary purpose is to automate complex workflows such as AI-driven content creation, music industry data scraping, and personalized communication digests ("Pulses") for artists and organizations.
The system leverages a specialized architecture combining background workers, ephemeral Linux microVM sandboxes for code execution, and AI model integrations (fal.ai, Claude, and Recoup Chat API). It operates within a monorepo structure, emphasizing strictly validated schemas and test-driven development (TDD) for reliability.
Sources: README.md:1-5, AGENTS.md:21-30, src/tasks/createContentTask.ts:38-51
System Architecture
The project is structured into functional modules that handle specific aspects of the Recoup ecosystem. Core logic resides in src/tasks/, where Trigger.dev background tasks are defined using the v4 SDK.
Core Components
- Trigger.dev v4 Workers: The execution engine for all background tasks.
- Recoup API Client: Functions located in
src/recoup/for interacting with the core Recoup service. - Sandboxes: Managed Vercel Sandbox environments (Linux microVMs) used for isolated command execution and AI agent tasks.
- Content Pipeline: A sophisticated multi-step process for generating social-ready videos using AI image generation, video animation, and automated captioning.
Sources: README.md:28-37, AGENTS.md:21-30, src/tasks/createContentTask.ts:25-36
Data Flow Overview
The following diagram illustrates the high-level flow of a task execution, from trigger to completion.
This diagram shows how Trigger.dev workers ingest triggers, validate payloads via Zod, and branch into specialized logic modules.
Sources: README.md:18-26, AGENTS.md:21-30, src/tasks/createContentTask.ts:51-140
Setup and Installation
The project requires Node.js 20.x or later and pnpm 9.x.
Prerequisites
- Node.js 20.x+
- pnpm 9.x
- Trigger.dev Account and API Keys
- GITHUB_TOKEN (for repository interactions)
- FAL_KEY (for image and video generation)
Sources: README.md:7-11, src/tasks/createContentTask.ts:65-67
Getting Started Commands
The following commands are used to initialize and run the development environment:
| Command | Description |
|---|---|
pnpm install | Installs all project dependencies. |
pnpm dev | Starts the Trigger.dev development server for local task execution and logging. |
pnpm test | Runs the test suite using Vitest. |
pnpm run deploy:trigger-prod | Deploys the current task definitions to the production Trigger.dev environment. |
Sources: README.md:13-21, AGENTS.md:14-19
Development Workflow
Recoup Tasks follows strict engineering principles to maintain code quality and consistency across distributed tasks.
Coding Principles
- SRP (Single Responsibility Principle): Each file should export exactly one primary function.
- TDD (Red-Green-Refactor): Developers must write a failing test before implementing fixes or new features.
- Schema Validation: All task payloads are strictly validated using Zod schemas found in
src/schemas/. - Git Workflow: Changes must be made in feature branches. Pushing directly to
mainis prohibited; all updates require a Pull Request (PR) created via the GitHub CLI (gh pr create).
Sources: AGENTS.md:32-52, CLAUDE.md:32-52
Task Definitions
Tasks are defined using schemaTask or schedules.task to provide type safety and scheduling capabilities.
| Task ID | Trigger Type | Primary Function |
|---|---|---|
create-content | On-demand (Schema) | Full AI video generation pipeline (Image -> Upscale -> Video -> FFMPEG). |
send-pulses-task | Cron (Daily 9 AM ET) | Generates personalized email digests based on artist activity and social stats. |
run-sandbox-command | On-demand (Schema) | Executes Claude Code prompts inside an isolated Vercel Sandbox. |
pro-artist-social-profiles-scrape | Cron (Daily Midnight ET) | Updates social profile metrics for professional tier artists. |
Sources: README.md:18-26, src/tasks/createContentTask.ts:38-42, src/tasks/sendPulsesTask.ts:133-135
Testing and Debugging
The repository includes a comprehensive testing framework and local utility for debugging long-running pipelines.
Pipeline Testing
For the create-content task, a local utility src/content/testPipeline.ts allows developers to run individual steps (e.g., image generation, upscaling, or rendering) without triggering a full background job. This utility saves state to a .pipeline-state.json file between steps.
This sequence shows how state is persisted across isolated test executions to debug specific pipeline segments.
Sources: src/content/testPipeline.ts:1-20, 39-55
Logs
The system uses the @trigger.dev/sdk/v3 logger for all task output. Local development logs are accessible via the terminal running pnpm dev, while production logs are managed through the Trigger.dev dashboard.
Sources: AGENTS.md:36, README.md:18
Conclusion
The Recoup Tasks system provides a robust, schema-validated infrastructure for automating AI-heavy music industry workflows. By utilizing Trigger.dev for background execution and Vercel Sandboxes for isolated environments, it ensures scalable and secure processing of artist data and content. Following the established TDD and Git workflows is essential for maintaining the stability of these integrated services.