AdminConsole
Stateful journeys/InTouch Telematics
statefultrip aggregate
InTouch · telemetry-backed operations

Connected fleet trip

Provision an observable trip, follow live vehicle state, explain exceptions, close deliberately, and retain a replayable operational record.

Open implementation workshop Run verified appExplore lifecycle
Lifecycle state machine

Every state means something operational

A state is not a UI label. It determines which actor may act, what evidence exists, what may be retried, and how recovery proceeds.

01
planned

Planned

Stops, service window, asset, driver, and business identifiers are fixed enough to create the trip.

02
ready

Ready

The trip and assigned device are provisioned, entitled, and emitting sufficiently fresh location.

03
active

Active

Positions, events, progress, ETA, and exception state are continuously observed.

04
exception

Exception

A deviation, delay, device gap, geofence, or safety event requires operator attention.

05
closing

Closing

Arrival is plausible but late events, final proof, and device state are still being reconciled.

06
closedterminal

Closed

The provider trip and internal aggregate are closed with a final trace, metrics, and exception record.

Command → decision → event

Transitions are attributable and retry-safe

Commands express intent. The aggregate validates current state and invariants, commits one new version, and emits a fact in the same transaction.

Command & actorAllowed fromResultIdempotency strategy
create_tripFleet planner
new aggregate
plannedtrip.created

Use the dispatch or order journey ID across retries.

confirm_device_readyTelematics service
planned
readytrip.ready

Bind the decision to device identity and observed health version.

start_tripDriver
ready
activetrip.started

Persist the driver command ID before the first transmission.

raise_exceptionTelematics service
activeexception
exceptiontrip.exception_raised

Derive a stable key from rule, asset, and source-event identity.

resolve_exceptionOperations controller
exception
activetrip.exception_resolved

Record acknowledgement and resolution command IDs separately.

request_closeDriver
activeexception
closingtrip.close_requested

The same close request may be safely replayed while finalization runs.

close_tripTelematics service
closing
closedtrip.closed

Provider close and internal completion must reconcile to one terminal version.

Durable records

Persist enough to recover and explain

Keep provider responses, business identity, state, events, and side-effect delivery distinct so each can be reconciled safely.

Trip aggregate

Current operational state and identity mapping.

tripIdexternalIdproviderTripIddeviceIdstateversion

Telemetry envelope

Immutable position and vehicle observation.

sourceEventIddeviceIdeventTimereceivedTimepositionquality

Exception case

Operator-owned acknowledgement and resolution workflow.

caseIdruleseverityownerstatussourceEventIds

Trip revision

Recomputed summary when bounded late data arrives.

tripIdrevisioninputWatermarkmetricsgeneratedAt
Non-negotiable rules

Protect truth at the aggregate boundary

  1. 1

    A device is assigned to at most one active trip in the same operational context.

  2. 2

    Raw telemetry is immutable and distinguished by event time and receipt time.

  3. 3

    Derived live state can be rebuilt from ordered observations and commands.

  4. 4

    Trip closure never discards unresolved exceptions or data gaps.

  5. 5

    Every provider identifier is mapped to the internal trip and tenant.

Failure and recovery

Know what to do before it breaks

Recovery changes durable truth only through the same rules as normal operation. A timeout is an unknown outcome, not evidence that nothing happened.

Telemetry arrives late or out of order

Detect

Event time is behind the trip watermark or its sequence creates a gap.

Recover

Store raw input, recompute the bounded affected window, and publish a new derived revision.

Device stops reporting

Detect

Freshness exceeds the vehicle-specific health threshold.

Recover

Raise a connection exception, show last-known time explicitly, and avoid extrapolating authoritative position.

Close succeeds remotely but the response is lost

Detect

Internal trip remains closing while provider detail reports closed.

Recover

Reconciliation closes the internal aggregate with the original command identity.

Driver or vehicle assignment changes mid-trip

Detect

A control-plane version differs from the assignment captured at trip start.

Recover

Use an explicit transfer transition and retain both assignment intervals.

Operational telemetry

Observe the journey, not merely HTTP status

Measure state age, event health, retries, reconciliation, and sensitive-data access alongside latency and error rate.

  • Telemetry freshness, ordering lag, rejection, and quality
  • Active trips without a healthy assigned device
  • ETA error and route-deviation duration
  • Open exception age by severity and owner
  • Trips stuck in closing and reconciliation outcomes
  • Raw-to-derived lineage and revision count
Grounded implementation

Contracts, repositories, workshops, tutorials, and runnable evidence

Only explicitly indexed evidence is linked. Empty sections are not backfilled with invented endpoints or package names.