API analysis - architecture and authentication

Rewritten-docs.md

@@ -208,7 +208,7 @@ System features represents directly accessible functionality to users of the
 system.  They describe the evaluation system in general and also university
 addons (mostly administrative features).
 
-#### Pure user requirements
+#### Requirements of the users
 
 - users have their own account in the system
 - system users can be members of multiple groups (reflecting courses or labs)
@@ -908,9 +908,47 @@ patterns used in this framework (e.g., dependency injection, authentication,
 routing). There is a good extension for the Nette framework which makes usage of
 Doctrine 2 very straightforward.
 
-@todo: what database can be used, how it is mapped and used within code
+#### Architecture of the system
-
+
-@todo: authentication, some possibilities and describe used jwt
+The Nette framework is an MVP (Model, View, Presenter) framework. It has many
+tools for creating complex websites and we need only a subset of them or we use
+different libraries which suite our purposes better:
+
+- **Model** - the model layer is implemented using the Doctrine 2 ORM insead of
+Nette Database
+- **View** - the whole view layer of the Nette framework (e.g., the Latte engine
+used for HTML template rendering) is unnecessary since we will return all the
+responses encoded in JSON. JSON is a common format used in APIs and we decided
+to prefer it to XML or a custom format.
+- **Presenter** - the whole lifecycle of a request processing of the Nette
+framework is used. The Presenters are used to group the logic of the individual
+API endpoints. The routing mechanism is modified to distinguish the actions by
+both the URL and the HTTP method of the request.
+
+#### Authentication
+
+To make certain data and actions acessible only for some specific users, there
+must be a way how these users can prove their identity. We decided to avoid
+PHP sessions to make the server stateless (session ID is stored in the cookies
+of the HTTP requests and responses). The server issues a specific token for the
+user after his/her identity is verified (i.e., by providing email and password)
+and sent to the client in the body of the HTTP response. The client must remember
+this token and attach it to every following request in the *Authorization* header.
+
+The token must be valid only for a certain time period ("log out" the user after
+a few hours of inactivity) and it must be protected against abuse (e.g., an attacker
+must not be able to issue a token which will be considered valid by the system and
+using which the attacker could pretend to be a different user). We decided to use
+the JWT standard (the JWS).
+
+The JWT is a base64-encoded string which contains three JSON documents - a header,
+some payload, and a signature. The interesting parts are the payload and the signature:
+the payload can contain any data which can identify the user and metadata of the token
+(i.e., the time when the token was issued, the time of expiration). The last part is a
+digital signature contains a digital signature of the header and payload and it
+ensures that nobody can issue their own token and steal someone's identity. Both of
+these characteristics give us the opportunity to validate the token without storing
+all of the tokens in the database.
 
 @todo: solution of forgotten password, why this in particular