Provide high-level documentation of event handlers and FSM

README.md

@@ -15,9 +15,35 @@ The goal of the tutorial-framework is to help content developers in creating int
 To make this possible TFW implements a robust messaging system and provides several pre-written components built upon it, such as a file editor or a terminal (running in your browser).
 
 The foundation of the whole framework is the messaging system connecting the frontend with the backend.
-Frontend components use websockets to connect to TFW, which you can hook to several *event handlers* to define ways to handle specific messages.
+Frontend components use websockets to connect to TFW, to which you can hook several *event handlers* defining how to handle specific messages.
 
 ![TFW architecture](docs/tfw_architecture.png)
 
-Note that our reference frontend implementation is written in Angular (`frontend-tutorial-framework` repository).
+### Event handlers
-Most of pre-made `EventHandler`s are writen in Python3, but you can write event handlers in any language that has ZeroMQ bindings (this virtually means any language).
+
+Imagine event handlers as callbacks that are executed when TFW receives a specific type of message. For example you could send a message to the framework when the user does something of note.
+
+This allows you to define actions triggered on the backend when the user presses a button on the frontend, moves the cursor to a specific area or anything like that.
+
+Event handlers use ZeroMQ to connect to the framework. They are as loosely-coupled as possible: usually they are running in separate processes and only communicate with TFW through ZMQ.
+
+Most of pre-made event handlers are writen in Python3, but you can write event handlers in any language that has ZeroMQ bindings (this means virtually any language).
+
+This makes the framework really flexible: you can demonstrate the concepts you want to in any language while using the same set of tools provided by TFW.
+
+### FSM
+
+Another unique feature of the framework is the FSM – finite state machine – representing the state of your challenge.
+This allows you to track users progressing with the tasks you've defined for them to complete.
+
+For instance you could represent whether the user managed to create a malicious user with a state called `user_registered` and subscribe callbacks to events regarding that state (like entering or leaving).
+
+You could create challenges that can be completed in several different ways: imagine a state called `challenge_complete`, which represents when the challenge is completed. Several series of actions could lead to this state.
+
+This enables you to guide your users through the experience you've envisioned with your tutorial.
+We can provide a whole new level of interactivity in our challenges because we know what the user is doing.
+This includes context-dependent hints and the automatic typing of commands to a terminal.
+
+### Frontend
+
+Note that our frontend implementation is written in Angular. It is maintained and documented in the `frontend-tutorial-framework` repository.