Project structure update

Rewritten-docs.md

@@ -794,15 +794,17 @@ approaches are equally good, final decision depends on actual case.
 
 ## Structure of the project
 
-The ReCodEx project is divided into two logical parts – the *backend* and the
-*frontend* – which interact which each other and which cover the whole area of
-code examination. Both of these logical parts are independent of each other in
-the sense of being installed on separate machines at different locations and
+The ReCodEx project is divided into two logical parts -- the *backend* and the
+*frontend* -- which interact with each other and together cover the whole area
+of code examination. Both of these logical parts are independent of each other
+in the sense of being installed on separate machines at different locations and
 that one of the parts can be replaced with a different implementation and as
 long as the communication protocols are preserved, the system will continue
 working as expected.
 
-*Backend* is the part which is responsible solely for the process of evaluation
+### Backend
+
+Backend is the part which is responsible solely for the process of evaluation
 a solution of an exercise. Each evaluation of a solution is referred to as a
 *job*. For each job, the system expects a configuration document of the job,
 supplementary files for the exercise (e.g., test inputs, expected outputs,
@@ -815,58 +817,48 @@ on the specified requirements. In case it accepts the job, it will be placed in
 a queue and it will be processed as soon as possible. The backend publishes the
 progress of processing of the queued jobs and the results of the evaluations can
 be queried after the job processing is finished. The backend produces a log of
-the evaluation and scores the solution based on the job configuration document.
+the evaluation which can be used for further score calculation or debugging.
 
 To make the backend scalable, there are two necessary components -- the one
 which will execute jobs and the other 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 fulfill 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.
-
-*Frontend* on the other hand is responsible for the communication with the users
-and provides them a convenient access to the backend infrastructure. The
-frontend manages user accounts and gathers them into units called groups. There
-is a database of exercises which can be assigned to the groups and the users of
-these groups can submit their solutions for these assignments. The frontend will
-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
-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
-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.
+execution of numerous jobs. Implementation of these services are called
+**broker** and **worker**, the first one handles distribution, the latter one
+execution. These components could handle the whole evaluation process, but for
+cleaner design 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 a simple service which is able to serve job progress
+state from worker to web application. These two additional components 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.
+
+### Frontend
+
+Frontend on the other hand is responsible for providing users a convenient
+access to the backend infrastructure and interpreting raw data from backend
+evaluation. 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 with preserving single server
+side component.
 
 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.
+to the different courses, the teachers are the supervisors of these groups. 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 a custom frontend with own user management system and use the
+possibilities of the backend without any changes.
+
+### Possible connection
 
 One possible configuration of ReCodEx system is illustrated on following
 picture, where there is one shared backend with three workers and two separate