added project state diagram

README.md

@@ -194,5 +194,46 @@ Further reading: [Stack Overflow](https://stackoverflow.com/questions/46602286/n
 You can publish the GUI to github.io so that others on the Internet can view it.
 [Read the wiki for a step-by-step guide.](https://github.com/LLK/scratch-gui/wiki/Publishing-to-GitHub-Pages)
 
+## Understanding the project state machine
+
+Since so much code throughout scratch-gui depends on the state of the project, which goes through many different phases of loading, displaying and saving, we created a "finite state machine" to make it clear which state it is in at any moment. This is contained in the file src/reducers/project-state.js .
+
+It can be hard to understand the code in src/reducers/project-state.js . There are several types of data and functions used, which relate to each other:
+
+### Loading states
+
+These include state constant strings like:
+
+* `NOT_LOADED` (the default state),
+* `ERROR`,
+* `FETCHING_WITH_ID`,
+* `LOADING_VM_WITH_ID`,
+* `REMIXING`,
+* `SHOWING_WITH_ID`,
+* `SHOWING_WITHOUT_ID`,
+* etc.
+
+### Transitions
+
+These are names for the action which causes a state change. Some examples are:
+
+* `START_FETCHING_NEW`,
+* `DONE_FETCHING_WITH_ID`,
+* `DONE_LOADING_VM_WITH_ID`,
+* `SET_PROJECT_ID`,
+* `START_AUTO_UPDATING`,
+
+### How transitions relate to loading states
+
+As this diagram of the project state machine shows, various transition actions can move us from one loading state to another:
+
+![Project state diagram](docs/project_state_diagram.svg)
+
+For example, suppose the project state machine is currently in the `FETCHING_WITH_ID` state.
+
+If the project state machine is given the `DONE_FETCHING_WITH_ID` action, the state will transition to the `LOADING_VM_WITH_ID` state. As part of that transition, it will store the `projectData` that it fetched while in the `FETCHING_WITH_ID` state.
+
+Once in the `LOADING_VM_WITH_ID` state, the `projectData` object is loaded into Scratch's virtual machine (the "vm"). Next, the `DONE_LOADING_VM_WITH_ID` action transitions the state from `LOADING_VM_WITH_ID` to `SHOWING_WITH_ID`. In this state, the project appears playable to the user.
+
 ## Donate
 We provide [Scratch](https://scratch.mit.edu) free of charge, and want to keep it that way! Please consider making a [donation](https://secure.donationpay.org/scratchfoundation/) to support our continued engineering, design, community, and resource development efforts. Donations of any size are appreciated. Thank you!