clearer communication analysis

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
+- CORBA (or some other form of RPC) -- CORBA is a well known framework for
-  are multiple implementations for almost every known programming language. It
+  remote procedure calls. There are multiple implementations for almost every
-  fits nicely into object oriented programming environment.
+  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
+  bindings to a large number of languages and large community. Also, it is
-  of routing requests, which could be handy feature for job loadbalancing.
+  capable of routing requests, which could be handy feature for job
-- ZeroMQ -- ZeroMQ is another messaging framework, but instead of creating
+  load-balancing.
-  separate service this is a small library which can be embedded into own
+- ZeroMQ -- ZeroMQ is another messaging framework, which is different from
-  projects. It is written in C++ with huge number of bindings. 
+  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
-We like CORBA, but our system should be more loosely-coupled, so (asynchronous)
+  which clients have to connect -- ZeroMQ based clients are capable of
-messaging is better approach in our minds. RabbitMQ seems nice with great
+  communicating directly. However, it only provides an interface for passing
-advantage of routing capability, but it is quite heavy service written in
+  messages (basically vectors of 255B strings) and any additional features such
-language no one from the team knows, so we do not like it much. ZeroMQ is the
+  as load balancing or acknowledgement schemes have to be implemented on top of
-best option for us. However, all of the three options would have been possible
+  this. The ZeroMQ library is written in C++ with a huge number of bindings. 
-to use.
+
-
+CORBA is a large framework that would satisfy all our needs, but we are aiming
-Frontend communication follows the choice, that ReCodEx should be primary a web
+towards a more loosely-coupled system, and asynchronous messaging seems better
-application. The communication protocol has to reflect client-server
+for this approach than RPC. RabbitMQ seems nice with great advantage of routing
-architecture. There are several options:
+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
+results of evaluation. In other words, it acts as an intermediate storage node
-passed between the frontend and the backend. This functionality can be easily
+for data passed between the frontend and the backend. This functionality can be
-separated from the rest of the backend features, which led to designing the
+easily separated from the rest of the backend features, which led to designing
-fileserver as a standalone component. Such design helps encapsulate the details
+the fileserver as a standalone component. Such design helps encapsulate the
-of how the files are stored (e.g. on a file system, in a database or using a
+details of how the files are stored (e.g. on a file system, in a database or
-cloud storage service), while also making it possible to share the storage
+using a cloud storage service), while also making it possible to share the
-between multiple ReCodEx frontends.
+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)