Skip to main content

Core Concepts

These are the main runtime nouns you will keep seeing in the Triggers v2 code and docs.

Flow​

A flow is the released graph that tells Triggers how to route one source event through the runtime. It starts at a source node, passes through service nodes, runs actions inside those services, and can continue to other supported nodes.

For a newcomer, one easy shape is:

source -> service(flow_lab) -> action(parse)

Source​

A source is the entry point that starts a flow run when a matching event arrives. In the local flow_lab example, the first source you touch is flow_lab_in.

In the recommended first flow, that source routes into a service node first. More broadly, a source can also route into nodes such as condition, rate-limit, mapping, output-topic, or service-in before a service action runs.

Service​

A service is the runtime boundary that registers capability with Triggers and owns one or more actions. In the local example, the service name is flow_lab.

Flows can target services through service segments. In Studio, that segment maps to the runtime service-in node kind, with actions nested under it.

Action​

An action is executable work inside a service. It has input and result schemas plus runtime settings such as timeout and retry.

Actions are not wired directly to each other in the first simple graph. If you want to continue after one action, route into another service segment or another supported node type.

Run​

A run is one execution of a released flow for one incoming source event. When you inspect:

curl -s "http://localhost:8888/api/v2/flows/<flow_id>/runs" | jq .

you are looking at the recorded history of those executions.

DLQ​

DLQ means dead-letter queue. When a handler fails permanently or exhausts its local retries, the runtime publishes a DLQ entry instead of silently dropping the work.

In the current wire docs, per-action failures use the triggers.v2.dlq.<service>.<action> subject shape.

Secondary terms​

manifest​

The registration payload a service sends when it comes online. It describes the service identity, actions, service_sources, supported node kinds, and related runtime metadata.

In practice, the runtime receives the manifest on triggers.v2.manifest.register, stores it, and uses it to understand what that service can do.

service_sources​

The source ingress declarations inside a service manifest. They are manifest-declared ingress capability and catalog data for what a service segment can receive.

Do not confuse them with top-level flow sources. A source like flow_lab_in starts the flow. A service_source such as nats describes what a service segment can receive, while the live target is opened from released flow service-in config reconciled from flow broadcasts and the flow cache.

result_event​

Per-action metadata that describes the public shape of an action result for downstream binding and Studio chaining.

This is especially important once you move past the first simple path and start chaining outputs, such as parse -> wrap. In the repo example, downstream bindings depend on upstream actions declaring result_event.

result_event is catalog metadata. It helps the graph understand action output shape, but it is not the same thing as the runtime observability event.

CompletionEvent​

The runtime observability event emitted for node progress and outcomes. It carries flow and node identity, service, timing, status, and optional error details. It is published on triggers.v2.flow.events.<flow_id>.

The important mental model is:

  • CompletionEvent is for observability
  • the result payload keeps moving through the graph separately

Do not assume the result body lives inside CompletionEvent. In the current wire contract, it does not.

If you are new, keep this short version in your head:

  1. A source event starts a flow run.
  2. The flow routes through graph nodes, often into a service segment early on.
  3. Nodes in the graph make progress, including service actions when the flow reaches them.
  4. The result payload can continue through the graph.
  5. CompletionEvent gives observability.
  6. Terminal failures land in the DLQ.

For the runtime details behind that model, read /triggers/engine-architecture and /triggers/wire-protocol.