ViaDe ES1B

Note	This version of the template contains some help and explanations. It is used for familiarization with arc42 and the understanding of the concepts. For documentation of your own system you use better the plain version.

1. Introduction and Goals

The intention of this project, Viade, is to create and develop a route management system, such as Wikiloc, but with the difference that it’s done in a decentralized way, which means that the app and data storage are independent so your data is only yours and you decide who you share it with. To carry out this this app, we are using SOLID specifications and the React framework.

1.1. Requirements Overview

Functional requirements

Users can view their routes on a map and store them in their own pods.
An user can get notifications when some friend shares a route with him.
To register routes, users must have a POD, so they have to log in and authenticate in SOLID inrupt or community.
Users can have groups of friends with whom they may want to share a route.
View routes that had been loaded in other apps.

Non functional requirements

Ease of learning to interact whith the app by new users.
Small response and loading times.
Security and privacy: no vulnerability points.
Accessibility and usability level following the recommendations of W3C.
Not having a central database, which compromises the information of the users that use it.

1.2. Quality Goals

The priority will go in decreasing order. The number one will be the most priority and will decrease the priority

Table 1. The quality goals
Priority	Quality goal	Scenario
1	Usability	There is a new user in our app and he wants to start to use all its functionality as soon as possible.
2	Security	An user doesn’t want to share his information with another one unless he gives him permission.
3	Mantainability	The developer team wants to add more functionality to the application.
4	Compatibility	Someone wants to share his route from other app with some user that is using Viade.
5	Efficiency	When an user wants to load a route, it must be in a short time.

1.3. Stakeholders

Table 2. Steakeholders of the app
Role/Name	Contact	Expectations
Teachers	Teaching staff of ASW	Well developed app paying special attention to its architecture.
Inrupt	Startup behind SOLID	Well usage of their technology in decentralized apps.
Developers	Members of the team that create the app	Develop a functional and maintainable app.
Hiker, Cyclist, Runner, Mountaineer,…	Users of this app	Efficient and usable app to share their routes.

2. Architecture Constraints

Constraints are fixed technical or bussiness-oriented design decisions that absolutely cannot be changed (maybe negotiable). Most often these are provided by stakeholders at the outset of the project. Sometimes a team may choose to create a constraint, perhaps to simplify the world in which they are working

Table 3. The main constraints are the following
Constraint	Explanation
SOLID	We are forced to use the SOLID framework and its features in order to develop our application
ReactJS	The use of the ReactJS framework
Decentralized network system	Being able to develop a functional project while maintaining the decentralized network system having in consideration all the challenges it may bring to the team
Independency	Make sure that the files that store the routes are independent of the application
Flexible Web Interface	Implementation of a web interface flexible enough to be used in a variety of devices
Tests	The need of implementing a variety of tests in order to maintain the funcionality of the application and find possible bugs
Version Control	The use of a GitHub repository in order to keep the development of the project in check and always available
Geo file standard	The need of searching and choosing a file format to store the routes (viadeSpec)
Time schedule	We have limited time to deliver a final version in May/June
Code coverage	The use of certain tools in order to evaluate the quality of the code itself.

3. System Scope and Context

The project will be an application that allow users to share their routes, images or videos with anyone. The client will be any of these users. The application will be done in a decentralized network using SOLID and made using the framework ReactJS.

The users will be able to:

Save a route in his PODS.
Visualize the routes in a map.
Share files, images and videos with anyone.
Receive friend notification.
Make friends groups

Representative diagram:

4. Solution Strategy

Framework React
This is a framework focused on JavaScript that will help us developing our app, facilitating the communication between interfaces and services.
See [02_architecture_costraints.adoc]

Asciidoctor
This is the text processor we are using to write the documentation of our app.

Node.js
It’s a runtime environment that allows us execute JavaScript outside of a web browser and therefore it will help us to display the app.

Solid POD
Solid pods are the way in which users will store their information in order to share and use it in the app.

Github
It is a repository in which we upload the code with the documentation

5. Building Block View

The main structure of this project consist on dividing the app in a lot of small parts that will be inside a bigger one.

Some of this parts will be the different components of the application that will contain the files referred to the user interface and some logic related to that component. There is also a folder intended for the logic that manages the whole interaction between components.

Another important part of the structure is the folder containing the domain model of the application.

Scope and context

Name

Responsability

Actor

It is the user who uses our application. It can be a hiker, a cyclist, ..

Viade

It’s our web app

POD’s

It is the storage server of the routes and with which our application connects

Level 1

Contained blackboxes:

Name

Responsability

Map

It is in charge of handling the entire issue of viewing the map, showing routes downloaded from the POD and uploading routes to your POD. That is why it communicates with Leaflet, outside of our application. It also communicates with Notifications with which it can send notifications. Lastly, it communicates with the POD to be able to upload or download the routes.

Notifications

It is in charge of sending messages to the user. Receive the message of why this notification is sent and from the friends to whom it should be sent and leave it lodged in it. Then he can read them from there.

Friends

The friends are in charge of receiving and sending the friendships of the POD. Also friends who are erased. Communicates with notifications only when you add a friend to let them know.

Level 2

5.1. Map

Contained blackboxes:

Name

Responsability

MapView

It is the view of the map and its utilities. Receive the map components and display them

MapComponents

It is all you need to show all window utilities in the right places. It also gives the possibility to create your route

Friends

Here the friends are shown to later share a route. You need the friendsManager to be able to show them

ShareRoutes

Use the friends and the route that is drawn on the map to send it to the POD of the selected friend

UploadRoutes

Take the route created in the MapView and adding a name and optionally, photos and videos, the service takes care of uploading it to your POD

DownloadRoutes

When requesting this service, access your POD, and from which it shows them on the map

5.2. Notifications

Contained blackboxes:

NotificationsView

It is the notifications tab. Receive the components to be seen and receive all the notifications from the POD

NotificationsComponents

It is all you need to show all window utilities in the right places

NotificationManager

Manages the flow of when you have to show or send notifications. When they load the notifications tab, send the receiver to act and pass the notifications to them to be painted. When you have to send them, you only need the message and the friend you want to send it to. Connects to the POD to send as to receive

Sender

The sender is called from the manager. This receives the message and the friend’s ID and connects with the POD to leave the message in their inbox

Reader

It is sent by the manager every time the page is reloaded and connects to the POD and the POD brings back all the messages in the inbox

POD

You have an inbox folder which is where you store the messages

5.3. Friends

Contained blackboxes:

Friends

It is the component where everything related to friends is drawn

AddFriend

It is a service that is responsible for adding a friend by their webID

DeleteFriend

It is a service that is responsible for removing a friend from the friends list

getFriends

It is responsible for listing the friends of the POD. Changes to add and delete friends are also transmitted

CheckID

Auxiliary method that checks if the id is correct

FriendAlreadyExit

Auxiliary method that verify if you are already a friend of the friend you want to add

6. Runtime View

This is not a definitive version. We will be adding more scenarios later

6.1. How does the application login work?

Shows the login of the application and how the whole process works.
An user enters their credentials in the login interface. Then, that interface sends the request to the authenticator, which in turn validates the data on the SOLID server. From here, two situations can occur:
- The first is that the session is correct and then loads the new graphical interface (that of the application) and then loads its own routes from its own POD.
- The second option is that the login is invalid, which causes the graphical interface of the login to be loaded again with an error message.
Notably,the SOLID server is different from the user’s POD.

This is the sequence to generate the uml:

6.2. Add route

Show how a route is added to the application.
The user wants to add a route. In the application there will be a button or something similar in which you can add a route. When everything requested to save the route has been added, there will be a service that validates that the route is correct. This service will try to save the route in your POD. From here, two situations can occur:
- That the route is saved successfully and you receive a message that it was saved correctly.
- Or that the route could not be saved and you receive an error message.

This is the sequence to generate the uml:

6.3. Map view with routes

The user clicks on the "View map" button and then clicks on the route of his pod that he wants to see on the map.
Then the service will take care of asking the POD for that route and show it on the map, which here is divided into two options:
- You have chosen a route and it has been possible to download the POD, which will be shown on the map
- You have chosen a route and it could not be downloaded from the POD, which will show an error message

This is the sequence to generate the uml:

6.4. Share routes

The user clicks on the "Share routes" button and And you can click on the route you want to share.
Then you can select the friend with whom you want to share that route and the service will take care of getting that route from your POD and send the route to your friend’s POD:
- You have chosen a route and it has been possible to download the POD and it has been successfully sent to your friend
- You have chosen a route and it could not be sended to your friend’s POD, which will show an error message
- If the route has been received correctly notify your friend that they have a new shared route
- If the route could not be received, a notification will be sent to your friend that the route could not be received.

This is the sequence to generate the uml:

6.5. Notifications in add friend

The user goes to the Friends tag. Click the add friend button
The service will try to add the friend to the POD profile. It also posts a message in the POD inbox
- If all goes well, you are added as a friend. If you don’t send a message that something went wrong
When the friend looks at their notifications, they will see a notification that the user has added

This is sequence to generate the uml:

7. Deployment View

7.1. Infrastructure Level 1

Users must have a device with an Internet connection and a web browser, preferably Firefox or Chrome, which are the web browsers with which we have developed the Viade application. It is also more recommended computer than mobile device since it is not optimized for the latter. The Viade application is hosted and working on GitHubPages. In order to access the web application it is necessary to have acquired a Solid POD, it can be obtained from the Solid Inrupt page or from the Solid Community. The POD will be on a Solid server.

Motivation

The motivation is that users can transparently use the PODs and be able to see their routes and save them.

Quality and/or Performance Features

Performance can be affected by three factors:

Internet connection of the user. Uncontrollable from us
POD server. Also uncontrollable by us
Code performance. This if uncontrollable on our part. From which we are committed to using the best code that provides the best performance

Mapping of Building Blocks to Infrastructure

It looks good in the diagram but the main components of the application are:

the user’s device (PC, tablets, mobile, …)
the web browser (Firefoz, Chrome, …)
the web server (GitHub pages)
the user’s POD (Inrupt or Comunnity)
the POD’s server
the app itselft

8. Cross-cutting Concepts

This section is intended to describe the general ideas, regulations and concepts that apply, either to the whole system, or to several parts of it.

8.1. Domain concepts

A route contains a unique name and consists of a series of points, which must be at least two.
Map points contain longitude and latitude
Pod: user repository, following the SOLID specification. It can be located anywhere, not on a single platform.
Client: the viade program running on the user’s browser. Its responsability is to give the functionality, not to store the data.

8.2. User Experience

For us the user experience is a high priority in our application. So we made a commitment to make an application in which the maps and all the functionality were iterative.

8.3. Architecture and design patterns

Up until know, the viade is an React system, therefore following the Model View Controller architectural pattern. However, all our application would not store any of the user’s data. It will access it via SOLID pods.

8.4. Persistency

Persistence has been achieved using JSON and multiple converters to different types. It has also been achieved using an RDF standard. Persistence in Viade will be achieved following the SOLID specification.

8.5. Testing

Two types of testing are currently in place:

Unit testing: in charge of testing the low level features of the system.
End to end: in charge of testing the general behavior of the system by mocking a real user.

8.6. Building

The building of the project, considering that it is an React application, is done via the Node.js package manages, npm. It is expected to be built using the docker platform, in order to avoid dependencies and enviorment issues.

8.7. Security

The application will use secure communication channels. We will use the protocol HTTPS. With them we ensure te authenticity and integrity of the data sended and received from the pods.

8.8. Internacionalization

The application will be internationalized to the two most spoken languages in the world, Spanish and English. We believe it is a good way to reach a higher number of users.

9. Design Decisions

Some design decisions are also involved in point 4.
See [04_solution_strategy.adoc]. Here are some of the most important:

Section	Decision	Date	Pros	Cons
Programming language	Javascript	11-02-2020	Async task	Better handling of language
Design Pattern	MVC (Model View Controller)	18-02-2020	Easy to implement and efficient	Simple
IDE	Visual Studio Code	20-02-2020	Easy to use and very complete.Ability to add extensions	Some cons are solved with extensions
Testing	Unit Tests	16-03-2020	Tests incorporated into the React skeleton	Does not perform exhaustive tests, you have to do them
Map	Leaflet	10-03-2020	Javascript library that shows us the map and allows us to put points. It’s free.	Other competitive libraries
Storage	JSON / RDF	27-03-2020	Most used language and persistence	Just support one
Friends	query-LDflex	28-04-2020	Solid ecosystem	A little limited in several ways

Section

Decision

Date

Pros

Cons

Programming language

Javascript

11-02-2020

Async task

Better handling of language

Design Pattern

MVC (Model View Controller)

18-02-2020

Easy to implement and efficient

Simple

IDE

Visual Studio Code

20-02-2020

Easy to use and very complete.Ability to add extensions

Some cons are solved with extensions

Testing

Unit Tests

16-03-2020

Tests incorporated into the React skeleton

Does not perform exhaustive tests, you have to do them

Map

Leaflet

10-03-2020

Javascript library that shows us the map and allows us to put points. It’s free.

Other competitive libraries

Storage

JSON / RDF

27-03-2020

Most used language and persistence

Just support one

Friends

query-LDflex

28-04-2020

Solid ecosystem

A little limited in several ways

Routes sharing is unidirectional.
It means that an user doesn’t have to share his routes to another one once the second one has shared his own routes.

Syntax of the storage.
Choosing the language in which to write the routes is a very difficult decision. A chat was enabled to discuss it (viadeSpec), but there was no consensus. So we have decided to support JSON and different parsers for other types of files.

10. Quality Requirements

10.1. Quality Tree

The following file represents the quality tree in wich are defined quality attributes and scenarios

10.2. Quality Scenarios

In this section we take a deeper look at some of the quality requirements mentioned in the quality tree:

Type	Explanation
Responsiveness	The application should use the minimum amount of system resources in order to work smoothly in most current devices
Response Time	The notifications, storage, share features and POD management in less than 15 seconds (It depends on the internet speed, the amount of notifications you have and the routes and their images and videos.).
Error Handling	Lighter errors should take no next to no hit on system performance and fatal errors must be notified in detail to the user
Multi-device support	The application must work across a wide range of devices with different sizes and different platforms (mobiles, tablets, PC, …)
Data portability	Routes are stored in a format that allows the use of said files in other route-oriented applications
Share Features	Users are the only entities capable of allow sharing of their routes to other users
Permissions	The application must ask permission to the user in order to gain access to funcionality of the device such as GPS signal, wireless communication and such others
Accessibility	The app must meet at least the minimum accessibility standards in order to guarantee a wide user base
Look and Feel	The app should be good looking and the interface needs to be desgined in a way that allows a coherent aesthetic between all the options and accessible at the same time
Social Features	All social features such as share routes or send files to other users are blocked unless the user is authenticated. Otherwise the user cannot use said options
Data Storage	Users have the choice of storing their routes locally in the device while maintaining a copy in their POD
Map	Regarding the design of the map, it has been decided that the map is shown in the center and on the side, in the case of seeing routes, showing the name of the route and the other routes of the user. In the case of wanting to upload your route, a dialog will be displayed in which you can write the name and save it through a button

Type

Explanation

Responsiveness

The application should use the minimum amount of system resources in order to work smoothly in most current devices

Response Time

The notifications, storage, share features and POD management in less than 15 seconds (It depends on the internet speed, the amount of notifications you have and the routes and their images and videos.).

Error Handling

Lighter errors should take no next to no hit on system performance and fatal errors must be notified in detail to the user

Multi-device support

The application must work across a wide range of devices with different sizes and different platforms (mobiles, tablets, PC, …)

Data portability

Routes are stored in a format that allows the use of said files in other route-oriented applications

Share Features

Users are the only entities capable of allow sharing of their routes to other users

Permissions

The application must ask permission to the user in order to gain access to funcionality of the device such as GPS signal, wireless communication and such others

Accessibility

The app must meet at least the minimum accessibility standards in order to guarantee a wide user base

Look and Feel

The app should be good looking and the interface needs to be desgined in a way that allows a coherent aesthetic between all the options and accessible at the same time

Social Features

All social features such as share routes or send files to other users are blocked unless the user is authenticated. Otherwise the user cannot use said options

Data Storage

Users have the choice of storing their routes locally in the device while maintaining a copy in their POD

Map

Regarding the design of the map, it has been decided that the map is shown in the center and on the side, in the case of seeing routes, showing the name of the route and the other routes of the user. In the case of wanting to upload your route, a dialog will be displayed in which you can write the name and save it through a button

11. Risks and Technical Debts

The main risks we have identified in the implmentation of this application are the following ones:

Risk	Solution
Adaptation between members of the team	We are 5 people who have worked together rarely or none and, although we know that this is what our future probably holds to us, the lack of communication or rapport between all of us is still a risk.
Short term reviews	We have very little time to develop the first version of our application (3 weeks) and if we don’t organize well it can be a disaster.
Support more route file formats	In the absence of a decision to allow interoperability. The decision was to format one of the most widely used in the world for data transfer, JSON. We leave as a possibility to expand some parsers to allow more types of files. Addapt to viadeSpec
Interoperability	The folder structure to save routes is granted but there are no parsers to obtain other routes. It is another reference to the previous row.
Group functionality	We decided to give more priority to other functionalities, since this functionality was complicated since we have a one-way prototype only. But we believe that this solution is of sufficient quality to be put into production
Sharing routes with groups of friends	We have not been able to implement the sharing of routes with a group since as we saved the groups it gave an error when sending the route to several friends

Risk

Solution

Adaptation between members of the team

We are 5 people who have worked together rarely or none and, although we know that this is what our future probably holds to us, the lack of communication or rapport between all of us is still a risk.

Short term reviews

We have very little time to develop the first version of our application (3 weeks) and if we don’t organize well it can be a disaster.

Support more route file formats

In the absence of a decision to allow interoperability. The decision was to format one of the most widely used in the world for data transfer, JSON. We leave as a possibility to expand some parsers to allow more types of files. Addapt to viadeSpec

Interoperability

The folder structure to save routes is granted but there are no parsers to obtain other routes. It is another reference to the previous row.

Group functionality

We decided to give more priority to other functionalities, since this functionality was complicated since we have a one-way prototype only. But we believe that this solution is of sufficient quality to be put into production

Sharing routes with groups of friends

We have not been able to implement the sharing of routes with a group since as we saved the groups it gave an error when sending the route to several friends

12. Glossary

Term	Definition
Solid	A web decentralization project that aims to separate user’s data and applications, led by Tim Berners-Lee, the inventor of the World Wide Web. This is the project in which this project is based on. SOLID It stands for Social Linked Data
POD	An Acronim for 'Personal Online Data', it refers to the personal decentralized storage used in SOLID applications. Its stores the data from the user outside of the application, allowing the user to retain control and ownership of personal information.
Linked Data	It is the way SOLID connects different POD’s resources. Those links are typed, this means that they contain additional information.
Distributed Network	A network that hasn’t a central server, instead all of the clients can act like it.
ReactJS	A JavaScript framework to build user interface. It’s based on Components items that render on screen.
Stakeholder	Individual or entity that shows any kind of interest in the product and that has a certain power of decision in it.
Git	Distributed version-control system used to track changes in code during software development that allows teams to work together.
Codacy	Software tool for automatic identification of security issues, code duplication, code complexity and code analysis.
Decentralized Web	New vision for the web that is build around blockchain technology where users own their own data. Data is portable, resources are provided by end-users within distributed networks, apps run locally on end-user devices and platforms are decentralized and autonomous. This project aims to help to contribute to said vision.
Leaflet	an open-source JavaScript library for mobile-friendly interactive maps
WhiteBox	Machine or system whose internal structure or processing is known in addition to the knowledge about its inputs, outputs, and the relationship between them.

Term

Definition

Solid

A web decentralization project that aims to separate user’s data and applications, led by Tim Berners-Lee, the inventor of the World Wide Web. This is the project in which this project is based on. SOLID It stands for Social Linked Data

POD

An Acronim for 'Personal Online Data', it refers to the personal decentralized storage used in SOLID applications. Its stores the data from the user outside of the application, allowing the user to retain control and ownership of personal information.

Linked Data

It is the way SOLID connects different POD’s resources. Those links are typed, this means that they contain additional information.

Distributed Network

A network that hasn’t a central server, instead all of the clients can act like it.

ReactJS

A JavaScript framework to build user interface. It’s based on Components items that render on screen.

Stakeholder

Individual or entity that shows any kind of interest in the product and that has a certain power of decision in it.

Git

Distributed version-control system used to track changes in code during software development that allows teams to work together.

Codacy

Software tool for automatic identification of security issues, code duplication, code complexity and code analysis.

Decentralized Web

New vision for the web that is build around blockchain technology where users own their own data. Data is portable, resources are provided by end-users within distributed networks, apps run locally on end-user devices and platforms are decentralized and autonomous. This project aims to help to contribute to said vision.

Leaflet

an open-source JavaScript library for mobile-friendly interactive maps

WhiteBox

Machine or system whose internal structure or processing is known in addition to the knowledge about its inputs, outputs, and the relationship between them.

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