From 96982dfdcf06fa30ed205333ed5a6be456e1aee9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Krist=C3=B3f=20T=C3=B3th?= <kristof.toth@avatao.com>
Date: Sat, 1 Dec 2018 16:39:05 +0100
Subject: [PATCH] Add chapter explaining components

---
 content/a_tour_of_tfw.tex | 62 +++++++++++++++++++++++++++++++++++++++
 content/architecture.tex  |  4 +--
 thesis.tex                |  1 +
 3 files changed, 65 insertions(+), 2 deletions(-)
 create mode 100644 content/a_tour_of_tfw.tex

diff --git a/content/a_tour_of_tfw.tex b/content/a_tour_of_tfw.tex
new file mode 100644
index 0000000..73371ba
--- /dev/null
+++ b/content/a_tour_of_tfw.tex
@@ -0,0 +1,62 @@
+\chapter{A Tour of TFW}
+
+The purpose of this chapter is to further detail the built-in components
+provided by the framework.
+As previously mentioned, these components are implemented as event handlers 
+running in the \texttt{solvable} Docker container and frontend
+components written in Angular.
+For instance the built-in code editor requires a frontend component and an event
+handler to function properly, while the frontend component responsible for
+drawing out and managing other components implement no
+event handler.
+
+In the Tutorial Framework most of the built-ins define APIs, which are TFW messages
+that can be used to interact with them.
+For example, to inject a command into the terminal one would use a message like this:
+\begin{lstlisting}[captionpos=b,caption={An API Message Capable of Writing in the Terminal}]
+{ 
+    "key": "shell",
+    "data":
+    {
+        "command": "write",
+        "value": "echo 'Hello TFW World!'\n"
+    }
+}
+\end{lstlisting}
+Notice the \texttt{``\\n''} at the end of the command.
+By including a newline character, we are also capable of executing commands in the
+user's terminal.
+Were this newline omitted, the command would only be written to the terminal
+(but not automatically executed) for users to inspect and potentially execute themselves.
+
+Some components emit or broadcast messages on specific events, for instance the
+\texttt{FSMManagingEventHandler} broadcasts the following message on state transitions:
+\begin{lstlisting}[captionpos=b,caption={An FSM Update message}]
+{
+    "key": "fsm_update",
+    "data" :
+    {
+        "current_state": ...string...,
+        "valid_transitions": ...[array of {"trigger": ...string...} objects]...,
+        "in_accepted_state": ...boolean...,
+        "last_event": ...
+                      object like
+                      {
+                          "from_state": ...string...,
+                          "to_state": ...string...,
+                          "trigger": ...string...,
+                          "timestamp": ...unix timestamp...
+                      }
+                      ...
+    }
+}
+\end{lstlisting}
+As you can see this message contains loads of useful information regarding what is
+exactly happening in the tutorial at a given point and can be used by client code
+to make informed decisions based on this knowledge.
+
+It is not the purpose of this text to provide a complete API documentation, so in the
+following I am only going to explain possibilities provided by given components rather
+than showcasing actual, real-life API messages.
+
+\section{Messages component}
diff --git a/content/architecture.tex b/content/architecture.tex
index 4cccf0b..83c9c1e 100644
--- a/content/architecture.tex
+++ b/content/architecture.tex
@@ -10,7 +10,7 @@ two Docker images:
           whether the user completed the tutorial or not)
 \end{itemize}
 During most of this capter I am going to be discussing the \texttt{solvable} Docker image,
-with the exception of section \ref{solutioncheck}, where I will dive into how the
+with the exception of section~\ref{solutioncheck}, where I will dive into how the
 \texttt{controller} image is implemented.
 
 The most important feature of the framework is it's messaging system.
@@ -355,7 +355,7 @@ field is designed for).
 In this case the TFW server will only forward privileged messages that
 have a valid signature.
 
-\subsection{Solution checking}
+\subsection{Solution checking}\label{solutioncheck}
 
 Traditionally most challenges on the Avatao platform implement a Docker image called
 \texttt{controller}, which is responsible for detecting the successful
diff --git a/thesis.tex b/thesis.tex
index 26c3b45..25cfe70 100644
--- a/thesis.tex
+++ b/thesis.tex
@@ -43,6 +43,7 @@
 \include{content/abstract}
 \include{content/introduction}
 \include{content/architecture}
+\include{content/a_tour_of_tfw}
 
 \listoffigures
 \lstlistoflistings{}