ADR / 003

Use code at orchestration boundaries

Keep transparent local rules declarative; move stateful, cross-system orchestration behind tested service boundaries.

Reference pattern

Independently created. Contains no employer or client implementation detail, internal names or figures.

01Context

A commercial process combines approvals, calls to external systems, work that must be retried and steps users watch. Business administrators can change declarative automation in hours; engineers can test and recover coded services. Put everything in declarative flows and retries, idempotency and compensation hide in chained automations that fail half-way. Put everything in code and every threshold change becomes a release.

02Decision drivers

  1. D01

    Who must be able to change the rule, and how often

  2. D02

    Whether the step has side effects outside the system

  3. D03

    Whether a failure must be retried, compensated or resumed

  4. D04

    Whether the behaviour must be tested before every change

03Options considered

Options considered: when each would be the right choice, what it costs, and the verdict under these premises
OptionRight whenCost / trade-offVerdict
Declarative automation onlyLocal, deterministic record rules with no external side effectsRetries, idempotency and compensation hide in chained flows; failures surface as half-applied updatesRejected
Coded services onlyTeams where every rule is complex and engineering owns all changeSimple thresholds become release-managed code; business administrators lose rules they should ownRejected
Split by boundary: declarative inside the record, code for cross-system orchestrationProcesses that mix local rules with stateful, cross-system stepsThe boundary must be defined, documented and governed; two skill sets to maintainSelected

Every option is right under some premises. The verdict applies to the context above.

04Decision

Use declarative automation for local, inspectable rules that change often: validation, assignment and thresholds. Move anything that crosses a system boundary, holds state across steps, needs idempotency or must compensate into a coded orchestration service with tests. Declarative automation may start an orchestration; it may not chain external side effects itself.

05Consequences

What this choice changes elsewhere in the system.

  1. Ownership

    Who changes what follows the boundary: business administrators own local rules; engineering owns orchestration.

  2. Failure

    External side effects are never chained in declarative flows, so a failure cannot leave work half-applied.

  3. Business state

    The orchestration publishes its state back to the user’s record, so progress is visible where people work.

  4. Change & release

    Thresholds change without a release; cross-system behaviour changes only through tested releases.

06Revisit when

The decision holds while its context holds. Challenge it when:

01

The process becomes local: no external calls and no state across steps.

02

Platform-native orchestration offers idempotency, retries, compensation and tests equivalent to code.

03

Business administrators stop changing the rules, so the speed argument for declarative automation disappears.

07Where this decision is applied

The decision says why this path was chosen; each case shows how it takes part in a larger architecture.

  1. Automation case / 01Designing stateful orchestration for a long-running commercial processOne durable run per period with an explicit state machine, start-once steps, waiting as a state, a lightweight continuation that wakes unfinished runs, retry classified at the step boundary and a run record that answers the operator's questions—so a failure in step seven resumes at step seven.AutomationData & IntegrationsRevenue OperationsArchitecture case · 12 min
  2. Operating-model case / 05Owning and evolving the operating model after go-liveThe complete post-go-live model: every project responsibility handed to a named operating owner before go-live, recurring friction classified into a governed backlog, change authority per domain, versioned releases, operating and release forums, and adoption and model reviews that turn what users struggle with into design changes—so the model keeps improving after the project ends.Digital Operating ModelChange & AdoptionSystems & CRM ArchitectureArchitecture case · 10 min

Decisions this one depends on, or constrains.

  1. ADR / 009Model long-running automation as a run record with a state machineWhen automation spans steps, systems or days, give each run an identity, a state and step-level guards—so it can wait, fail, resume and finish exactly once.Proposed patternAutomation · Orchestration · Operations
  2. ADR / 007Treat uncertain integration outcomes as unknown, not failedA timeout says nothing about whether the receiver committed. Model ‘unknown’ as its own state, resolve it by request key, and only then retry or fail.Proposed patternIntegration · Resilience · ERP