From ade0936c6f31a7400fb34966d773826c9d7148c4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Krist=C3=B3f=20T=C3=B3th?= Date: Tue, 3 Apr 2018 17:41:19 +0200 Subject: [PATCH] Provide high-level documentation of event handlers and FSM --- README.md | 32 +++++++++++++++++++++++++++++--- 1 file changed, 29 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 2ec6302..fb58cc5 100644 --- a/README.md +++ b/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). -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). +### Event handlers + +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.