LOMAP_EN1A

1. Introduction and Goals

The goal of the project is to develop a software system that allows users to create personalized maps holding any place they want. These maps will be completely controlled by the users and may include places such as shops, bars, sights, etc. The software will include features to allow the users to add reviews, comments, etc.; share information with others; and many other options.

1.1. Requirements Overview

The principal motivation for the creation of this system is to develop a software that the users could use to move around their cities, save interesting places for them, find or promote different places of it, etc.

The software is planned to include several features to provide several services. It must:

Allow the users to add and store any location they want to include in their maps.
Customize said locations with images and names.
Allow to add and see their and other person’s reviews, comments, pics, etc. about some place.
Include a way of managing the information that is accessible with other users, i.e. the level of privacy desired for each piece of information.
Filter the map’s markers by category, friends, etc.

These and more requirements can be found in the version 1.0 of the assignment description.

1.2. Quality Goals

These are the most important quality goals this application must fulfill:

Code	Quality category	Quality attribute	Scenario
QS2	Usability	Ease of Learning	A new user wants to find a place with the app in less than 5 minutes.
QS4	Operability	Performance	25 concurrent users request the map of a given city in less than 10 seconds.
QS7	Integrity	Privacy	Sensible user data will not be accessible for anyone but the user.
QS8	Maintainability & Support	Testability	The application should have a test coverage greater than 80%.

Code

Quality category

Quality attribute

Scenario

QS2

Usability

Ease of Learning

A new user wants to find a place with the app in less than 5 minutes.

QS4

Operability

Performance

25 concurrent users request the map of a given city in less than 10 seconds.

QS7

Integrity

Privacy

Sensible user data will not be accessible for anyone but the user.

QS8

Maintainability & Support

Testability

The application should have a test coverage greater than 80%.

For the full list of quality goals, refer to the quality scenario list.

1.3. Stakeholders

These are some stakeholders the application has to interact with:

Role/Name	Contact	Expectations
Developers	Sergio del Rey Álvarez, Diego Moragón Merallo, Vanesa Alonso Ramos, Rubén del Rey Álvarez, Álvaro González Erigoyen, Pablo Valdés Fernández	Create, test (not entirely), and document the system and communicate with the other roles to get feedback and resources.
Teaching staff	Pablo González González	Guide the developers and solve any conflicts. He is present in the meeting minutes and also provides the project’s skeleton.
SOLID challenge	Inrupt/Empathy	From what is know currently, a public challenge will take place and people in this institution will have to evaluate the usage of SOLID regarding user data.
Users	People that use or are expected to use the application	The developers will use them in the intermediate phases of the development to find problems, and test things like usability or UX.
Government	Government of Brussels	The Government is the client that is paying for the development of the software.

Role/Name

Contact

Expectations

Developers

Sergio del Rey Álvarez, Diego Moragón Merallo, Vanesa Alonso Ramos, Rubén del Rey Álvarez, Álvaro González Erigoyen, Pablo Valdés Fernández

Create, test (not entirely), and document the system and communicate with the other roles to get feedback and resources.

Teaching staff

Pablo González González

Guide the developers and solve any conflicts. He is present in the meeting minutes and also provides the project’s skeleton.

SOLID challenge

Inrupt/Empathy

From what is know currently, a public challenge will take place and people in this institution will have to evaluate the usage of SOLID regarding user data.

Users

People that use or are expected to use the application

The developers will use them in the intermediate phases of the development to find problems, and test things like usability or UX.

Government

Government of Brussels

The Government is the client that is paying for the development of the software.

2. Architecture Constraints

This application, and the whole system that follows behind, must adhere to some architectural constraints that have been set at the project definition or by the teachers; and thus cannot be changed.

Technical constraints

These constraints relate to the technologies that must be used to successfully complete the application:

Code	Constraint	Explanation
TC1	SOLID project	The shared information of the users will be stored in a personal POD according to the SOLID project. It is a specification that stores data securely in decentralized data stores called PODs.
TC2	GIT	Git must be used to track, manage and store code versions and branches. For this, GitHub will be used, as it also provides extra tools for issue tracking, continuous integration, and work assignment.
TC3	Web Interface	The application should allow users to access its services through a web application.
TC4	Deployable	The application should be deployable in the cloud, and being able to deploy both halves of the application in different containers or even machines.

Code

Constraint

Explanation

TC1

SOLID project

The shared information of the users will be stored in a personal POD according to the SOLID project. It is a specification that stores data securely in decentralized data stores called PODs.

TC2

GIT

Git must be used to track, manage and store code versions and branches. For this, GitHub will be used, as it also provides extra tools for issue tracking, continuous integration, and work assignment.

TC3

Web Interface

The application should allow users to access its services through a web application.

TC4

Deployable

The application should be deployable in the cloud, and being able to deploy both halves of the application in different containers or even machines.

Organizational constraints

These constraints relate to how the project will be developed:

Code	Constraint	Explanation
OC1	Time schedule	The project must follow a specific delivery schedule: - Documentation 0.1 must be delivered in week 4. - Prototype 0.1 in week 7. - Prototype 1.0 and documentation 1.0 in week 10. - Prototype 1.1 and documentation 1.1 in week 13.
OC2	Team	The project will be done in a team composed of 6 students, so work must be assigned accordingly.
OC3	Git-based development	The project will be built around the Git workflow, so all tools used must be able to closely interact with this system.
OC4	Testing	The project must be tested thoroughly, and a high test coverage must be reached.
OC5	Meetings	The project’s development process must be reflected in the minutes of each meeting that happens.

Code

Constraint

Explanation

OC1

Time schedule

The project must follow a specific delivery schedule:

- Documentation 0.1 must be delivered in week 4.

- Prototype 0.1 in week 7.

- Prototype 1.0 and documentation 1.0 in week 10.

- Prototype 1.1 and documentation 1.1 in week 13.

OC2

Team

The project will be done in a team composed of 6 students, so work must be assigned accordingly.

OC3

Git-based development

The project will be built around the Git workflow, so all tools used must be able to closely interact with this system.

OC4

Testing

The project must be tested thoroughly, and a high test coverage must be reached.

OC5

Meetings

The project’s development process must be reflected in the minutes of each meeting that happens.

Political constraints

These constraints relate to what conventions does the project follow:

Code	Constraint	Explanation
PC1	Documentation	We are going to use AsciiDoc and follow the Arc42 template.
PC2	Language	The documentation and application will be developed in English.
PC3	RDF Schemas	The project aims to follow RDF schemas in its data models, to favour interoperability between different providers of the service.
PC4	Code	The code for the application must be as clear as possible, to favour code maintainability.

Code

Constraint

Explanation

PC1

Documentation

We are going to use AsciiDoc and follow the Arc42 template.

PC2

Language

The documentation and application will be developed in English.

PC3

RDF Schemas

The project aims to follow RDF schemas in its data models, to favour interoperability between different providers of the service.

PC4

Code

The code for the application must be as clear as possible, to favour code maintainability.

3. System Scope and Context

As stated in the introduction, the project is aimed at creating a software system for decentralized maps, where users can store their shared information in SOLID Pods. As such, the application will be able to retrieve that data (given the permission from the user), and use it to display whatever markers the user might want to add.

3.1. Business Context

The system is related with several partners, shown in the following diagram:

The elements shown in the diagram and their functions are explained here:

Partner	Description	Output
User	Uses the application to manage its markers, reviews and other content	User data that will be stored in its POD and shown to other users, according to the level of privacy desired.
POD	Holds user data, in control of its owner	Provides access to the data the user wants to share.
LoMap	The application that provides the services to the user	Interacts with the user, its POD and the Map provider to provide the desired service.
Database	Holds user link data, to compartmentalize and link separate pieces of data	Link information that allows data to be fetched from the correct places.
Map provider	Provides the map the user sees when it uses the application	The map, and the coordinate information needed to create new markers.

Partner

Description

Output

User

Uses the application to manage its markers, reviews and other content

User data that will be stored in its POD and shown to other users, according to the level of privacy desired.

POD

Holds user data, in control of its owner

Provides access to the data the user wants to share.

LoMap

The application that provides the services to the user

Interacts with the user, its POD and the Map provider to provide the desired service.

Database

Holds user link data, to compartmentalize and link separate pieces of data

Link information that allows data to be fetched from the correct places.

Map provider

Provides the map the user sees when it uses the application

The map, and the coordinate information needed to create new markers.

3.2. Technical Context

The technical system’s structure consists in the following components:

Each component will be explained in more detail:

Technical component	Description
GitHub Repository	Repository storing the code and documentation of the project.
Documentation	Files explaining the system’s architecture following the arc42 template.
Frontend	System components that handle the interaction with the user through the user interface.
Backend	System components that handle the data processing logic.
Database	Persistent storage system to store the link data.
Map provider	Company that provides map information to display in the application.
SOLID	Architecture providing a way to store the user data in a decentralized and remote way.
POD	Decentralized server in which a single user’s information is stored.

Technical component

Description

GitHub Repository

Repository storing the code and documentation of the project.

Documentation

Files explaining the system’s architecture following the arc42 template.

Frontend

System components that handle the interaction with the user through the user interface.

Backend

System components that handle the data processing logic.

Database

Persistent storage system to store the link data.

Map provider

Company that provides map information to display in the application.

SOLID

Architecture providing a way to store the user data in a decentralized and remote way.

POD

Decentralized server in which a single user’s information is stored.

4. Solution Strategy

The solution strategy is complex, as many decisions had to be taken, but it can be broken down into several sections:

4.1. Language

Our language of choice is TypeScript, due to several reasons:

It comes bundled with our base project, so as the starting point of the application is implemented in this language, it does not make much sense to change it and discard all progress.
As the majority of the team is familiar with JavaScript, adapting to TypeScript does not pose any significant problem, even though it is technically a new language.
It offers several features to make the code more robust and easy to read. Although that constraints the freedom of code in some occasions, it makes the code less prone to runtime errors and mistakes, as they can be detected at development time.

4.2. Libraries

The libraries used are a key part of the project, and they can be divided by their intended use:

Frontend and UI:
- We are going to use React for the UI of the application, as it is fairly simple, allows a great range of customization and integrates perfectly with the language of choice.
- To give the application a bit of style, libraries such as @emotion, @mui, and @material-ui are used. They include style elements integrated into React components to simplify the UI design.
Backend:
- Node.js is being used for the backbone of the backend. It is the main building block of the backend of the application, and will hold all endpoints of the API. It is the obvious choice when searching for a TypeScript-JavaScript runtime environment.
- To run the code in a development scenario, ts-node-dev is used, as it translates TypeScript files on-the-fly and allows for fast development cycles.
- Regarding all server functions, Express is the library of choice. It works out-of-the-box with Node.js, so no extra configuration is needed on our part.
- For SOLID data access, a suite of libraries from Inrupt are used:
  - @inrupt/solid-client for data fetching and session management.
  - @inrupt/solid-client-authn-node for authentication and permission management.
  - @inrupt/vocab-common-rdf for compatibility with RDF schemas.

4.3. Data storage

When talking about data persistence, two distinct scenarios appear:

Data itself: The actual data about the user’s activities are solely stored in the user’s POD. This means that if a user creates a comment, that comment will live in that user’s POD, rather than in the system database or in another user’s POD. This is done to maximize data privacy and control.
Metadata: In order to speed up data fetching and access, the system is fitted with a JSON-based documental database, that stores link information. This information is used to relate entities in our data model, and exists to avoid repeated POD accesses that could slow down the application runtime.

4.4. Code structure

Taking a quick peek at the general structure of the application, the usage of some patterns and techniques was debated, those being:

MVC pattern: In the backend of the application, the code is divided following this pattern, as an effort to improve standarization, and code readability and mantainability. This improves the components' cohesion and coupling characteristics, and makes for an overall better code.
OOP: Although JavaScript was not meant for Object Orientation, the use of TypeScript leads nicely to the inclusion of some OOP concepts, ideas and patterns. Because of this, most of the code of the RestAPI follows a class-based structure and tries to contain code into its appropriate functions.
Script-based code: Most of the code closely related to Express is meant to be used in scripts, so that is how it is implemented. Not only is it simpler to develop, but a wide variety of documentation and examples exist to complement its development.
React components: The WebApp is almost entirely built on components. Both custom and library-provided components are implemented and used, that wrap plain HTML into easily-usable and interchangeable bits.
States: React is a technology that heavily relies on the useState pattern. They provide a bundled equivalent of properties, setters and getters; as taken from the OO paradigm. They ease up the access to shared information, and were found to work nicely with different types of data.

5. Building Block View

5.1. Level 1: Whitebox Overall System

This is a high-level static overview of the system and all its building blocks. It shows the application components, the user-related components and the external services that the application uses.

The main actor for the application is the user, which interacts with the application and provides access to a POD on which its data is stored. The application is divided into the frontend –managing the user interaction–, and backend which interacts with external services.

This diagram is divided based on data ownership. Three main groups are considered:

User: groups all user-related blocks.
LoMap: groups all application-specific blocks.
External Services: groups all other blocks that are not directly related to the user nor to the application.

5.1.1. Contained BlackBoxes

Name	Description
User	External user that provides its data through a POD and that makes use of the application services.
POD	Privately holds all user data. The application asks for permission to access this information.
WebApp	Provides a user-friendly interface to access all application services.
RestAPI	Provides the services that the application offers. Connects to data sources to provide those services.
Database	Holds all common data that the application needs to run.
Map Provider	External service that provides map data to the application.

Name

Description

User

External user that provides its data through a POD and that makes use of the application services.

POD

Privately holds all user data. The application asks for permission to access this information.

WebApp

Provides a user-friendly interface to access all application services.

RestAPI

Provides the services that the application offers. Connects to data sources to provide those services.

Database

Holds all common data that the application needs to run.

Map Provider

External service that provides map data to the application.

5.2. Level 2: WebApp

The WebApp encompasses all UI-related components of the application. It is built with React, and follows a typical React structure.

5.2.1. Contained BlackBoxes

Name	Responsibility
About.tsx	Redirects to the about page.
api.ts	Interacts with the RestAPI through HTTP requests.
CommentForm.tsx	Form to post a new comment in a place.
CommentList.tsx	List that contains all the comments of a place.
Contact.tsx	Redirects to the contact information page.
CreatePlaceWindow.tsx	Window for the creation of a new place.
FAQ.tsx	Contains the Frequently Asked Questions of the application.
FilterCategory.tsx	Strip holding the filters of the application.
Footer.tsx	Contains the links to the About and Contact pages.
FriendPanel.tsx	Small panel that holds your friends.
FriendsView.tsx	Friend management page.
Home.tsx	Presents the application and its features.
InfoWindow.tsx	Holds the information of a place.
LoginForm.tsx	Offers the option to log in with an Identity Provider.
MapView.tsx	Main component of the page itself. Contains the most important components of the frontend.
NavBar.tsx	Tops the main view of the page, and offers log in and logout options.
PictureSelector.tsx	Allows users to select an image to upload.
Profile.tsx	Shows your profile.
Sidebar.tsx	Contains all pop-down menus of the map.
SlideShow.tsx	Used to hold several images as a carousel.
UserProfile.tsx	Shows the name and webId of the current user logged in.

Name

Responsibility

About.tsx

Redirects to the about page.

api.ts

Interacts with the RestAPI through HTTP requests.

CommentForm.tsx

Form to post a new comment in a place.

CommentList.tsx

List that contains all the comments of a place.

Contact.tsx

Redirects to the contact information page.

CreatePlaceWindow.tsx

Window for the creation of a new place.

FAQ.tsx

Contains the Frequently Asked Questions of the application.

FilterCategory.tsx

Strip holding the filters of the application.

Footer.tsx

Contains the links to the About and Contact pages.

FriendPanel.tsx

Small panel that holds your friends.

FriendsView.tsx

Friend management page.

Home.tsx

Presents the application and its features.

InfoWindow.tsx

Holds the information of a place.

LoginForm.tsx

Offers the option to log in with an Identity Provider.

MapView.tsx

Main component of the page itself. Contains the most important components of the frontend.

NavBar.tsx

Tops the main view of the page, and offers log in and logout options.

PictureSelector.tsx

Allows users to select an image to upload.

Profile.tsx

Shows your profile.

Sidebar.tsx

Contains all pop-down menus of the map.

SlideShow.tsx

Used to hold several images as a carousel.

UserProfile.tsx

Shows the name and webId of the current user logged in.

5.2.2. Level 2: RestAPI

The RestAPI block, also called LoMapCore, encompasses all business-logic components, as well as data-source management and interaction with other services. It is in charge of managing the storage of data, the interaction with the PODs and the enforcement of all business rules.

5.2.3. Contained BlackBoxes

Name	Responsibility
WebApp	Frontend of the application.
Domain	Holds all entities and DTOs used across the application to communicate modules.
Controllers	Declare the endpoints of the RestAPI and make use of the services to provide the functionality.
Services	Manage all business rules of the application, and use the repositories to persist said data.
Repositories	Handle the storage of the data provided by the services. They interact with the database dn with the PodAccess.
PodAccess	In charge of handling POD accesses, authentication and data fetching.
PermissionManagement	Handles the required permissions to access POD data.

Name

Responsibility

WebApp

Frontend of the application.

Domain

Holds all entities and DTOs used across the application to communicate modules.

Controllers

Declare the endpoints of the RestAPI and make use of the services to provide the functionality.

Services

Manage all business rules of the application, and use the repositories to persist said data.

Repositories

Handle the storage of the data provided by the services. They interact with the database dn with the PodAccess.

PodAccess

In charge of handling POD accesses, authentication and data fetching.

PermissionManagement

Handles the required permissions to access POD data.

5.2.4. Database

The Database holds linked data for the application. This data is in charge of linking entities with each other, to avoid repeated access to PODs to search for these pieces of metadata. An example of a piece of data stored in the DB could be as simple as a pair of internal IDs, that link a comment with its corresponding place.

Then, you could search for the ID of a place to retrieve all associated comments without going through several PODs to discover if they hold any useful information.

In the following diagrams, a schema of the data stored in the database and a possible snapshot are represented. It must be noted that, as the database is documental, the class diagram is not a direct representation of the internal structure of the data stored; but rather a schema of what is stored. A more realistic representation is the object diagram below.

5.2.5. MapService

The Map provider is an external service, provided through an API, that allows LoMap to obtain the most recent and updated maps available, in order to avoid providing outdated information to the end user. It is interacted with through the WebApp, as the ResAPI does no longer need that information. The vendor selected is OpenStreetMaps, as it provides free access to their API for non-commercial usage, and it aligns with the privacy principles of our application.

In order to receive the service of the Map provider, an API key was obtained that authenticates all requests done through the WebApp.

6. Runtime View

The runtime view offers a different perspective of the structure of the application, revealing the process each request makes throughout the whole scope of the system.

6.1. Login scenario

This scenario describes a high-level overview of the process a user takes to log into the application.

6.2. Add location scenarios

This scenario describes the steps taken for a user to save a location to the system. This assumes the user is already logged in.

6.3. View location details scenario

This scenario describes the process taken when a user requests to see the information of a given location. Like the last scenario, this one assumes the user is already logged in.

In this case, several PODs are accessed, as the comments, reviews and scores are stored in each poster’s POD.

6.4. Review location scenario

This scenario describes the process taken when a user wants to leave a review. This scenario follows from the last one.

7. Deployment View

The deployment of the application is designed for a deployment in a Virtual Machine in the Azure Cloud. Inside, two Docker containers are deployed: one holds the RestAPI and the other holds the WebApp.

Also, the POD and the Database are cloud-based, so they are held in their respective provider’s infrastructure.

Component	Description
Azure Server	Both the frontend and the backend will be hosted from docker containers, both of them inside an Azure virtual machine.
WebApp	The frontend of the application, which will receive the user’s requests and ask the RestAPI for its services.
Rest API	Manages the requests from the web application and fetches the data from the corresponding place.
Database	A documental database, which will store the minimal link information about the users.
Map Provider	An external service to get the maps for the application.
User	The user of the application.
User Machine	The device from which the user will interact with the application.
POD	Stores the user’s data.

Component

Description

Azure Server

Both the frontend and the backend will be hosted from docker containers, both of them inside an Azure virtual machine.

WebApp

The frontend of the application, which will receive the user’s requests and ask the RestAPI for its services.

Rest API

Manages the requests from the web application and fetches the data from the corresponding place.

Database

A documental database, which will store the minimal link information about the users.

Map Provider

An external service to get the maps for the application.

User

The user of the application.

User Machine

The device from which the user will interact with the application.

POD

Stores the user’s data.

8. Cross-cutting Concepts

The application manages a lot of information. As such, it is required to define and explain some of them to reflect its internal workings.

8.1. Domain model

The following domain diagram and its description aims to describe the entities the application manages.

Element	Description and purpose
User	The people that use the application.
Visibility	The privacy level of elements of the application (markers, reviews, scores, etc.) can be managed. Either public, private or friend-only levels are currently supported.
Place	They represent the points on the map (they can be either created by users or be given by the application).
Category	Places are classified into cateogries.
Picture	Users can upload pictures to places.
Score	Users can score places.
Comment	Users can upload comments to places.
Route	They are sets of places, of the same category.
Role	Users can be classified into different roles.

Element

Description and purpose

User

The people that use the application.

Visibility

The privacy level of elements of the application (markers, reviews, scores, etc.) can be managed. Either public, private or friend-only levels are currently supported.

Place

They represent the points on the map (they can be either created by users or be given by the application).

8.2. Security and user privacy

In order to increase security and privacy, all users authenticate through their POD, that will store their data, friends and maps. This way the users can decide who can see and use their information, giving them more freedom and control over the data they share.

8.3. Persistence

A document database will be used to store metadata about entities in the domain model. This metadata is intended to link entities with their containers, for example linking a comment to its associated place.

8.3.1. Structure of link data

The concept of link data aims to provide a faster, more private way of handling information inside the application. It works as follows: entities (such as places or reviews) are stored in each user’s POD, and have a UUID associated with them. They only contain data about themselves, such as names, links or webIds. They do not contain other entities (for example, in the case of places, they don’t contain its reviews), but that information is stored in the database as small documents that contain the two entities to link, as well as some extra information to include the privacy level of the item and the webId of the owner.

Refer to database schema for a representation of this data.

8.4. Session management

Since the POD is the only identity 'token' the application uses, each person will only sign in and have access to their saved data through it. Passwords will only be used by the Identity Provider to ensure the correct user is giving access to the POD’s resources.

As a consequence, the application does not have to manage users. At a more basic level, the application is just another POD browser: it manages data stored in the PODs of users.

9. Design Decisions

Along the process of developing the application, decisions had to be taken as problems arise. The following table contains some of the design decisions that were imposed to us due to the architectural constraints:

Table 1. Imposed decisions
Code	Decision	Advantages	Disadvantages
ID1	TypeScript	Similar to JavaScript, but with types.	We have never used it before
ID2	React.js	Quite easy to learn in comparison to other front-end libraries. Increasingly popular in the web	We have never used it before
ID3	MongoDB	We are quite new with MongoDB. It does not need to be started manually.	Since our Mongo database is not stored locally, queries can take some time to be performed
ID4	Node.js	Easy escalability, easy to learn, high performance for real-time applications	We have never used it before
ID5	Docker	Fast deployment, ease of moving/maintaining your applications	We do not have much experience using Docker
ID6	PlantUML	Allows drawing diagrams very easily, with a simple syntax.	Does not allow as much control over the exact layout of the elements in the diagram as other tools.

The most interesting design decisions are reflected in this architectural records:

Table 2. Architectural Records
Code	Context	Record
ADR1	This decision was taken on 27-02-2023 , when discussing about the privacy of the stored data.	In the context of deciding what use to give to the system’s database, facing the desire to keep as much data in control of the users as possible, we decided to store link data in the database instead of public data of the users to achieve better user ownership of the data. This decision was taken accepting a possible downside in performance, because the public data must still be fetched from the user’s PODs.
ADR2	This decision was taken on 06-03-2023, when discussing how to create the UI of the application.	In the context of implementing a map view for the application, facing the API chosen to provide the map service, we decided to change the responsibility of fetching the map from the RestAPI to the WebApp. This was made because the map provider offers a simple way to embed the map into the webpage, so implementing it into the RestAPI would prove much more difficult than needed.
ADR3	This decision was taken on 20-03-2023, when reviewing the deliverable notes and corrections.	In the context of accessing linkage data in the DB, facing the complexity of implementing a functional access to the kind of data stored, we decided to switch our DB system from MySQL to MongoDB. This was made to achieve an easier and more efficient way of accessing these data, accepting the extra effort needed to rebuild the database structure and the changes to the data model.
ADR4	This decision was taken on 06-04-2023, when discussing the implementation of a functional POD access.	In the context of implementing the functionalities of the backend of the system, facing the increasing complexity of the RestAPI, we decided to completely refactor its code following a 3-layer architectural pattern. This was made to favor code cohesion, improve code independence and maintainability, accepting the effort needed to refactor the code of our API and the discarding of the progress made in that regard.
ADR5	This decision was taken on 17-04-2023, when discussing the usability problems of the application.	In the context of improving the usability of the application, facing the tediousness of loading the username when fetching reviews, we decided to add the whole user entity to the database entries for reviews. This was made because before, the reviews showed the webId of the OP (link to glossary), which was not adequate as it cluttered the view.
ADR6	This decision was taken on 27-04-2023, when discussing the privacy concerns of managing friends.	In the context of reviewing the security level of the application, facing the possible privacy concerns of being added to friends of an unknown individual, we decided to create a friend-request system. This was made because you might not want to be friends with some individual, and a request system adds an extra layer of protection for the user, accepting the extra effort needed to implement such feature..
ADR7	This decision was taken on 27-04-2023, when discussing the tediousness of managing friends.	In the context of finding ways to improve the usability of the application, facing the tediousness of managing friends, we decided to create a friend-request window to accompany the friend-request feature. This was made because handling friends through a POD browser is hard and tedious, and a window specific for that purpose is a better solution, accepting the extra complexity added for the end-user.

10. Quality Requirements

10.1. Quality Tree

The quality tree classifies the qualities the system will be evaluated about. We divide them in four main categories: Usability, Operational, Integrity and Maintainability & Support.

10.2. Quality Scenarios

The quality scenarios propose metrics and methods used to evaluate the quality requirements of the application. This table is classified by quality category.

Code	Quality category	Quality attribute	Scenario	Priority	Implementation complexity
QS1	Usability	Ease of Use	The application should be usable on a computer.	Medium	Medium
QS2	Usability	Ease of Learning	A new user wants to find a place with the app in less than 5 minutes.	High	Low
QS3	Operability	Availability	The application must be available the 99% of the time.	Medium	High
QS4	Operability	Performance	25 concurrent users request the map of a given city in less than 10 seconds.	High	High
QS5	Operability	Robustness	The application should keep working for other users if one user experiences problems.	Medium	Medium
QS6	Integrity	Security	User data must be transmitted and stored securely.	Low	High
QS7	Integrity	Privacy	Sensible user data will not be accessible for anyone but the user.	High	Medium
QS8	Maintainability & Support	Testability	The application should have a test coverage greater than 80%.	High	Low
QS9	Maintainability & Support	Maintainability	The code should be clear and documented enough to allow new developers to join the project.	Low	Low

Code

Quality category

Quality attribute

Scenario

Priority

Implementation complexity

QS1

Usability

Ease of Use

The application should be usable on a computer.

Medium

QS2

Usability

Ease of Learning

A new user wants to find a place with the app in less than 5 minutes.

High

Low

QS3

Operability

Availability

The application must be available the 99% of the time.

Medium

High

QS4

Operability

Performance

25 concurrent users request the map of a given city in less than 10 seconds.

High

QS5

Operability

Robustness

The application should keep working for other users if one user experiences problems.

Medium

QS6

Integrity

Security

User data must be transmitted and stored securely.

Low

High

QS7

Integrity

Privacy

Sensible user data will not be accessible for anyone but the user.

High

Medium

QS8

Maintainability & Support

Testability

The application should have a test coverage greater than 80%.

High

Low

QS9

Maintainability & Support

Maintainability

The code should be clear and documented enough to allow new developers to join the project.

Low

11. Risks and Technical Debts

When making decisions, there are often trade-offs between various options. Risks and technical debt are two types of compromises that we may accept in order to make progress towards our goals.

Risk refers to the possibility of something going wrong or not working out as planned. In other words, it’s the chance that an outcome will deviate from what we expect or hope for. When we make a decision, we may take on certain risks in order to achieve a certain outcome.

Technical debt, on the other hand, refers to the shortcuts or quick fixes we may make in order to achieve a short-term goal at the expense of long-term sustainability or maintainability.

Both risks and technical debt are compromises that we accept in order to achieve our goals. However, it’s important to carefully consider the potential consequences of these compromises, and to weigh them against the potential benefits. If we take on too much risk or technical debt, we may end up with problems that are more difficult or costly to solve in the long run.

11.1. Risks

This is a table of the risks we took during the development of the application:

Table 3. Risks
Risk	Explanation	Solution
No knowledge of React	We have never worked with React before, so we know nothing about it.	Read React’s documentation and analyze the provided exercises, and take advantage of the fact that we are simultaneously taking the SDI course.
No knowledge of SOLID	It is a new concept and technology for us.	Explore SOLID’s documentation to familiarize ourselves with the technology, and seek examples of use.
Little knowledge of TypeScript	Some of us know some JavaScript, but TypeScript is a little different.	Read TypeScript’s documentation, see code examples, seek similarities with other languages and experiment with its capabilities and features.
Time	We have to take into consideration the different deadlines, and balance the development time with the rest of stuff we have to do.	Try to manage our free time better, and make better use of the tools used in the development process to optimize the time spent.
Team members	It can be difficult to work with a large group of people, as there may be disagreements and each person does things in their own way.	Good communication between team members, assigning tasks correctly and make good use of organizational tools provided with our Git service.
External services' dependency	During this project, we will use some external services that are out of our control.	Create the application in such a way that minimizes the negative consequences of this dependency.

11.2. Technical debt

As of now, most of the technical debt has already been tackled and solved, but there is still stuff to fix.

Table 4. Technical debts
Technical debt	Explanation
MySQL	We used MySQL for the first prototype as it is the DB provider we are more familiar with, and we were not sure how to save the data. Now, the DB schema and provider have been selected so that they fit better to the project.
Creating the tests at the end of development	Ideally, tests should be created before starting the development or at the beginning, as that facilitates the design task. But due to time constraints, we will create them at the end.
POD permissions	The permissions of the directories inside the PODs are not configured properly and are difficult to manage, consequently everybody can see everything inside the LoMap folder and the owner can modify its data in any way, even corrupting its information.

12. Glossary

This glossary contains an alphabetically sorted list of terms that are widely mentioned across this documentation:

Term	Definition
Component	In the WebApp, a component is a template for a visual element that is used as a reutilization mechanism to compose the views, joining and combining several components into others.
Continuous Deployment (CD)	A process that automatically deploys a project into a deployment scenario whenever changes are committed in a repository.
Continuous Integration (CI)	A process that automatically builds and tests code from a repository whenever changes are committed.
Docker	Software platform that allows you to deliver software in packages called containers
IDP	IDentity Provider: Service in which a user can request a POD to hold its data.
JSON	JavaScript Object Notation:Standard, language-independent format used to store and transmit data objects storing them as attribute-value pairs of standard, human-readable text.
Link data	In LoMap, we call link data to data that is used to relate entities of the domain. For example, there exists link data that joins a review and a place, or a place and a user.
Metadata	Data that defines characteristics of other data, such as date and time, size, format, etc.
MongoDB	Open-source, cross-platform, NoSQL document-oriented database management system which uses a document format similar to JSON, with the option to use schemas.
Node.js	Single-threaded, open-source, cross-platform runtime environment for building fast and scalable server-side and networking applications
OP	Original Poster: the creator and owner of an entity, such a place, a review or a score.
POD	Personal Online Datastore: Decentralized data stores. They are like secure personal web servers for data
Profile	A profile is a document that holds the personal information about a user, and its held into the user’s POD.
React.js	JavaScript library that allows developers to easily create fast user interfaces for websites and applications alike
SessionId	A sessionId is a token that is used to identify a user across the layers of the application, so that the RestAPI and the WebApp can keep track of a user’s request.
TypeScript	Open source high-level programming language. It is a strict syntactical superset of JavaScript and adds optional static typing
WebId	A webId is a URL used as the ID of a user. It navigates to the user’s profile hosted in its POD.

Term

Definition

Component

In the WebApp, a component is a template for a visual element that is used as a reutilization mechanism to compose the views, joining and combining several components into others.

Continuous Deployment (CD)

A process that automatically deploys a project into a deployment scenario whenever changes are committed in a repository.

Continuous Integration (CI)

A process that automatically builds and tests code from a repository whenever changes are committed.

Docker

Software platform that allows you to deliver software in packages called containers

IDP

IDentity Provider: Service in which a user can request a POD to hold its data.

JSON

JavaScript Object Notation:Standard, language-independent format used to store and transmit data objects storing them as attribute-value pairs of standard, human-readable text.

Link data

In LoMap, we call link data to data that is used to relate entities of the domain. For example, there exists link data that joins a review and a place, or a place and a user.

Metadata

Data that defines characteristics of other data, such as date and time, size, format, etc.

MongoDB

Open-source, cross-platform, NoSQL document-oriented database management system which uses a document format similar to JSON, with the option to use schemas.

Node.js

Single-threaded, open-source, cross-platform runtime environment for building fast and scalable server-side and networking applications

Original Poster: the creator and owner of an entity, such a place, a review or a score.

POD

Personal Online Datastore: Decentralized data stores. They are like secure personal web servers for data

Profile

A profile is a document that holds the personal information about a user, and its held into the user’s POD.

React.js

JavaScript library that allows developers to easily create fast user interfaces for websites and applications alike

SessionId

A sessionId is a token that is used to identify a user across the layers of the application, so that the RestAPI and the WebApp can keep track of a user’s request.

TypeScript

Open source high-level programming language. It is a strict syntactical superset of JavaScript and adds optional static typing

WebId

A webId is a URL used as the ID of a user. It navigates to the user’s profile hosted in its POD.

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