Understanding Tasks

A task represents any user-initiated request within your application. Think of it as a single unit of work that your application handles. This concept is incredibly flexible; a task can be anything from an external data scraping and assembly operation to a complex video or image transformation, or even an external AI request.

It can be pretty much anything you can imagine your application doing in the background.

What is a Task?

At its core, a task is a defined unit of work that your application executes. When a user initiates a task, it typically costs them credits, reflecting the computational or resource cost of the operation.

Tasks are structured using Task Groups and Fields defined directly within your flareforge.jsonc configuration. This declarative approach allows you to specify the data inputs required for any task without writing extensive boilerplate code for databases or forms.

For detailed information on schemas, refer to the Task definitions.

How Tasks Work

Flareforge automates the entire lifecycle of a task:

1. You define the structure and required inputs for your tasks in flareforge.jsonc

2. Flareforge’s code generation engine automatically handles:

   • Database schemas
   • Frontend forms for users to submit task requests
   • Type-safe API to receive task submissions

3. When a user submits a task (initial request or revision), it’s validated by a dedicated API endpoint and then automatically added to a Cloudflare Queue.

4. Your Cloudflare Worker’s queue handler picks up the task and dispatches it to your custom-defined logic.

What You Can Do With Tasks

The task system is the heart of Flareforge’s extensibility for custom functionality:

• Easily integrate calls to AI models for image generation, text summarization, content analysis, or any other AI transformation.
• Manage workflows for video encoding, image manipulation, or audio processing in the background.
• Create and store content unique to each user, from custom designs to personalized reports.
• Perform external data scraping or bulk data processing.

Flareforge provides you with a structured, type-safe environment to define and execute these complex operations. You focus on the core logic of what your task does, and Flareforge handles the underlying infrastructure and boilerplate.

Your custom task logic resides in your main Worker file (typically workers/index.ts). Here, you define distinct submission and revision handlers using the ExportedTaskHandler interface:

workers/index.ts

export default {
  // Handles a new task submission
  async submission({ payload }, ctx) {
    console.log("Processing new task:", payload.task.id);
    // Your custom logic here: e.g., call an AI model, process data
    // Use ctx.upload(file) to save results to R2
    // Use ctx.db to interact with D1
  },

  // Handles a request for a revision or change to an existing task
  async revision({ payload, version }, ctx) {
    console.log(`Processing revision for task ${payload.task.id}, version ${version}`);
    // Your custom revision logic here: e.g., apply changes to previous output
  },
} satisfies ExportedTaskHandler;

Each of these handlers receives a ctx object, providing powerful utilities like ctx.upload for asset management, ctx.db for database interactions, and other Flareforge service managers.