From 324c5c3789a106f5b6be9087f0b911e346ec6908 Mon Sep 17 00:00:00 2001 From: Simon Rozsival Date: Wed, 28 Dec 2016 19:59:14 +0100 Subject: [PATCH] frontend architecture --- Rewritten-docs.md | 100 +++++++++++++++++++++++++++++++++++++++------- 1 file changed, 85 insertions(+), 15 deletions(-) diff --git a/Rewritten-docs.md b/Rewritten-docs.md index f1c19e6..42c3289 100644 --- a/Rewritten-docs.md +++ b/Rewritten-docs.md @@ -348,6 +348,8 @@ specific time and memory limits for the sandboxed tasks. The most important part of the system is the evaluation of the solutions submitted by the users for their assigned exercises. + + ~~For imaginary system architecture _UI_, _API_, _Broker_ and _Worker_ this goes as follows.~~ First thing users have to do is to submit their solutions to _UI_ which provides @@ -477,11 +479,11 @@ described as well. ## Implementation analysis -Developing project like ReCodEx have to have some discussion over implementation -details and how to solve some particular problems properly. This discussion is -never ending story which is done through whole development process. Some of the -most important implementation problems or interesting observations will be -discussed in this chapter. +When developing a project like ReCodEx there has to be some discussion over +implementation details and how to solve some particular problems properly. +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 @@ -594,15 +596,83 @@ cleaner completes machine specific caching system. ### General frontend implementation -@todo: communication between backend and frontend - -@todo: why is frontend divided into server and client part, mention possibilities of separated api (can be used by multiple client programs - mobile/pc/web applications) - -@todo: what apis can be used on server frontend side, why rest in particular - -### API - -@todo: php frameworks, why nette +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: + +- *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 reponses +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 in some kind of a database. +It must also be able to communicate with the backend over ZeroMQ. + +We considered several technologies which could be used: + +- PHP + Apache -- one of the most widely used technologies for creating web servers. It is a suitable +technology for this kind of a project. It has all the features we need when some additional extensions +are installed (to support LDAP or ZeroMQ). +- ASP.NET (C#), JSP (Java) -- these technologies are very robust and are used to create server technologies in many big +enterpises. Both can run on Windows and Linux servers (ASP.NET using the .NET Core). +- JavaScript (Node.js) -- it is a quite new technology and it is being used to create REST APIs lately. +Applications running on Node.js are quite performant and the number of open-source libraries avialble +on the Internet is very huge. + +We chose PHP and Apache mainly because we were familiar with these technologies and we were able to develop +all the features we needed without learning to use a new technology. Since the number of features was quite +high and needed to meet a strict deadline. This does not mean that we would find all the other technologies +superior to PHP in all other aspects - PHP 7 is a mature language with a huge comunity and a wide range of +tools, libraries, and frameworks. + +We decided to use an ORM framework to manage the database, namely the widely used PHP ORM Doctrine 2. +This framework has a robust abstraction layer DBAL so the database engine is not very important and it can be changed +without any need for changing the code. We chose an open-source database MariaDB. + +To speed up the development process of the PHP server application we decided to use an MVC framework. +After evaluating and trying several frameworks, such as Lumen, Laravel, and Symfony, we ended up using +the framework Nette. This framework is very common in the Czech Republic -- its main developer is a +well-known Czech programmer David Grudl -- and we were already familiar with the 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 straighforward. @todo: what database can be used, how it is mapped and used within code @@ -622,7 +692,7 @@ cleaner completes machine specific caching system. @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