radiodan/magic-button — pull request #5 by pixelblend (2014-11-04 17:37:44+00:00)
Title: State Refactoring

# Aim

The magic button state machine was in quite a state, with tonnes of objects being passed all over the system and a complicated `handlers` ecosystem. Hopefully this refactoring has simplified things a bit.

# New objects

## Device
This is object that represents the internal state of the radio. It sets up the objects below, and returns an instance of the `state` object. This object is how other elements of the system interact with the radio.

## Action Manager
Creates an instance of `action-register`, and instantiates the `action` objects, passing in `players`, `physical-ui`, `services` and `event-bus`.

## Action Register
Registers actions against the states they wish to be applied to. Marshals the collected actions into a format that `state` will accept.

## Actions
These detail the functionality that can be triggered within each state of the device. This is where `radiodan` objects and manipulated and commands are sent out to the server.
Examples: `lib/actions/play`, `lib/actions/avoid`, `lib/actions/standby`

## Shutdown
Handles shutdown and restart of the physical device (if on a Pi, and `cease` is running). Creates an instance of the `radiodan.device` object, is not exposed to the rest of the system.

## Physical UI
Creates the Physical UI objects from `radiodan-client`. This is passed to the `action` objects. This is the only time these objects are created.

## Players
See `Physical UI`.

## State

This still uses `machina`, but the number of potential states are massively simplified. At this time, I do not see the need to add any new ones. They are:

* standby
* online
* shutdown
* restart

Only `online` should be necessary for any given magic button functionality. Other areas of the system (like the web app routes), interact with the state machine by asking it to handle certain messages, which are then handled by the `actions`.