Documentation for the state machine overhaul

Diagrams and accompanying document describing why we're making these changes.