← Back to selected work
ENGINEERING STORY / 02ORCHESTRATION · BACKEND ARCHITECTURE · RELIABILITY

Redesigning Fleet interactions.

In October 2026, I designed and implemented the Fleet interaction framework within the existing Order Scheduler. I separated planning from execution and brought Fleet calls behind a centralized interaction boundary to make their control flow easier to reason about.

In this story
About this write-up. My responsibility was the framework's technical architecture and implementation; the upstream business and configuration specification was developed collaboratively. The scheduler already existed. Earlier legacy refactoring, Rule Flow and conditional order chaining, and later Fleet configuration simplification are separate initiatives. Diagrams, the illustrative contract, and hypothetical failure scenarios explain the reasoning without reproducing private production implementation details or claiming every example was implemented or tested. Disclosure review remains outstanding.

01 / WHERE COUPLING STARTS

A scheduler can quietly become the whole system.

Fleet interactions were distributed across several legacy execution paths, with configuration decisions intertwined with the code performing the calls. Understanding a change meant tracing both the decision and its effects across those paths. That made it harder to assess how an internal change might affect established scheduler behavior.

I designed the framework around a shared Fleet interaction boundary and separated two responsibilities within it: which interaction should be selected? and how should that interaction be carried out? Centralizing that boundary gave interaction ownership and control flow a consistent place in the design.

THE DESIGN QUESTIONCan a scheduling decision be understood and tested without running the external operation it chooses?

I implemented the redesign in stages, with compatibility guiding the migration of existing call paths. The constraint was to preserve established scheduler and provider-facing behavior while changing internal responsibilities. A clearer structure would not justify silently changing what those paths did.

02 / THE ARCHITECTURAL BOUNDARY

Decide first. Execute second. Make the handoff obvious.

I made planning side-effect-free: the planner selects the intended Fleet interaction from supplied state and policy context. The executor carries out the selected operation through the integration boundary, where provider-specific interaction concerns belong. Results feed subsequent orchestration decisions. This separation lets decision logic be reasoned about and tested without performing the external operation.

FIG. 01 / RESPONSIBILITY BOUNDARIESCONCEPTUAL MODEL
OUTCOME LOOPResult + progress

Correlate the result, update durable state, and inform the next planning decision.

An educational decomposition of responsibilities; it does not describe internal services, deployment topology, or proprietary protocols.

The decision contract makes the handoff explicit: an intended action and the context needed to execute it, without making the executor reconstruct the selection policy. Supplied inputs can become stale before execution. Side-effect-free planning does not make the whole scheduler independent of external state or establish that a decision remains valid indefinitely.

ILLUSTRATIVE CONTRACTNOT PRODUCTION CODE
Decision {
  operationId
  actionType
  targetReference
  policyContext
}

This is an illustration, not a private API. An operationId identifies a logical operation; retries are separate attempts whose outcomes need attribution. Identity supports correlation, but does not itself enforce idempotency, safe concurrent result acceptance, or exactly-once provider effects.

03 / EXPLICIT BEHAVIOR

Rules are part of the architecture, not an afterthought.

Here, rules mean the decision policies governing Fleet interactions: precedence, fallback, result handling, and configuration. These are concerns of the framework boundary; the separate Rule Flow and conditional order-chaining initiative is outside this account. The cards below summarize conceptual questions, not specific policy semantics or a claim that each behavior changed in this redesign.

One useful habit from this work was to write down the expected behavior before changing the framework. It turns “what happens here?” from an argument spread across conditionals into something reviewers and testers can inspect.

01 / PRIORITYWhat takes precedence?

Define how competing eligible actions are selected.

02 / FALLBACKWhat happens on no match?

Make the default path an explicit behavior.

03 / RESULTSWhere does the outcome go?

Specify correlation and result publication.

04 / FLAGSWhat varies by configuration?

Keep policy switches distinct from execution plumbing.

04 / FAILURE PATHS

The interesting part happens when the happy path stops.

These proposed checks examine the Fleet boundary under changing state and uncertain outcomes. Retry responsibility must identify who classifies errors, who schedules another attempt, and who enforces an attempt limit or time budget and records exhaustion. Planning, execution, and integration must not each add an independent retry loop that defeats the intended bound. Persistent provider failures also require considering total in-flight work and retry pressure, not just the limit for one operation.

01An order is not eligible yet
THE QUESTIONWhat if eligibility changes between planning and execution?
DESIGN RESPONSE

Planning selects an interaction from supplied context. A valid selection can become invalid before execution. Checking necessary preconditions at the relevant action boundary is distinct from re-evaluating all selection policy inside the executor; side-effect-free planning alone does not keep inputs fresh.

TRADEOFF / PROPOSED CHECK

Preconditions need explicit semantics. Proposed check: test an initially ineligible order, then an eligible decision whose preconditions change before execution. Under the illustrative policy, assert that neither permits a prohibited provider call. This does not prescribe a production rejection or replanning protocol.

02A provider call times out
THE QUESTIONWas the operation executed remotely?
DESIGN RESPONSE

A missing response leaves several possibilities: failure before acceptance, success with a lost response, or an outcome still unknown to the scheduler. Safe retry or reconciliation depends on the provider contract. Status queries and idempotency support cannot be assumed, and a centralized boundary alone cannot prevent duplicate external effects.

TRADEOFF / PROPOSED CHECK

Uncertainty may delay progress. Proposed check: simulate acceptance with a lost response separately from a known rejection. Assert that the unknown outcome is not recorded as confirmed failure and that any retry or reconciliation follows the simulated provider contract.

03Several order types are available
THE QUESTIONWho decides which one takes precedence?
DESIGN RESPONSE

The planner should resolve competing Fleet interactions using explicit precedence, tie, and fallback policies. Repeatable decisions require controlled state, configuration, and any time-dependent inputs. This concerns interaction selection, not the separate Rule Flow initiative.

TRADEOFF / PROPOSED CHECK

Each policy choice adds cases to maintain. Proposed check: supply competing eligible actions, a tie, and a no-match case with fixed inputs. Assert the selection prescribed by each illustrative policy, including no action where that policy requires it, without inventing production precedence rules.

04A result arrives after a retry
THE QUESTIONCan late, repeated, or concurrent results change the logical outcome incorrectly?
DESIGN RESPONSE

Correlate the result with the logical operation and the attempt it describes, then enforce the permitted state transition. Correlation or a separate state check is insufficient if competing handlers can both accept a result. A late observation must not overwrite a newer authoritative state merely because its operation identity matches.

TRADEOFF / PROPOSED CHECK

Acceptance rules must cover races as well as sequential delivery. Proposed check: replay a result, deliver duplicates concurrently, and deliver an older attempt after completion. Assert one application of the defined logical transition and no invalid state regression; this does not establish how many times the provider acted.

These are hypothetical scenarios and proposed assertions, not production incidents, completed tests, or evidence of particular enforcement mechanisms. Bounded retries limit repeated attempts; they do not guarantee recovery. Permanent failures and exhausted budgets need explicit outcomes rather than indefinite retries.

05 / VALIDATION

Test the behavior, not just the method.

Replacing internal Fleet paths had to respect behavior that the existing scheduler and its integrations depended on. Compilation or a passing unit test cannot establish that compatibility. I would compare old and new paths against agreed expectations for selection and fallback, the integration boundary reached, outcome and error classification, and retries and notifications under the applicable contracts. In-flight and interrupted work also belongs in that comparison. The matrix below illustrates specific checks; it is not a record of completed regression tests.

Swipe horizontally to read all table columns →

Illustrative behavioral test matrix — examples to verify, not a claim of completed tests.
SituationPlanning expectationExecution expectationCorrectness property
Eligible decision; preconditions change before executionSelect an action from fixed planning inputsCheck required execution preconditions without repeating selection policyNo provider call prohibited by the illustrative preconditions
No policy matches the controlled inputsSelect the fallback specified by the illustrative policyExecute only the resulting action, if anyObserved action matches the fallback; no provider call for a no-action decision
Simulated retryable failure persists until the budget is exhaustedKeep the intended interaction distinct from retry classificationAdapter reports the outcome; the designated retry owner applies the budgetAttempts stop at the configured limit or deadline; exhaustion is observable
Duplicate results race; an older attempt arrives laterKeep the logical operation distinct from its attemptsCorrelate results and enforce valid transition acceptanceOne application of the defined logical transition; no invalid state regression

I implemented the framework in stages so that replacing legacy call paths did not require reviewing every responsibility change at once. The rationale was to keep behavior comparisons understandable and make a regression easier to isolate, rather than assume a new boundary preserved behavior automatically. Architecture and staged implementation are part of my reported work; specific test coverage, comparison results, and release status still require evidence review. No independently verified regression results are presented here, and the illustrative checks do not establish complete backward compatibility or production rollout.

06 / TRADEOFFS

Modularity doesn't make complexity disappear.

I chose centralized Fleet interaction ownership with separate planning and execution boundaries. Keeping selection intertwined with the existing execution paths would leave the decision and external effect spread across those paths. The separation required stricter contracts, but gave each responsibility an explicit place. I accepted that maintenance cost to make policy, provider interaction, and compatibility questions easier to examine independently.

WHAT IMPROVESSelection and external effects have distinct owners.

The intended benefit is to test policy from supplied inputs and trace a selected action through a consistent integration boundary. This gives behavior comparisons clearer points to inspect during migration.

WHAT IT COSTSThe contracts become work to maintain.

Planning inputs and decision/execution contracts must stay consistent with execution preconditions and adapter boundaries. Result correlation, retry ownership, and state and progress semantics need explicit responsibilities. Regression coverage must follow the paths being migrated; separating the code does not remove that work.

07 / WHAT I TOOK AWAY

The migration was part of the design.

Working inside an existing scheduler made compatibility part of the architectural problem. Separating Fleet decisions from external effects gave me clearer boundaries to implement, but the existing behavior still had to be accounted for as call paths moved. The framework design and the migration could not be judged independently.

The lesson I take from this work is that explicit contracts earn their maintenance cost when they make responsibility inspectable: what selected an interaction, what performs it, and where its result belongs. I can describe that architectural contribution without treating the design itself as proof that every compatibility or recovery condition was verified.

THE TAKEAWAYA useful boundary lets me explain the decision, follow its effects, and identify the existing behavior a change must preserve.

This case study is intended for architectural discussion only. All examples require personal accuracy and employer-confidentiality review before public publication.

PREVIOUS ENGINEERING STORYDistributed billing and reporting
Read the case study ↗