System Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The system is architected as a background task processing engine powered by Trigger.dev v4. It manages complex workflows involving AI content generation, automated coding agents, and data synchronization across multiple submodules. The infrastructure relies on isolated Linux microVM sandboxes for code execution and utilizes various external AI services (Claude, Fal.ai) and APIs (Recoup Chat, Recoup API) to fulfill tasks.
Sources: AGENTS.md:16-17, CLAUDE.md:16-17, src/sandboxes/writeReadme.ts:38-42
Core Components
The repository is organized into specialized directories that handle distinct aspects of the system's logic:
| Component | Responsibility |
|---|---|
src/tasks/ | Definitions for Trigger.dev background workers. |
src/sandboxes/ | Management of isolated Linux microVM environments (Vercel Sandboxes). |
src/schemas/ | Zod-based validation for task payloads and API responses. |
src/recoup/ | Client functions for interacting with the Recoup API. |
src/content/ | Logic for media generation, template loading, and asset processing. |
Sources: AGENTS.md:18-24, CLAUDE.md:18-24
Task Processing Architecture
The system utilizes Trigger.dev v4 SDK patterns, specifically task() and schemaTask(), to handle asynchronous operations. These tasks are designed to be idempotent and often involve long-running pipelines such as video generation or automated code refactoring.
Content Generation Pipeline
The createContentTask implements a multi-stage pipeline that transforms a request into a social-ready video. It coordinates several external AI models and media processing tools.
The pipeline handles face-guide resolution from GitHub, audio clip selection, and final video rendering using FFMPEG to crop 16:9 content to a 9:16 portrait aspect ratio.
Sources: src/tasks/createContentTask.ts:31-137, src/tasks/tests/createContentTask.test.ts:114-121
Sandbox & Agent Infrastructure
For tasks requiring code execution or git operations, the system spawns ephemeral Vercel Sandboxes. These are isolated Linux microVMs where "Claude Code" agents can perform work.
Sandbox Features
- Isolated Execution: Each sandbox runs in its own microVM to ensure security.
- Snapshot Support: State can be saved and restored via snapshot IDs.
- GitHub Integration: Linked repositories allow for persistent file storage and submodule management.
- Automated Lifecycle: Sandboxes are configured with automatic timeouts and are explicitly stopped after task completion.
Sources: src/sandboxes/writeReadme.ts:44-51, src/tasks/tests/codingAgentTask.test.ts:100-102
Coding Agent Workflow
The codingAgentTask orchestrates the lifecycle of a coding agent from sandbox creation to Pull Request (PR) submission.
Data Architecture
The system uses a Supabase-backed PostgreSQL database, with types defined to mirror the public schema. The data model supports multi-tenant accounts, artist management, and social media analytics.
Key Entities
- Accounts: The root entity for billing and access control.
- Socials: Stores profile data and engagement metrics for platforms like TikTok, YouTube, and Spotify.
- Fans: Tracks fan interactions, segments, and streaming data.
- Tasks & Scheduled Actions: Persists background job state and cron-based triggers.
Sources: types/database.types.ts:241-248, types/database.types.ts:1248-1262, types/database.types.ts:1483-1498
Submodule Management
Because the project operates as a monorepo with multiple submodules, the architecture includes a SUBMODULE_CONFIG to map directories to their respective repositories and target branches (e.g., api targets test, while tasks targets main).
Sources: src/sandboxes/submoduleConfig.ts:1-13
Integration Points
| Endpoint | Purpose |
|---|---|
https://chat.recoupable.com/api | Used for generating AI-driven captions and insights. |
https://recoup-api.vercel.app/api | Core business logic and data persistence. |
fal.ai | Media generation and upscaling. |
Sources: AGENTS.md:46-47, src/tasks/createContentTask.ts:55-58
Conclusion
The System Architecture is a robust, event-driven framework designed to automate the lifecycle of content creation and software development. By leveraging Trigger.dev for task orchestration and Vercel Sandboxes for isolated execution, it provides a scalable environment for AI agents to interact with git repositories and media processing pipelines.