How workflows are built

A workflow is a directed graph of nodes. Each node does one job; each connection carries one value from an output port of a node to an input port of another. The graph has no cycles: data flows from the inputs to the outputs, and every node runs as soon as everything it needs is available — independent branches run in parallel.

Nodes

Every node has a type (a code such as ai/remove_background or image/resize), a set of input ports, a set of output ports and parameters. The catalog holds around two hundred node types, grouped by category:

Category	What the nodes do	Examples
Input	Receive the values that change from run to run	text, number, image, video, audio, document, JSON value, CSV, dataset
AI	Call AI models, with a default model and alternatives	generate or edit an image, remove a background, write or analyze text, transcribe, synthesize a voice, animate an image
Image, Video, Audio processing	Deterministic media processing	resize, crop, overlay, color, trim, merge, burn captions, mix, normalize loudness
Text processing	Deterministic text work	fill a text template, join, replace
Document	Documents from templates	render a design template to PDF or images, fill a template per item
Utility and Control	Structure, checks and routing	extract a JSON value, validate against a schema, predicate, filter, quality gate, select by key, switch
Enumerate and Aggregate	Fan a list out and collect it back	JSON / CSV / value-list enumerators, data rows, video and audio segments; generate JSON / CSV / PDF, merge video or audio
Workflow	Composition	run another published workflow as a single node
Output	Name what the run returns	image, video, audio, text, JSON, CSV, PDF, 3D model

Never guess a node type or a port name: read them from the catalog (search_node_types, then get_node_type, or Catalog discovery over REST). The catalog entry of a node says what it is for, when to use it, its exact ports and parameters, and, for AI nodes, which models it can use.

Ports, types and connections

Ports are typed: text, number, boolean, json, image, video, audio, pdf, document, model3d, csv and a few more. A connection is valid only between compatible types, and validation rejects the others before anything runs. Some input ports accept several values at once (an array port such as images shows as images_0, images_1, …).

A node reads a value in one of two ways:

• From a connection — the value produced upstream at run time.
• From a parameter — a value fixed in the workflow (a prompt, a size, a color, a model choice).

Many nodes accept either: a prompt can be typed as a parameter or come from a text template upstream. The node’s catalog entry says which inputs can also be set as parameters.

Some nodes have dynamic ports that depend on their configuration: a text template exposes one input per placeholder, a document node exposes one input per field of its template, a JSON enumerator exposes one output per property you map. Read them after configuring the node.

AI nodes and models

An AI node performs one capability (for example image editing or text generation) and can run it on different models. Each node has a default model, chosen for quality and cost, that is the right choice unless the user asks for another one. The model and its options determine the credit cost of the node, which is known before the run through an estimate.

AI results vary between runs by nature. Make them dependable by constraining them — a clear prompt, a JSON answer validated against a schema, a quality gate — and by keeping facts (prices, names, dates) out of the model and in deterministic steps.

From draft to published version

1. Draft. A workflow is created as an editable draft (in the editor, by the agent, or through the API).
2. Validate. Validation checks node types, parameters, connections, port types, required template fields and the structure of iterations. Each issue points to the exact node, port or parameter and suggests the fix.
3. Estimate. The credit estimate shows what a run will cost before it starts — with the actual inputs when they decide how many items a list produces.
4. Publish. Publishing freezes the definition as a numbered, immutable version. Only published workflows run. Editing again makes a new draft; publishing again makes the next version. Earlier versions stay available.
5. Archive a workflow that should no longer be used.

Changes are protected by an ETag: an edit must name the version it was based on, so two people (or an agent and a person) cannot overwrite each other’s work silently.

The interface of a workflow

The inputs and outputs of a workflow are its contract. By default they are its input nodes and output nodes; an interface can expose a chosen subset with readable keys, so that an App, an API client or an agent sees product_photo and hero_image rather than internal node names. The execution contract of a published workflow lists exactly what to send and where each output is read.

Inputs can be optional. When an optional input is not provided, the nodes that would need it are skipped — not failed — and the corresponding outputs are reported as absent. A run in which some branches were skipped still succeeds.

Running a workflow

An execution runs one published version with one set of inputs:

• Each node becomes a task that runs as soon as its inputs are ready; independent branches run at the same time.
• AI calls to external providers can take seconds or minutes; Madoo waits for them without blocking other work.
• Credits are reserved when the run starts and settled on what was actually used; unused credits return.
• A node that fails is retried when the failure is transient. A run in which some nodes failed ends as partial success; a run can be cancelled at any time.
• The result of a run is read by output key: text and JSON come back already parsed, files come back as links, and each output says whether it is present, absent (skipped) or missing.

To process a list of items — every row of a CSV, every photo of a shoot, every segment of a long video — a workflow does not need a loop: lists fan out on their own. That is the subject of Iteration.

Composition

A published workflow can be used inside another one as a single node (workflow/sub): its inputs and outputs become the node’s ports. Composition keeps large pipelines readable and lets teams reuse proven building blocks.

Rules of thumb

• Start from the outcome: decide the outputs first, then work backwards to the inputs.
• Look nodes up in the catalog instead of guessing; read the ports of a node after configuring it.
• Validate after every change and fix issues by their path; estimate before running anything that costs credits.
• Build what was asked. An AI step the user did not request costs their credits: propose it instead of adding it.
• Keep facts deterministic and let AI create, choose or rewrite — then check what AI produced before it reaches a customer.