Journey flow control

Each user journey is subject to strict flow control rules that determine how a user can move through the application.

The application has three components that govern flow control:

• Journey definition
• Journey middleware
• State machine

Journey definition

Registering a journey defines a sequence of steps that forms the basis of the journey's flow control. The order of steps dictates the order that a user must progress through the application.

The flow control of each journey is independent of any other registered journey.

Constant journey paths

Three routes are defined by default when a journey definition is registered:

• /check-answers
• /terms-and-conditions
• /confirm

These paths are also prefixed using the journey pathPrefix property when a journey is registered.

Journey middleware

A series of middleware is applied to each route registered for a journey. Every time a journey route is requested the request is piped through this middleware.

The application uses POST -> REDIRECT -> GET for handling requests to journey routes. The registered middleware is slightly different for GET and POST requests.

The journey middleware uses the state machine, and data stored in the session and on the request, to determine the redirect.

There are two types of journey middleware:

Constant middleware

This middleware is not configurable and always applied to every route.

Optional middleware

This middleware is defined when a step is registered and enables unique behaviour for each step. This middleware is optional for each step. See defining a step for more information.

State machine

A journey has a lifecycle that consists of three possible states:

• IN_PROGRESS
• IN_REVIEW
• COMPLETED

When a journey route is requested, the middleware will query the state machine to find out what actions are allowed given the active state of the journey. The state machine in turn accesses the session to return a suitable response to the calling code.

The state machine has 6 valid actions:

• GET_NEXT_PATH
• IS_PATH_ALLOWED
• GET_NEXT_ALLOWED_PATH
• SET_NEXT_ALLOWED_PATH
• INCREMENT_NEXT_ALLOWED_PATH
• INVALIDATE_REVIEW

These actions are dispatched at various points during the request / response pipeline to determine the flow control of the journey.

Directly setting state for a journey

Custom middleware should not call the state machine directly. This is the domain of the constant middleware. The step schema provides an API that abstracts knowledge of the state machine away from the step's optional middleware.

It is however possible to call the state machine or set the state of the journey directly from a step's optional middleware:

// steps/my-step.js
const { stateMachine, states } = require('./flow-control')

// Only implement if absolutely necessary
const myStep = {
  ...
  behaviourForPost: (config, journey, step) => (req, res, next) => {
    stateMachine.setState(states.IN_PROGRESS, req, journey)
    next()
  }
}