small documentation on how the state machine works.