web app - implementation - progress

Rewritten-docs.md

@@ -1685,7 +1685,7 @@ There are two basic ways how to create a website these days:
   over the UI and a more sophisticated user interactions with the UI can be
   achieved.
 
-All of these approaches are used in production by the web developers and all
+All of these are used in production by the web developers and all
 of them are well documented and there are mature tools for creating websites
 using any of these approaches.
 
@@ -1744,28 +1744,6 @@ the Bootstrap components for React and with the stylesheets from AdminLTE the
 application looks good and is distingushable form the many websites using the
 Bootstrap framework with very little work.
 
-#### WebApp Architecture
-
-The whole project is written using the next generation of JavaScript referred to
-as *ECMAScript 6* (also known as *ES6*, *ES.next*, or *Harmony*). Since not all
-of the features introduced in this standard are implemented in the modern
-web browsers of today (like classes and the spread operator) and hardly any are
-implemented in the older versions of the web browsers which are currently still
-in use, the source code is transpiled into the older standard *ES5* using
-[Babel.js](https://babeljs.io/) transpiler and bundled into a single script file
-using the [webpack](https://webpack.github.io/) moudle bundler. The need for a
-transpiler also arises from the usage of the *JSX* syntax for declaring React
-components. To read more about these these tools and their usage please refer to
-the [installation documentation](#Installation). The whole bundling process
-takes place at deployment and is not repeated afterwards when running in
-production.
-
-##### State Management
-
-@todo: Describe how Redux works
-@todo: Describe where which part of the state is persisted (logged in user) and how
-
-
 # User Documentation
 
 Users interact with the ReCodEx through the web application. It is required to
@@ -3106,11 +3084,84 @@ Swagger UI can be used to access the API directly.
 
 ## Web Application
 
-@todo: what to mention:
+The whole project is written using the next generation of JavaScript referred to
-	- used libraries, JSX, ...
+as *ECMAScript 6* (also known as *ES6*, *ES.next*, or *Harmony*). Since not all
-	- usage in user doc
+of the features introduced in this standard are implemented in the modern
-	- server side rendering
+web browsers of today (like classes and the spread operator) and hardly any are
-	- maybe more ...
+implemented in the older versions of the web browsers which are currently still
+in use, the source code is transpiled into the older standard *ES5* using
+[Babel.js](https://babeljs.io/) transpiler and bundled into a single script file
+using the [webpack](https://webpack.github.io/) moudle bundler. The need for a
+transpiler also arises from the usage of the *JSX* syntax for declaring React
+components. To read more about these these tools and their usage please refer to
+the [installation documentation](#Installation). The whole bundling process
+takes place at deployment and is not repeated afterwards when running in
+production.
+
+### State Management
+
+Web application is a SPA (Single Page Application. When the user accesses the page,
+the source codes are downloaded and are interpreted by the web browser. The communication
+between the browser and the server then runs in the background without reloading the page.
+
+The application keeps its internal state which can be altered by the actions of the user
+(e.g., clicking on links and buttons, filling input fields of forms) and by the outcomes
+of HTTP requests to the API server. This internal state is kept in memory of the web
+browser and is not persisted in any way -- when the page is refreshed, the internal state
+is deleted and a new one is created from scratch (i.e., all of the data is fetched from the
+API server again).
+
+The only part of the state which is persisted is the token of the logged in user. This token
+is kept in cookies and in the local storage. Keeping the token in the cookies is necessary
+for server-side rendering.
+
+#### Redux Middleware
+
+@todo
+
+#### Accessing The Store Using Selectors
+
+@todo
+
+#### Routing
+
+The page should not be reloaded after the initial render but the current location
+of the user in the system must be reflected in the URL. This is achieved through the
+[react-router](https://github.com/ReactTraining/react-router) and
+[react-router-redux](https://github.com/reactjs/react-router-redux) libraries.
+These libraries use `pushState`
+method of the `history` object, a living standard supported by all of the modern browsers.
+The mapping of the URLs to the components is defined in the `src/pages/routes.js` file.
+To create links between pages, use either the `Link` component from the `react-router` library
+or dispatch an action created using the `push` action creator from the `react-router-redux`
+library. All the navigations are mapped to redux actions and can be handled by any reducer.
+
+Having up-to-date URLs gives the users the possibility to reload the page if some
+error occurs on the page and land at the same page as he or she would expect. Users can also
+send links to the very page they want to.
+
+### Servier-side Rendering
+
+To speed-up the initial time of rendering of the web application a technique called server-side
+rendering (SSR) is used. The same code which is executed in the web browser of the client can run
+on the server using [Node.js](https://nodejs.org). React can serialize its HTML output into
+a string which can be sent to the client and can be displayed before the (potentially large)
+JavaScript source code starts being executed by the browser. The redux store is in fact
+just a large JSON tree which can be easily serialized as well.
+
+If the user is logged in then the access token should be in the cookies of the web browser
+and it should be attached to the HTTP request when the user navigates to the ReCodEx
+web page. This token is then put into the redux store and so the user is logged in on
+the server.
+
+The whole logic of the SSR is in a single file called `src/server.js`. It contains only
+a definition of a simple HTTP server (using the [express](http://expressjs.com/) framework)
+and some necessary boilerplate of the routing library.
+
+All the components which are associated to the matched route can have a class property `loadAsync`
+which should contain a function returning a *Promise*. The SRR calls all these functions and delays
+the response of the HTTP server until all of the promises are resolved (or some of them fails).
+
 
 ## Communication Protocol