Skip to main content
Two nouns sit at the center of every Swarm system, and it helps to separate them up front. A flow is the definition: a self-contained package of YAML contracts (states, events, system nodes, agents, tools, policy) that describes a piece of work. An entity is one actual unit of that work moving through it: a ticket, an order, a claim. If a flow is the program, an entity is the record it processes, advancing through the flow’s states as events arrive. A flow is also the only building block. Every level of a Swarm system is a flow, from the root down to the smallest child; there is no separate “project.” And a flow exposes a typed public interface (its pins), which is what lets you drop one into another system and wire it without refactoring.

​
Instances: static vs template

A flow is a definition; a flow instance is one running copy. How many copies exist depends on the mode you declare in the parent: Each instance owns exactly one entity. That is the scaling rule to internalize: a ticket system handling thousands of tickets is a template flow with thousands of instances — one instance, one ticket entity, one lifecycle each. A template flow is a stamp: nothing runs at boot, and the runtime mints a fresh instance (with its fresh entity) whenever a new identity arrives.

​
Entities

An entity is the thing moving through a flow instance’s staged lifecycle. It carries three things:
  • stage: which lifecycle stage it is in (new, assigned, resolved), exactly one at a time.
  • gates: named boolean checkpoints a handler can set and a guard can check (verified: true).
  • fields: typed data that handlers write (category, total, resolution).
You declare an entity’s fields in the flow’s entities.yaml. Its state is not declared there, because the lifecycle belongs to the flow’s stages: declaration (in schema.yaml).
entities.yaml

​
Many instances, no locks

Thousands of instances of one template flow can be live at the same time, each with its own entity and its own stage. You never reason about locking: the engine processes one instance’s events one at a time, so its entity cannot be corrupted by a race, while events for different instances run concurrently. That is what lets one contract carry hundreds or thousands of work items in parallel without any author-managed concurrency. This multiplicity has a knock-on effect: because a template flow has many instances, an event arriving from another flow cannot just go “to the flow” — it has to say which instance it is for, by carrying that instance’s identity field. Composing flows covers how that address is declared.

​
Pins: a flow’s public interface

A flow keeps most of its events and data private. What it chooses to expose, it exposes through typed pins: the events it accepts from outside, the events it emits outward, and the entity fields it reads or writes (no two flows may write the same field). Pins are the contract other flows wire against, which is what makes composition mechanical rather than a refactor. Any event not exposed as a pin is internal to the flow. See Composing flows for how pins are wired across flows.

System nodes and handlers

The deterministic logic that advances an entity through its states.

Stages, gates, and timers

The stages, gates, and time-based triggers an entity moves through.

Events and routing

How work moves between flows and the actors inside them.

Composing flows

Wiring flows together through their pins.