Merge branch 'master' of https://github.com/ReCodEx/wiki.wiki

Rewritten-docs.md

@@ -875,7 +875,7 @@ protocol between these two logical parts will be described as well.
 Some of the most important implementation problems or interesting observations
 will be discussed in this chapter.
 
-### General communication
+### Communication between the backend components
 
 Overall design of the project is discussed above. There are bunch of components
 with their own responsibility. Important thing to design is communication of
@@ -893,26 +893,39 @@ Often way to reflect these reproaches is to use some framework which provides
 better abstraction and more suitable API. We decided to go this way, so the
 following options are considered:
 
-- CORBA -- Corba is a well known framework for remote object invocation. There
-  are multiple implementations for almost every known programming language. It
-  fits nicely into object oriented programming environment.
+- CORBA (or some other form of RPC) -- CORBA is a well known framework for
+  remote procedure calls. There are multiple implementations for almost every
+  known programming language. It fits nicely into object oriented programming
+  environment.
 - RabbitMQ -- RabbitMQ is a messaging framework written in Erlang. It has
-  bindings to huge number of languages and large community. Also, it is capable
-  of routing requests, which could be handy feature for job loadbalancing.
-- ZeroMQ -- ZeroMQ is another messaging framework, but instead of creating
-  separate service this is a small library which can be embedded into own
-  projects. It is written in C++ with huge number of bindings. 
-
-We like CORBA, but our system should be more loosely-coupled, so (asynchronous)
-messaging is better approach in our minds. RabbitMQ seems nice with great
-advantage of routing capability, but it is quite heavy service written in
-language no one from the team knows, so we do not like it much. ZeroMQ is the
-best option for us. However, all of the three options would have been possible
-to use.
-
-Frontend communication follows the choice, that ReCodEx should be primary a web
-application. The communication protocol has to reflect client-server
-architecture. There are several options:
+  bindings to a large number of languages and large community. Also, it is
+  capable of routing requests, which could be handy feature for job
+  load-balancing.
+- ZeroMQ -- ZeroMQ is another messaging framework, which is different from
+  RabbitMQ and others (such as ActiveMQ) because it features a "brokerless
+  design". This means there is no need to launch a message broker service to
+  which clients have to connect -- ZeroMQ based clients are capable of
+  communicating directly. However, it only provides an interface for passing
+  messages (basically vectors of 255B strings) and any additional features such
+  as load balancing or acknowledgement schemes have to be implemented on top of
+  this. The ZeroMQ library is written in C++ with a huge number of bindings. 
+
+CORBA is a large framework that would satisfy all our needs, but we are aiming
+towards a more loosely-coupled system, and asynchronous messaging seems better
+for this approach than RPC. RabbitMQ seems nice with great advantage of routing
+capability, but it is a quite heavy service written in language no one from the
+team knows, so we do not like it much. ZeroMQ is the best option for us, even
+with the drawback of having to implement a load balancer ourselves (which could
+also be seen as a benefit). However, all of the three options would have been
+possible to use.
+
+### Frontend - backend communication
+
+Our choices when considering how clients will communicate with the backend has
+to stem from the fact that ReCodEx should primarily be a web application. This
+rules out ZeroMQ -- while it is very useful for asynchronous communication
+between backend components, it is practically impossible to use it from a web
+browser. There are several other options:
 
 - *TCP sockets* -- TCP sockets give a reliable means of a full-duplex
   communication. All major operating systems support this protocol and there are
@@ -1294,13 +1307,13 @@ term project for C# course so it might be written and integrated in future.
 
 The fileserver provides access to a shared storage space that contains files
 submitted by students, supplementary files such as test inputs and outputs and
-results of evaluation. In other words, it acts as an intermediate node for data
-passed between the frontend and the backend. This functionality can be easily
-separated from the rest of the backend features, which led to designing the
-fileserver as a standalone component. Such design helps encapsulate the details
-of how the files are stored (e.g. on a file system, in a database or using a
-cloud storage service), while also making it possible to share the storage
-between multiple ReCodEx frontends.
+results of evaluation. In other words, it acts as an intermediate storage node
+for data passed between the frontend and the backend. This functionality can be
+easily separated from the rest of the backend features, which led to designing
+the fileserver as a standalone component. Such design helps encapsulate the
+details of how the files are stored (e.g. on a file system, in a database or
+using a cloud storage service), while also making it possible to share the
+storage between multiple ReCodEx frontends.
 
 For early releases of the system, we chose to store all files on the file system
 -- it is the least complicated solution (in terms of implementation complexity)