AdminConsole
Stateful journeys/Routes & Navigation
hybridnavigation session aggregate
Navigation · device session lifecycle

Recoverable navigation session

Move from route intent through preview, guidance, reroute, arrival, and cleanup while surviving process, sensor, and network interruption.

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
draft

Draft

Origin, destination, stops, vehicle profile, and constraints are incomplete or editable.

02
preview

Preview

Alternatives and trade-offs are visible but guidance and sensor use have not started.

03
navigating

Navigating

Guidance owns an active route and consumes position, progress, traffic, and user commands.

04
rerouting

Rerouting

The active route is temporarily superseded by a recalculation caused by deviation, traffic, or destination change.

05
arrived

Arrived

Arrival policy passed and the application is waiting for confirmation or final trip actions.

06
endedterminal

Ended

Sensors, audio, observers, foreground services, and SDK session resources are released.

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
calculate_routeNavigation application
draftpreview
previewroute.calculated

Hash normalized intent and constraints for request deduplication and caching.

start_guidanceDriver
preview
navigatingnavigation.started

Persist a session command ID before starting foreground resources.

request_rerouteNavigation application
navigatingrerouting
reroutingreroute.requested

Coalesce equivalent deviations while one calculation is outstanding.

accept_rerouteMappls navigation SDK
rerouting
navigatingroute.updated

Apply only a response matching the latest route-intent version.

confirm_arrivalNavigation application
navigating
arrivednavigation.arrived

Arrival policy version and stop ID form the stable key.

end_sessionDriver
previewnavigatingreroutingarrived
endednavigation.ended

Cleanup must tolerate repeated calls and partial startup.

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.

Route intent

Portable origin, stops, profile, constraints, and version.

intentIdversionwaypointsprofileconstraints

Session checkpoint

Minimal recoverable progress without persisting unsafe SDK internals.

sessionIdintentVersionrouteIdlegIndexlastPositionTime

Navigation trace

Privacy-bounded operational and quality evidence.

sessionIdeventTypeoccurredAtrouteVersionquality
Non-negotiable rules

Protect truth at the aggregate boundary

  1. 1

    Only one guidance session owns foreground navigation resources at a time.

  2. 2

    Every route result is applied only to the intent version that requested it.

  3. 3

    The last valid route remains available while a reroute is pending.

  4. 4

    Arrival requires an explicit distance, speed, dwell, and stop policy.

  5. 5

    End releases every observer, sensor, audio, and service resource exactly once in effect.

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.

Application process is killed

Detect

A persisted active checkpoint exists without a live runtime owner.

Recover

Recreate resources, validate destination intent, recalculate if stale, and ask before resuming guidance.

GNSS quality degrades

Detect

Accuracy, age, speed consistency, or map-matching confidence crosses policy.

Recover

Surface degraded positioning, use supported dead-reckoning inputs, and avoid false reroutes.

Reroute response arrives after destination changed

Detect

Response intent version is older than the active intent.

Recover

Discard it and keep the latest calculation; never apply by arrival order alone.

Network disappears

Detect

Online route, traffic, or search dependency fails while local guidance remains active.

Recover

Keep last valid guidance, expose freshness, and use entitled offline capability when available.

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.

  • Route calculation latency and alternative selection
  • Position age, accuracy, and map-matching confidence
  • Reroute cause, time, cancellation, and supersession
  • Guidance session starts without matching cleanup
  • Arrival false-positive and manual-override rate
  • Crash/restart recovery outcome
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.