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

Rewritten-docs.md

@@ -454,9 +454,57 @@ and everybody seems happy about it. There are other communicating channels every
 user have available like email or git, but they are totally inappropriate for
 designing user interfaces on top of them.
 
-@todo: what type of users there should be, why they are needed
-
-@todo: groups, they can be public and private and why is that, what it solves, explain and discuss threshold and other group features
+The application interacts with users. From the project assignment is clear, that
+the system has to keep personalized data about users and adapt presented content
+according to this knowledge. User data cannot be publicly visible, so that
+implies necessity of user authentication. There are several way of
+auhtentication user in web applications. HTTP basic authentication has a few
+drawbacks like sending plain credentials in every request or no logout option,
+so it is not recommended to use. Using cookies is possible, but it is
+susceptible to various types of attacks including stealing and also brings state
+into stateless protocols as REST. Another option is using tokens, OAuth2 or JWT
+(JSON Web Token). Nowadays it is widely used and has only a few cons (need to
+make extra effort to mitigate XSS attacks). Additional option is usage of
+one-time passwords. These can be time or counter based and are mostly used for
+two-factor authentication. Since ReCodEx does not need to have military grade
+security, JWT tokens are used for authentication. However, two-factor
+authentication may come in next releases.
+
+User data also includes a privilege level. From the assignment it is required to
+have at least two roles, _student_ and _supervisor_. However, it is wise to add
+_administrator_ level, which takes care of the system as a whole and is
+responsible for core setup, monitoring, updates and so on. Student role has the
+least power, basically can just view assignments and submit solutions.
+Supervisors have more authority, so they can create exercises and assignments,
+view results of students etc. From the university organization, one possible
+level could be introduced, _course guarantor_. However, from real experience all
+duties related with lecturing of labs are already associtated with supervisors,
+so this role seems not so useful. In addition, no one requested more than three
+level privilege scheme.
+
+School labs are lessons for some students lead by one (or sometimes two or
+three) supervisors. Students have the same homeworks and supervisors are
+evaluating them. This organization has to be carried into the new system.
+Counterpart to real labs are virtual groups. This concept was already discussed
+in previous chapter including need for hierarchical structure of groups. Right
+for attending labs has only a person, who is student of the university and is
+recorded in university information system. To allow restriction of group members
+in ReCodEx, there two type of groups -- _public_ and _private_. Public groups
+are open for every registered users, but to become a member of private group one
+of its supervisors have to add that user. This could be done automatically at
+beginning of the term with data from information system, but unfortunately there
+is no such API yet. However, creating this API is now considered by university
+leadership. Another just as good solution for restricting membership of a group
+is to allow anyone join the group with supplementary confirmation of
+supervisors. It has no additional benefits, so approach with public and private
+groups is implemented.
+
+Supervisors using CodEx in their labs usually set minimum amout of points
+required to get a credit. These points can be get by solving assigned exercises.
+To visualy show users if they already have enough points, ReCodEx groups
+supports setting this limit. There are two equal ways how to set a limit --
+absolute value or relative value to maximum. The latter way seems nicer, so it
+is implemented. The relative value is set in percents and is called threashold.
 
 @todo: explain instances why they are useful what they solve and also discuss licenses concept
 
@@ -664,13 +712,52 @@ 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.
 
-### Backend communication
+### General communication
 
 @todo: what type of communication within backend could be used, mention some
 frameworks, queue managers, protocols, which was considered - why we don't use
 CORBA, RabbitMQ and why is ZeroMQ great
 
-@todo: maybe merge frontend communication into this
+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:
+
+- *TCP sockets* -- TCP sockets give a reliable means of a full-duplex
+  communication. All major operating systems support this protocol and there are
+  libraries which simplify the implementation.  On the other side, it is not
+  possible to initiate a TCP socket from a web browser.
+- *WebSockets* -- The WebSocket standard is built on top of TCP. It enables a
+  web browser to connect to a server over a TCP socket. WebSockets are
+  implemented in recent versions of all modern web browsers and there are
+  libraries for several programming languages like Python or JavaScript (running
+  in Node.js).  Encryption of the communication over a WebSocket is supported as
+  a standard.
+- *HTTP protocol* -- The HTTP protocol is a state-less protocol implemented on
+  top of the TCP protocol.  The communication between the client and server
+  consists of a requests sent by the client and responses to these requests sent
+  back by the sever. The client can send as many requests as needed and it may
+  ignore the responses from the server, but the server must respond only to the
+  requests of the client and it cannot initiate communication on its own.
+  End-to-end encryption can be achieved easily using SSL (HTTPS).
+
+We chose the HTTP(S) protocol because of the simple implementation in all sorts
+of operating systems and runtime environments on both the client and the server
+side.
+
+The API of the server should expose basic CRUD (Create, Read, Update, Delete)
+operations. There are some options on what kind of messages to send over the
+HTTP:
+
+- SOAP -- a protocol for exchanging XML messages. It is very robust and complex.
+- REST -- is a stateless architecture style, not a protocol or a technology. It
+  relies on HTTP (but not necessarily) and its method verbs (e.g., GET, POST,
+  PUT, DELETE). It can fully implement the CRUD operations.
+
+Even though there are some other technologies we chose the REST style over the
+HTTP protocol. It is widely used, there are many tools available for development
+and testing, and it is understood by programmers so 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.
 
 ### Broker
 
@@ -1055,49 +1142,6 @@ the monitor. To solve this, messages for each job are hold 5 minutes after
 reception of last message. The client gets all already received messages at time
 of connection with no message loss.
 
-
-### Frontend communication
-
-The first thing we need to address is the communication protocol of this
-client-server architecture. There are several options:
-
-- *TCP sockets* -- TCP sockets give a reliable means of a full-duplex
-  communication. All major operating systems support this protocol and there are
-  libraries which simplify the implementation.  On the other side, it is not
-  possible to initiate a TCP socket from a web browser.
-- *WebSockets* -- The WebSocket standard is built on top of TCP. It enables a
-  web browser to connect to a server over a TCP socket. WebSockets are
-  implemented in recent versions of all modern web browsers and there are
-  libraries for several programming languages like Python or JavaScript (running
-  in Node.js).  Encryption of the communication over a WebSocket is supported as
-  a standard.
-- *HTTP protocol* -- The HTTP protocol is a state-less protocol implemented on
-  top of the TCP protocol.  The communication between the client and server
-  consists of a requests sent by the client and responses to these requests sent
-  back by the sever. The client can send as many requests as needed and it may
-  ignore the responses from the server, but the server must respond only to the
-  requests of the client and it cannot initiate communication on its own.
-  End-to-end encryption can be achieved easily using SSL (HTTPS).
-
-We chose the HTTP(S) protocol because of the simple implementation in all sorts
-of operating systems and runtime environments on both the client and the server
-side.
-
-The API of the server should expose basic CRUD (Create, Read, Update, Delete)
-operations. There are some options on what kind of messages to send over the
-HTTP:
-
-- SOAP -- a protocol for exchanging XML messages. It is very robust and complex.
-- REST -- is a stateless architecture style, not a protocol or a technology. It
-  relies on HTTP (but not necessarily) and its method verbs (e.g., GET, POST,
-  PUT, DELETE). It can fully implement the CRUD operations.
-
-Even though there are some other technologies we chose the REST style over the
-HTTP protocolo. It is widely used, there are many tools available for
-development and testing, and it is understood by programmers so 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
 
 The API server must handle HTTP requests and manage the state of the application