liveBook · Manning

Orchestration

As explained in Clean Applications with Hexagonal Architecture

The coordination of collaborators to complete an application operation without owning the underlying business rules.

When a handler checks business conditions, validates commands, and decides how to persist, application coordination becomes tangled with rules that belong elsewhere. Orchestration keeps the handler focused on calling collaborators in the right order and propagating failures. section 4.4.2

The domain model decides what is allowed; the handler coordinates the operation. Command validation happens before the handler, and persistence is the repository’s concern. An if statement checking a business condition in a handler is a warning that the condition may belong in the domain model. section 4.4.2

Publishing an article

A publication handler coordinates the collaborators and lets an Either chain propagate failures. Article.publish() enforces the draft-status invariant; the repository handles persistence. A happy-path test can exercise the real application-domain collaboration while stubbing the ports. section 4.4.2 section 8.4.2

Choose where the sequence lives based on its duration and recovery needs:

  • Internal orchestration belongs in the handler when the steps stay in one process and transaction and finish within the request. It is not an integration mode. section 10.4 section 10.7
  • External orchestration uses a coordinator when a process crosses services, outlives a request, or needs to recover or compensate after a committed step. section 10.3.3 section 10.7
  • Use events when systems can continue by reacting to facts; use a synchronous call when the next step needs an answer. Do not turn the coordinator into a general message bus. section 10.4 section 10.7

An external coordinator is a driving actor: it calls use cases through input adapters and owns when and in what order steps run. The hexagon still owns what each step means and permits. The coordinator adds a runtime with state, retries, and failure handling to operate. section 10.3.3

Business and technical processes

An editorial pipeline from submission through review to approval is a possible business process, with stakeholder-visible state and approvals. Refreshing a thumbnail across services behind one pipeline step is a possible technical process; its sequencing and recovery matter to the implementation. section 10.3.3

Figure 10.2 Internal orchestration keeps the sequence inside one transaction. External orchestration spans services, so a coordinator holds the sequence durably and runs compensation when a later step fails.

Compare a handler’s transaction-bound sequence with a durable cross-service sequence that may require compensation. section 10.3.3

How Clean Applications with Hexagonal Architecture covers it

How deep it goes
Explains handler and coordinator boundaries, selection criteria, recovery, and operational costs; defers coordinator tool selection.
Examples
Uses article publication, an editorial approval pipeline, and a cross-service thumbnail refresh to illustrate different sequences.
What you can do after
Evaluate whether a handler, events, or an external coordinator should carry a sequence, and identify misplaced business conditions.
How it connects
Connects orchestration to domain invariants, use cases, repositories, input adapters, events, and synchronous calls.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Clean Applications with Hexagonal Architecture. The section links point to the parts of the book it draws on.