Structure of the project improved

Rewritten-docs.md

@@ -423,67 +423,97 @@ overview which part succeeded and which failed (optionally with reason like
 
 ### Structure of the project
 
-The ReCodEx project is divided into two logical parts – the *Backend*
+There are numerous ways how to divide some sort of system into separated
-and the *Frontend* – which interact which each other and which cover the
+services, from one single component to many and many single-purpose components.
-whole area of code examination. Both of these logical parts are
+Having only one big service is not feasible, not scalable enough and mainly it
-independent of each other in the sense of being installed on separate
+would be one big blob of code which somehow works and is very complex, so this
-machines at different locations and that one of the parts can be
+is not the way. The quite opposite, having a lot of single-purpose components is
-replaced with a different implementation and as long as the communication
+also somehow impractical. It is scalable by default and all services would have
-protocols are preserved, the system will continue working as expected.
+quite simple code but on the other hand communication requirements for such
-
+solution would be insane. So there has to be chosen approach which is somehow in
-*Backend* is the part which is responsible solely for the process of
+the middle, that means services have to communicate in manner which will not
-evaluation a solution of an exercise. Each evaluation of a solution is
+bring network down, code basis should be reasonable and the whole system has to
-referred to as a *job*. For each job, the system expects a configuration
+be scalable enough. With this being said there can be discussion over particular
-document of the job, supplementary files for the exercise (e.g., test
+division for ReCodEx system.
-inputs, expected outputs, predefined header files), and the solution of
+
-the exercise (typically source codes created by a student). There might
+The ReCodEx project is divided into two logical parts – the *backend* and the
-be some specific requirements for the job, such as a specific runtime
+*frontend* – which interact which each other and which cover the whole area of
-environment, specific version of a compiler or the job must be evaluated
+code examination. Both of these logical parts are independent of each other in
-on a processor with a specific number of cores. The backend
+the sense of being installed on separate machines at different locations and
-infrastructure decides whether it will accept a job or decline it based
+that one of the parts can be replaced with a different implementation and as
-on the specified requirements. In case it accepts the job, it will be
+long as the communication protocols are preserved, the system will continue
-placed in a queue and it will be processed as soon as possible. The backend
+working as expected.
-publishes the progress of processing of the queued jobs and the results
+
-of the evaluations can be queried after the job processing is finished.
+*Backend* is the part which is responsible solely for the process of evaluation
-The backend produces a log of the evaluation and scores the solution
+a solution of an exercise. Each evaluation of a solution is referred to as a
-based on the job configuration document.
+*job*. For each job, the system expects a configuration document of the job,
-
+supplementary files for the exercise (e.g., test inputs, expected outputs,
-*Frontend* on the other hand is responsible for the communication with
+predefined header files), and the solution of the exercise (typically source
-the users and provides them a convenient access to the Backend
+codes created by a student). There might be some specific requirements for the
-infrastructure. The Frontend manages user accounts and gathers them into
+job, such as a specific runtime environment, specific version of a compiler or
-units called groups. There is a database of exercises which can be
+the job must be evaluated on a processor with a specific number of cores. The
-assigned to the groups and the users of these groups can submit their
+backend infrastructure decides whether it will accept a job or decline it based
-solutions for these assignments. The Frontend will initiate evaluation
+on the specified requirements. In case it accepts the job, it will be placed in
-of these solutions by the Backend and it will store the results
+a queue and it will be processed as soon as possible. The backend publishes the
-afterwards. The results will be visible to authorized users and the
+progress of processing of the queued jobs and the results of the evaluations can
-results will be awarded with points according to the score given by the
+be queried after the job processing is finished.  The backend produces a log of
-Backend in the evaluation process. The supervisors of the groups can
+the evaluation and scores the solution based on the job configuration document.
-edit the parameters of the assignments, review the solutions and the
+
-evaluations in detail and award the solutions with bonus points (both
+From the scalable point of view there are two necessary components, the one
-positive and negative) and discuss about the solution with the author of
+which will execute jobs and component which will distribute jobs to the
-the solution. Some of the users can be entitled to create new exercises
+instances of the first one. This ensures scalability in manner of parallel
-and extend the database of exercises which can be assigned to the groups
+execution of numerous jobs which is exactly what is needed. Implementation of
-later on.
+these services are called **broker** and **worker**, first one handles
-
+distribution, latter execution. These components should be enough to fulfil all
-The Frontend developed as part of this project was created with the
+above said, but for the sake of simplicity and better communication gateways
-needs of the Faculty of Mathematics and Physics of the Charles
+with frontend two other components were added, **fileserver** and **monitor**.
-university in Prague in mind. The users are the students and their
+Fileserver is simple component whose purpose is to store files which are
-teachers, groups correspond to the different courses, the teachers are
+exchanged between frontend and backend. Monitor is also quite simple service
-the supervisors of these groups. We believe that this model is
+which is able to serve job progress state from worker to web application. These
-applicable to the needs of other universities, schools, and IT
+two additional services are on the edge of frontend and backend (like gateways)
-companies, which can use the same system for their needs. It is also
+but logically they are more connected with backend, so it is considered they
-possible to develop their own frontend with their own user management
+belong there.
-system for their specific needs and use the possibilities of the Backend
+
-without any changes, as was mentioned in the previous paragraphs.
+*Frontend* on the other hand is responsible for the communication with the users
-
+and provides them a convenient access to the backend infrastructure. The
-In the latter parts of the documentation, both of the Backend and
+frontend manages user accounts and gathers them into units called groups. There
-Frontend parts will be introduced separately and covered in more detail.
+is a database of exercises which can be assigned to the groups and the users of
-The communication protocol between these two logical parts will be
+these groups can submit their solutions for these assignments. The frontend will
-described as well.
+initiate evaluation of these solutions by the backend and it will store the
-
+results afterwards. The results will be visible to authorized users and the
-@todo: move "General backend implementation" here
+results will be awarded with points according to the score given by the Backend
-
+in the evaluation process. The supervisors of the groups can edit the parameters
-@todo: move "General frontend implementation" here
+of the assignments, review the solutions and the evaluations in detail and award
+the solutions with bonus points (both positive and negative) and discuss about
+the solution with the author of the solution. Some of the users can be entitled
+to create new exercises and extend the database of exercises which can be
+assigned to the groups later on.
+
+There are two main purposes of frontend -- holding the state of whole system
+(database of users, exercises, solutions, points, etc.) and presenting the state
+to users through some kind of an user interface (e.g., a web application, mobile
+application, or a command-line tool). According to contemporary trends in
+development of frontend parts of applications, we decided to split the frontend
+in two logical parts -- a server side and a client side. The server side is
+responsible for managing the state and the client side gives instructions to the
+server side based on the inputs from the user. This decoupling gives us the
+ability to create multiple client side tools which may address different needs
+of the users.
+
+The frontend developed as part of this project is a web application created with
+the needs of the Faculty of Mathematics and Physics of the Charles university in
+Prague in mind.  The users are the students and their teachers, groups
+correspond to the different courses, the teachers are the supervisors of these
+groups. We believe that this model is applicable to the needs of other
+universities, schools, and IT companies, which can use the same system for their
+needs. It is also possible to develop their own frontend with their own user
+management system for their specific needs and use the possibilities of the
+Backend without any changes, as was mentioned in the previous paragraphs.
+
+In the latter parts of the documentation, both of the backend and frontend parts
+will be introduced separately and covered in more detail.  The communication
+protocol between these two logical parts will be described as well.
+
 
 ### Evaluation unit executed on backend
 
@@ -574,34 +604,7 @@ This discussion is a never ending story which is done through the whole
 development process. Some of the most important implementation problems or
 interesting observations will be discussed in this chapter.
 
-### General backend implementation
+### Backend communication
-
-There are numerous ways how to divide some sort of system into separated
-services, from one single component to many and many single-purpose components.
-Having only one big service is not feasible, not scalable enough and mainly it
-would be one big blob of code which somehow works and is very complex, so this
-is not the way. The quite opposite, having a lot of single-purpose components is
-also somehow impractical. It is scalable by default and all services would have
-quite simple code but on the other hand communication requirements for such
-solution would be insane. So there has to be chosen approach which is somehow in
-the middle, that means services have to communicate in manner which will not
-bring network down, code basis should be reasonable and the whole system has to
-be scalable enough. With this being said there can be discussion over particular
-division for ReCodEx system.
-
-From the scalable point of view there are two necessary components, the one
-which will execute jobs and component which will distribute jobs to the
-instances of the first one. This ensures scalability in manner of parallel
-execution of numerous jobs which is exactly what is needed. Implementation of
-these services are called 'broker' and 'worker', first one handles distribution,
-latter execution. These components should be enough to fulfil all above said,
-but for the sake of simplicity and better communication gateways with frontend
-two other components were added, 'fileserver' and 'monitor'. Fileserver is
-simple component whose purpose is to store files which are exchanged between
-frontend and backend. Monitor is also quite simple service which is able to
-serve job progress state from worker to web application. These two additional
-services are on the edge of frontend and backend (like gateways) but logically
-they are more connected with backend, so it is considered they belong there.
 
 @todo: what type of communication within backend could be used, mention some frameworks, queue managers, protocols, which was considered
 
@@ -760,21 +763,7 @@ reception of last message. The client gets all already received messages at time
 of connection with no message loss.
 
 
-### General frontend implementation
+### Frontend communication
-
-The frontend is the part of the whole system, which is directly available to the user.
-It must hold the whole state of the system - the login credentials, users' data, hierarchy
-of groups, available exercises, exercises assignments, users' solutions, and much more.
-User must be able to access and modify this state through some kind of an user interface
-(e.g., a web application, mobile application, or a command-line tool). We want to implement
-a web application as part of this project, but we want to make it possible for other
-developers to contribute to the platform and to create their specific clients for
-their specific needs.
-
-We decided to split the frontend in two logical parts: a server side and a client side.
-The server side is responsible for managing the state and the client side gives instructions
-to the server side based on the inputs from the user. This decoupling gives us the ability
-to create multiple client side tools which may address different needs of the users.
 
 The first thing we need to address is the communication protocol of this client-server
 architecture. There are several options:
@@ -807,7 +796,7 @@ used, there are many tools available for development and testing, and it is unde
 it should be easy for a new developer with some experience in client-side applications to get to know with
 the ReCodEx API and develop a client application.
 
-#### API server
+### API server
 
 The API server must handle HTTP requests and manage the state of the application in some kind of a database.
 It must also be able to communicate with the backend over ZeroMQ.
@@ -858,7 +847,7 @@ Nette framework which makes usage of Doctrine 2 very straighforward.
 
 @todo: on demand loading of students submission, in-time loading of every other submission, why
 
-#### Web-app
+### Web-app
 
 @todo: what technologies can be used on client frontend side, why react was used