1. Introduction and Goals
Documentation of the LoMap system, an application in which citizens can have personalized maps of places and local businesses in the city.
1.1. Requirements Overview
-
Add places in different categories.
-
Users will be able to display locations in a map-like window.
-
Users can associate ratings, comments, photos on the added places.
-
Information about a place stored by each user will be stored in each user’s pod.
-
Users will be able to see places and information taken from their friends.
-
Filters are allowed for searches on the map.
1.2. Quality Goals
| Goal | Description |
|---|---|
Privacy |
Each user should have the ability to control their information and know who has access to it. |
Usability |
The system should be able to be used quickly and easily by any user. |
Decentralization |
To avoid security problems by having all the data in a central base, the personalized maps will be under the control of the users and the shared information will be stored in the personal pod of each one. |
Scalability |
LoMap must be able to grow and increase its functionalities in a simple way. |
Testability |
Unit tests will be applied to the application to ensure the proper performance of the system. |
1.3. Stakeholders
| Role/Name | Contact | Expectations |
|---|---|---|
Students |
Álvaro Davila Sampedro, Adrián Martínez Rodríguez, Hugo Roberto Pulido Pensado, Javier González Velázquez |
Main developers of the application, in order to improve teamwork and learn how SOLID principles work. |
Teachers |
Teachers |
In charge of supervising the work of the students. |
Users |
All people who are going to use the application |
At the time of use the app, users search for an app functional, fast and easy to understand. |
Recruiter |
Council of Brussels |
A functional application that meets the requirements requested in the contract. |
2. Architecture Constraints
2.1. Tecnichal Constraints
| Constraint | Explanation |
|---|---|
React |
The React framework will be used to create the web based UI (User Interface). |
Typescript |
TypeScript is a strongly typed version of JavaScript. We will use it to make development easier and to be able to detect typing errors during compilation. |
SOLID |
We will use SOLID as a way to have a decentralized storage of our users data. |
Git/GitHub |
Git will be used as a version control system and Github will be the platform where the remote repository is store. All the documentation of the development process will be stored in GitHub as well. |
2.2. Organizational Constraints
| Constraint | Explanation |
|---|---|
Team meetings |
We must hold at least one meeting a week. This will be done in the weekly laboratory session. Extra meetings may be hold when necessary. |
Deadlines |
As this project is part of a college course, it has very tight and fixed deadlines. This means we may have trouble delivering all releseases with the desired quality. |
Application interoperability |
It is desirable that the different groups agree on a common storage standard for the SOLID part of the application. This, however, is not mandatory as it can be difficult to coordinate those many groups. |
2.3. Conventions
| Constraint | Explanation |
|---|---|
Arc42 Documentation |
We will follow the Arc42 template for the documentation of the project. |
JavaScript/TypeScript |
We will use JavaScript/TypeScript naming conventions. |
MVC |
We will follow MVC naming and layering conventions. |
SOLID |
We will follow the SOLID specification in order to ensure our users data is kept private and under their control. |
3. System Scope and Context
The objetive of the project is develop a software system called “LoMap” where the citizens can have personalized maps about places and local businesses in their city. On the other hand, in this aplication the users can add locations in different categories like:
-
Shops
-
Bars
-
Restaurants
-
Sights
-
Monuments
The users can also add review scores, comments, pictures, etc. about the added places.
Users can see places and information about those places taken from their Friends and filter the maps by category.
3.1. Business Context
In the homepage will show the generic map in your current city. In this page, you can also customize maps. To use this aplication the customer will be able to log into the service as well as to register himself. If the usser is logged he will be able to see places and information about those places taken from their friends. The customer can also use a filter to see teh map by categories.
Caption:
| Entity | Description |
|---|---|
User |
Uses the application |
Lomap |
The main application |
PODs |
Store the personal data |
3.2. Technical Context
To develop this aplication we are going to use SOLID architecture using PODs to store the user’s personal data. As programming lenguaje we are going to use TypeScript with REACT to create the inteface. We will use NodeJS as execution enviroment. On the other hand, we are going to use the NonSQL datebase MongoDB. For the restApi we will use the work express framework.Mapbox will be our map provider and we will rely on MUI library to make the graphic interface.
| Technology | Description |
|---|---|
SOLID |
The architecture of the application |
PODs |
Store the personal data |
TYPESCRIPT |
Main programing lenguage |
REACT |
The library to make the GUI |
Mui |
Provides components |
Node.js |
The execution enviroment |
Express |
Framework for the restapi |
Mapbox |
Map api |
4. Solution Strategy
4.1. Technological decisions
We have decided to use the following technologies:
-
React: The JavaScript library we will use to create the user interface.
-
Node.js: It is a JavaScript environment that will be used to create the web server of the application
-
Typescript: JavaScript superset whose main objective is to add strong typing to JavaScript
-
SOLID: Decentrilized storage system where the user’s data will be stored.
-
Git/Github: Version control system also used for managing all the development process.
4.2. Decision about the top-level decomposition of the system
The system can be divided in two main parts, the backend and the frontend:
-
For the frontend we are using the React library allong with TypeScript.
-
For the backend we will use a MVC pattern (model-view-controller) as it provides a easy way of dividing the different parts of the application. The view part, however, will not exist on our backend as it will be part of the frontent
4.3. Decisions on achieving key quality goals
-
One of the key quality goals of the project is to keep user’s data private. For this reason we will use the SOLID POD, which decentrilizes that data.
-
Another important quality goal is usability and user experience. For this we will make our application as intuitive and simple as posible.
-
The last quality goal is accessibility. However, as the main part of the UI is a map, it is very difficult to make it trully accesible, so it won’t be the top priority when designing and developing the application.
4.4. Organizational decisions
-
In terms of communication, we will use WhatsApp for minor doubts and general comunication. To keep a record of problems and asigned tasks we will utilize de Issue system of Github combine with a Kanban project to have a more visual view of the work flow. We will hold a weekly class meetings and, if necessary, we will hold additional meetings in Discord.
-
We will keep a record of every meeting in the Wiki section of the Github project.
5. Building Block View
5.1. Level 1: Whitebox of the Overall System
- Motivation
-
Lomap is formed by the web app, the database and the rest api, each one has its on funcionality in order to separate responsabilities.
- Contained Building Blocks
| Name | Description |
|---|---|
User |
The user wich interact with the app |
Lomap |
The main application |
PODs |
Saves the user’s data |
Webapp |
Is the part of the application with wich the user interacts |
RestApi |
Manage the data that the webbapp |
5.2. Level 2
- Motivation
-
In this section the description is extended to provide more info on how it works.
- Contained Building Blocks
| Name | Description |
|---|---|
Log in |
Authenticates the user with their solid account |
Manage friend |
Allows to add and delete friends |
Add marker |
Allows you to add markers |
Delele marker |
Allows you to delete markers |
Share marker |
Allows you to share markers with friends |
6. Runtime View
6.1. Register
When the user registers, the app redirects to the pod for the user enter his data.
6.2. Log
When the user logs in, the app redirects to the pod for the user enter his credentials. The pod returns the result of the login.
6.3. Add mark
The app ask for the data of the mark, when receives the data, the app create the mark and saves it on the pod and the image on the Rest Api.
6.4. Delete mark
The app delete the mark from the Pod.
6.5. Add friend
To add a friend, the user is asked for a webID and the user with that webID is added to friends.
6.6. Delete friend
The user delete and confirm on the app and the app remove the friend from the POD.
6.7. Load markers
The app first loads its own marks, then those of friends and public, load the images from the Rest Api and finally shows them.
6.8. Share markers
The app change the state of the marker and save it into the public folder of the POD.
6.9. Make marker private
The app change the state of the marker and save it into the private folder of the POD.
6.10. Add news
The app ask for the data of the news, when receives the data, the app create the mark and saves it on the pod.
6.11. Load news
The app loads the news from the pod.
6.12. Add routes
The app ask for the data of the route, when receives the data, the app create the mark and saves it on the pod.
6.13. Load routes
The app loads the routes from the pod.
6.14. Delete routes
The app delete the route from the Pod.
7. Deployment View
7.1. Infrastructure
Describe (usually in a combination of diagrams, tables, and text):
-
the distribution of your system to multiple locations, environments, computers, processors, .. as well as the physical connections between them
-
important justification or motivation for this deployment structure
-
Quality and/or performance features of the infrastructure
-
the mapping of software artifacts to elements of the infrastructure
For multiple environments or alternative deployments please copy that section of arc42 for all relevant environments.
- Motivation
-
This diagram shows is a basic overview of how our application will be deployed. It will be updated in the future as the development process goes a¡on and we take more detailed decisions.
- Quality and/or Performance Features
-
As one of our key quality goals is to have a fast and efficient application, we tried to make the simplest arquitecture posible and using fast and reliable third party services.
- Mapping of Building Blocks to Infrastructure
| Node | Description |
|---|---|
Browser |
The client side application the user will use to connect to our application. |
WebServer |
This is where both our frontend and backend applications will be stored. The frontend will be served to the user and it will send requests to the backend. |
WebApp |
This is the frontend application that the user will receive and interact with through the browser. |
RestAPI |
It will be used to store images from user markers |
Mapbox |
To display the user markers we will use Mapbox as the map provider. |
PodProvider |
This is the third party service where our users' SOLID PODs will be stored |
User_Pod |
This is the SOLID POD where users' personal data will be stored and read by the WebApp. |
8. Cross-cutting Concepts
8.1. Domain model
Caption
| Entity | Description |
|---|---|
User |
Application user which is saved in SOLID |
Marker |
Location marker with the information |
Comment |
Comment in a marker |
Route |
A collection of markers |
News |
Information published by the users and available for everyone |
8.2. Gaphical user interface
To develop the user interface we are going to use the REACT library together with TypeScript. We are going to use REACT since it seems to us the most appropriate because it is based on components. The user interface should be intuitive, clean and simple to make it easier for the user to use the web, and only worry about looking for personalized maps about the city.
8.3. Internationalization
After having been talking, we have decided that both the documentation and the application are going to be done in English. This will be so because we want the application to be more international.
8.4. Security
Regarding security, we will follow the SOLID principles and will use the PODs to gain access. As we use the POD API we can verify the user and only access the data that he allows. In our case we will only store the username without the need to store the password.
8.5. Development concepts
We are going to explain how the development task will be as well as the tools to be used:
-
REACT is a library that is based on JavaScript that allows making interactive user interfaces in a simple way.
-
PODs to store users' personal information.
-
NodeJS for running web applications outside the client’s browser.
9. Design Decisions
In this part of the documentation we are going to explain the design decisions that we will make. These decisions will appear in the following table.
| Architectural decision | Pros | Cons | Link |
|---|---|---|---|
TypeScript |
TypeScript is a programming language built on top of JavaScript. This superset of JavaScript gives the language several additional features that make it easier to write code that is less buggy, simpler, more consistent, and easier to test. |
On the one hand the learning curve is greater than that of JavaScript. It also has a somewhat complicated type system. But the most important thing is that no member of the team has used it before |
|
REACT |
It is easy to learn, has a high level of flexibility, 100% open source JavaScript Library with frequent updates and improvements from developers around the world. |
Lack of official documentation, no development pattern, takes a long time to fully master. |
|
SOLID |
It allows us to facilitate the understanding of the architectures, prevent our code from falling into chaos and unexpected errors appear at all times, it also allows us to improve cohesion. |
The greatest disadvantage is that if we do not have a correct preparation we will find ourselves with ambiguous concepts that will make it difficult to understand the code. |
|
NodeJS |
The biggest advantage is that it will allow us to share code and structures between the server and the client, it is tremendously flexible as well as having a smooth data stream. |
Some of the disadvantages are that it has an unstable API, the code can be difficult to debug, and it is a young technology. |
|
MapBox |
It is a free library that offers us a wide range of tools and options to customize and design maps, it is also compatible with a large number of platforms and offers extensive documentation. |
Requires a learning curve for new users, some of the customizations and map layouts can be complex as well as vendor dependency. |
10. Quality Requirements
10.1. Quality Tree
10.2. Quality Scenarios
| Quality goal | Motivation | Usage scenarios | Priority |
|---|---|---|---|
Privacy |
User data must be protected and it must also be done in a decentralized way |
Data from users will be retrieved in a decentralized way, from the user’s pod. For this we will use different pod providers such as INRUPT and SOLID. All information related to personal bookmarks will be stored in the pods. |
High |
Usability |
In order for the page to stand out from the rest and to be easy to use and understand, it has to be usable. |
When a user wants to perform any action in Lomap, they will do so without any complications with the help of the interface |
High |
Security |
The page has to be very secure to protect user data, because if it were insecure no user would use it. |
Data must not be accessible for any third parties. Data from users will be stored in a secure system. |
High |
Testability |
The unit tests are necessary to check the correct implementation of the application. |
For this, the developers implement tests, in order to detect why the app was failing, so that funcionality is fixed as soon as possible. |
Medium |
Portability |
Today web page users use many different devices such as phones, computers. Therefore, we want to make the application portable to reach the maximum number of users. |
We will try to make the page as comfortable as possible for different devices, making it more adaptable, usable… |
Medium |
11. Risks and Technical Debts
Below we indicate the risks identified, as well as the measures proposed to eliminate them.
11.1. Risks
| Risk | Description | Measure |
|---|---|---|
Knowledge of SOLID |
SOLID is a new technology for the whole group that we have never used and therefore certain problems may arise when using it. Also, it is not very easy to find good examples on the Internet.. |
Understand the technology before using it by looking for documentation and tutorials so as not to have problems when we are implementing it. |
Time |
Due to the fact that there are many works by other subjects in this semester, it may be difficult for us to reach a delivery date. |
We must make an effort to organize the time we have and carry out good planning. |
Github |
Despite the fact that we have used Git and Github in other subjects, our knowledge is basic and problems can arise, such as knowing how to create a pull request or delete information due to a merge. |
Github is a basic technology that we must learn to use in order to work in the future and we can do it through examples or making small project prototypes to familiarize ourselves with it. |
12. Glossary
| Term | Definition |
|---|---|
Backend |
Part of application that handles the processing and retrieval of data, and communicates with the database |
Frontend |
Part of the application that the user communicates with through a browser |
RestAPI |
It is a standarized backend architecture for creating web services usign HTTP methods. |
MongoDB |
Open source NoSQL database that uses document-oriented data models. |
SOLID |
It is a web technology project that aims to decentralize the web by giving users control of their private data. |
POD |
It is server or storage space where users can store, share and control their data. The SOLID project is built on PODs. |
User |
Client that uses our application. |
13. Testing
13.1. Análisis de estadísticas
Hemos utilizado SonarCloud en nuestro proyecto para mejorar la mantenibilidad del proyecto y reducir los code smells y los problemas de seguridad.
13.2. Tests de carga
Para la realización de los tests de carga se utilizó el programa Gatling versión 3.9.0. Las pruebas realizadas consisten en la carga de los marcadores públicos y de las noticias.
13.2.1. Caso A (3 usuarios durante 30 segundos)
13.2.2. Caso B (15 usuarios durante 30 segundos)
13.2.3. Caso C (30 usuarios durante 30 segundos)
Como se puede apreciar a medida que aumentan el número de usuarios los tiempos de respuesta son mayores pero sin llegar a fallar nunca.
About arc42
arc42, the Template for documentation of software and system architecture.
By Dr. Gernot Starke, Dr. Peter Hruschka and contributors.
Template Revision: 7.0 EN (based on asciidoc), January 2017
© We acknowledge that this document uses material from the arc 42 architecture template, http://www.arc42.de. Created by Dr. Peter Hruschka & Dr. Gernot Starke.