1. Introduction and Goals
The aim of the project is to develop a decentralised route tracker, which has to be able to give an excellent performance meanwhile the privacy of the customer is well kept.
1.1. Requirements Overview
According to the priority of each requirement, we can order them as you can read next.
-
The application must implement a decentralised architecture based in the SOLID (Social Linked Data) specifications, therefore stored data must be separated from the app.
-
Information must be stored in pods.
-
Routes will be shown to users on the map.
-
A route should be fed back with relative data, such as shared pictures, videos or comments.
-
Notifications will be sent as a result of a friend sharing a route.
-
There can exist user groups for multiple sharing purposes.
-
Interoperability is an essential part of our specific application, so several apps are able to work with the same information of a route.
1.2. Quality Goals
| Priority | Objective | Description |
|---|---|---|
1 |
Privacy |
As a SOLID project, keeping the personal data is a main quality purpose. |
2 |
Usability |
The app must be easy to use, at least the average user should be able to interact comfortably with viade. |
3 |
Efficiency |
The times of response of Viade should be within a minimum so that the user can interact dynamically and comfortably |
4 |
Consistency |
The application should be consistent. |
5 |
Interoperability |
with other Viade apps that our classmates are creating. |
1.3. Stakeholders
| Role/Name | Contact | Expectations |
|---|---|---|
Teacher |
He will evaluate our project |
|
Solid community |
Resource for the Solid project |
|
Developers |
They will develop the architecture and the code of the application |
|
Inrupt |
They will judge our app because it will be shown in the inrupt challenge |
|
Technical Users |
People that have some experience in the route’s world and know some technical concepts |
|
Non-technical users |
People that is new in the world and have never used a route’s management app before |
|
Disabled users |
Users who have some kind of disability |
2. Architecture Constraints
Here are the tables that include all the project constraints and their explanations.
2.1. Technical Constraints
Previous architecture decisions that may impact the solution design.
| Constraint | Explanation |
|---|---|
SOLID and its PODs for a decentralized architecture |
One of the aims of 'Viade' is to be a decentralized app, so we need a decentralized technology like SOLID and its PODs |
React for presentation |
We were told to use 'React' in our project |
Use of GitHub |
Our project is going to be hosted on a GitHub repository |
Jest |
We need to create tests so we can be sure that our project is correct and it is working like it has to work and we need to have at least a 60% of coverage |
Cucumber |
Our project needs to implements some cucumber tests |
Gatling |
We need to test how the app would work if it’s used by more than one user |
Docker |
Viade has to have a Dockerfile and a docker-compose.yml file |
2.2. Organizational Constraints
The project’s environment. It affects the developing process.
| Constraint | Explanation |
|---|---|
Time limit |
We have to develop the project during our 'Architecture of Software' course, so we have less than 3 months |
Team members |
Our team is formed by 4 software engineering students at 'Universidad de Oviedo' university, so we only can use our free time and course lessons to develop it (and we need to organize our free time so we can study others subjects) |
Course deadlines |
We have 4 deadlines during our course and we need to accomplish the requirements of them during our project developing |
2.3. Documentation Constraints
Decisions about how to document our project.
| Constraint | Explanation |
|---|---|
Arc42 |
We have to use 'Arc42' structure for our project documentation because it is clear, simple and effective and a common tool used in current companies |
Asciidoctor |
We have to use 'Asciidoctor' to create our documentation |
3. System Scope and Context
Viade must allow a user to create and view a route and share pictures, videos or information about a route with other friends. It should be possible to view routes loaded by users that are using a different app, so interoperability with other route management systems should be taken into account.
Security and privacy is Viade priority. Users can store their routes in their own pods and Viade should have online independence, thats it, no central control of data.
Viade can import created routes in some of the most used formats in the routes management apps.
4. Solution Strategy
In this section, we summarize the fundamental strategies and decisions during the development of our project.
First of all, we have to remember that Viade is a decentralized routes management system based on the solid specifications and React framework, so our plans and resolutions need to be consistent with those characteristics.
Let’s talk about Technical decisions:
-
Using JavaScript: We talked about how to implement the logic of the project. We can take advantage of the functionalities of React, but perhaps we would need to implements something more complicated, so we agreed on using JavaScript because we have already used it and it allows us to do all the logic we thought about.
-
Use the React Solid template as a base: We didn’t have much time or experience, so we used a template to start our project. Here is the link.
-
Libraries: Here you can see some of the libraries we used:
Name |
Link |
Comments |
react-i18next |
We used it to for internationalization |
|
react |
Its the software we used for the interface |
|
react-toastify |
We used it to show some notifications to the user (like success messages) |
|
solid-react-components |
some of our components come from here |
|
react-bootstrap |
To create some components |
|
solid-auth-client |
We used it for the login part and uploading data to the POD |
|
solid-file-client |
We used it to search in the POD, load from it, delete files, etc |
|
sparql-fiddle |
We implemented it to be able to use sparql queries in our parsers. |
|
jest |
We used it to implement some test |
|
shx |
To execute some commands (like the one that compiles this documentation) |
|
cucumber |
For BBDD testing |
|
query-ldflex |
We used it to find some info from solid |
|
google-maps-react |
We created our map with it, but we do not recommend it because the author stopped maintaining it |
-
Pull request: We decided to use the "pull request" functionality of GitHub because it seems that it helps you get better results in your commits.
-
Jest: We used Jest to create our tests.
-
WebStorm: We used WebStorm to develop our app because of all the facilities that it gives us for the React programming part
-
Parsers: A good application should be able to admit differents formats, so we used some parsers to let the user create a route through them.
We want to fulfill some quality goals:
-
Usability: Viade has to be intuitive. We are going to use the knowledge acquired during this career.
-
Testability: It is a constraint to create tests, so Viade has to be testable.
-
Availability: You should be able to manage a route at any moment, so Viade has to be consistent.
-
Interoperability: We want out routes to be exportable to other apps so we need to investigate it.
-
Decentralization: It is a constraint on this project.
And this are our organization decisions:
-
Kanban: We also talked about using the "Project" tab of GitHub that resembles a kanban board. We used it to get organized because we used that methodology last semester and it works fine.
-
Issues: We want to register our group communications to show all of our work throughout the making of Viade, so we created a lot of issues in the GitHub repository.
-
WhatsApp: It is quicker and simpler to communicate using a group chat, so we used WhatsApp (the common chat app used in Spain) while trying not to stop creating GitHub issues.
-
English: We agreed on writing it in English because is the prevalent language used in informatic’s documentation projects.
With these decisions and plans, we wanted to create a good decentralized routes management system and fulfill all the requisites of the problem statement.
5. Building Block View
5.1. Whitebox Overall System
Level 1
| Name | Responsibility |
|---|---|
User |
Person who requires the functionality of this application. Is the one who interacts with the application and give the orders. |
Viade |
Decentralised route tracker. It interacts with the POD to store and load the routes, media, information about the user, etc |
SOLID POD |
Decentralised store unit of the user data. Is the part that contains tha information Viade uses. |
Level 2
Giving a deeper insight into Viade application.
| Name | Responsibility |
|---|---|
Viade |
Decentralized route tracker. |
Components and containers |
They describe the code to show the different parts of the application and ints functionality |
Parsers |
They let the user import a created route from other app |
PODs |
Where Viade obtains the routes information, media or user’s data and where viade stores the routes and media created in their classes. |
User |
Same user as the last level |
Routes in a non-turtle format |
Viade can create a route to work with from a GPX, JSON-LD or Geojson route and then create a turtle version to store it in the User’s POD |
Level 3
In viade we have a lot of components in the 3rd level that shoul be described, like the functionaliti of the parsers (when you read a route from the pod is the filewriter class the component that calls the parser, but when you write a route the parser calls the filewriter component), the classes that creates a route calls a parser so they can store the new routein the user’s POD, the media is taken from the POD in the moment that the user wanto to see the route’s details, etc
6. Runtime View
6.1. Log in
The login process will be done by users when they log in with their pesonal id to access the application.
-
The user click login button.
-
The user enters his credentials.
-
Their data is sent to a LoginManager to try to log in.
-
The server can deny or approve the authentication.
-
The user can start using the application’s features.
6.2. Routes Management
The users use the application to manage their routes.
-
The user creates a new route.
-
The user shares a route to a friend.
-
The user comments a route.
7. Deployment View
| Node | Description |
|---|---|
User computer |
Device that connects to the internet to access to Viade. |
Browser |
Software application for accessing information on the World Wide Web. When a user requests a particular website, the web browser retrieves the necessary content from a web server and then displays the resulting web page on the user’s device. |
Host |
Gh-pages. Web host where the application is deployed. The user’s browser accesses it with https requests |
Viade |
Decentralised route tracker. It interacts with the POD to store and load the routes, media, information about the user, etc |
POD Provider |
Solid, Inrupt, own node solid server… |
SOLID POD |
Decentralised store unit of the user data. Is the part that contains tha information Viade uses. |
8. Cross-cutting Concepts
8.1. Dissecting Viade
In Viade we can differentiate 2 parts:
-
Before the Route objects are created
-
After the Route objects are created
In the first part, the objective is to create a route that our app understands and can work with. That is the object Route. Our app will try to convert every route into this object (it can come from a POD, from another file or the user). The reason behind this is that we want to be able to work with different formats so the user won’t have restrictions, but there are a lot of different extensions to represent a route and in the future, it can appear more.
Creating parsers to transform the routes into the same object allows us to separate the logic that has come possibilities to change from the one that is more general and doesn’t have that characteristic. We also can change the way our parsers get the information without the rest of the app noticing.
After we have the Route objects, we can manipulate them. We can show the information, store it, share it,… and in the future we could edit it or show it in different styles.
In our app, we work with routes but we also work with the user’s information. We let him login and logout from different providers, we let him change its profile image, he can choose whether he wants to use Viade in English or Spanish and he can see his friends and share the routes with them.
8.2. Folder Structure
Here you can see a general folder structure of Viade where you can see the important ones.
In the root directory, we have the configuration folder where we have some .config files like the webpack.config.js file that we use for the app tests ad the jest folder.
Then we have the test_mocks_ folders that have some libraries and files that we use for our tests and through all the application like @fontawesome.
The src folder is the most important one because is where our source code is allocated. There you can see the components, constants, and containers of the app (some of the general logic and interface), the resources folder with all of the logos that we have created for Viade, the docs folder with the documentation related files and the utils folder with the parsers, the Route object, the I/O classes, etc.
The feature folder has some other files for testing the app.
The public folder has the images that viade is using (like icons or the actual logo) and the locales with the texts of the app in different folders so viade can be internationalized.
At last, the scripts folder has some js scripts to start the app, build it and execute the tests, to run them you just have to type "npm run " + the name of the script without the extension.
8.3. What do we use
To create our files and work with them, we do not use all of the data that the user gives to us. Of course, if the user creates a route using our map, we would only ask for the necessary data, but if he uses our parsers (geojson, gpx or json-ld) we will only take some data from them, like track points from gpx or name, points, description,… from json-ld. In summary, we will only take the necessary data to create a simple route with the same fields that appear in the page where you create a route with our map (and some others like the author o the fileName, but viade does that automatically)
8.4. Error handling
We decided to show the user some errors that can be important for him. An example is showing wich routes viade can’t show in the timeline because of a bad syntax or internal error. We also try to be consistent and try to make viade be still operative even if there are some errors.
8.5. A valid file
We use turtle to write the routes in the POD. You can use json-ld or any other typical format but only if you use the parsers that viade gives to you. If you want viade to upload a json-ld route from your POD and show it, it won’t happend (at least in this version of viade). A valid route wrote in turtle for viade would be:
@prefix viade: <http://arquisoft.github.io/viadeSpec/>. @prefix : <http://example.org/>. @prefix schema: <http://schema.org/>. @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>. @prefix xsd: <http://www.w3.org/2001/XMLSchema#>. :myRoute a viade:Route ; schema:name "Route" ; schema:description "Description" ; viade:point [ schema:latitude 43.52288176910197 ; schema:longitude -5.672779401110839 ]; viade:point [ schema:latitude 43.52618017535388 ; schema:longitude -5.653982480334472 ]; viade:point [ schema:latitude 43.531469695619926 ; schema:longitude -5.659475644396972 ]; viade:hasComments [ schema:text "This is a comment!" ; schema:publishedDate "7/5/2020" ]; viade:hasMediaAttached [ schema:contentUrl "https://anagciaschz4.solid.community/viade/resources/stay-home.png" ]; viade:hasMediaAttached [ schema:contentUrl "https://anagciaschz4.solid.community/viade/resources/videoplayback.mp4" ] .
8.6. Internationalization
In this version, we only support Spanish and English. We have the infrastructure to add more languages just by creating a new file, so in the future, we can add more if viade becomes popular.
8.7. Testability
At this moment, more than the 65% of our code include test so we can say that more of our code lines seems to work perfectly.
9. Design Decisions
| Decision | Pro | Con |
|---|---|---|
Minimalist style |
It will be more usable and simple to distinguish the options |
It maybe would look boring if we don’t do it properly |
The timeline page will contain all user routes and all routes shared to the user. |
The user will be able to see all the routes at once |
it can be difficult to find a route if there are many created and shared routes |
The new route page will let users create a new route with a map |
Intuitive and usable |
Markers cannot ben deleted |
We will accept routes in the common formats so viade van be a little interoperable |
We give more options to the user |
We have to learn about other formats and how to get the data that we need for viade from them |
The routes can be accessed from the timeline in a popup |
It reduces the loading time |
It is not possible to open more than one route at the same time |
We will show all necessary errors to the user |
It gives the user important information |
If the user has a lot of errors it could give a bad impression of viade |
Information about covid-19 in the main page |
We can inform our users about it |
It’s not information about routes or viade so maybe a user would not like it |
Internationalization |
We can be used by people from other countries |
We can forget to internationalize come parts because we do not have much time |
Use green, purple and white colors |
We can have a consistent look |
It can cause problems to some daltonic users |
10. Quality Requirements
10.1. Quality Tree
10.2. Quality Scenarios
| ID | Quality attribute | Quality scenario | Priority |
|---|---|---|---|
1-P |
Privacy |
The user is the owner of his data according to the SOLID principles but we store the user comments in a route in the pod of the author routes, so we can’t say that the user is the only proprietary of all of his data. We can say that he can control more than 90% of his data |
HIGH/HIGH |
2-P |
Privacy |
The user can control the media that he attached to a route |
HIGH/HIGH |
1-U |
Usability |
The user must have to use all the features of the application easily |
HIGH/HIGH |
2-U |
Usability |
AA daltonic user could use viade because we use colors that don’t usually give them problems |
MEDIUM/LOW |
3-U |
Usability |
The user can automatically give the necessary permissions to a friend while sharing a route with him |
MEDIUM/LOW |
4-U |
Usability |
The user can easily find an option in the viade menu |
MEDIUM/LOW |
1-I |
Interoperability |
The user can upload a route in a geojson format |
MEDIUM/MEDIUM |
2-I |
Interoperability |
The user can upload a route in a gpx format |
MEDIUM/MEDIUM |
3-I |
Interoperability |
The user can upload a route in a json-ld format |
MEDIUM/MEDIUM |
1-M |
Maintainability |
The architecture of the system should be well designed, this will allow the developers to add features and modify it easily |
MEDIUM/LOW |
1-S |
Scalability |
We did some tests and when our app received 2900 request, could process 2534 in less than 800 ms, 270 in less than 1200 ms and only 96 failed, so we can assume that our viade app could process the 95% of the requests in less than 800 ms. |
MEDIUM/HIGH |
1-A |
Availability |
In our tests, viade only failed in the 3% of the request, so we can be available the 97% of the time. |
HIGH/HIGH |
11. Risks and Technical Debts
The project has hardly any risks in the usage scenario, but there are some risks contemplated:
| Risk | Consequence | Possible Solution |
|---|---|---|
Limit the possibility of including videos and images in posts |
Add only one of each (video and image) |
Change the code to let the user add more media |
Use deprecated libraries |
Implement new features can be impossible or quite tedious |
Find new libraries or include new complementary libraries |
Actually, the technical debts are the following:
| Priority | Technical Debt | Consequence | Possible Solution |
|---|---|---|---|
HIGH |
Friend groups |
It is not possible to share routes with more than one user at the same time |
Create a service to share routes to groups |
MEDIUM |
Comments spec |
The comments doesnt follow the Viade specification |
The user’s cant see who posted a comment |
MEDIUM |
Map markers |
User cannot delete an marker from the map |
Use another map API |
HIGH |
Interoperability |
Viade is not interoperable with other Viade’s apps |
Work more with ViadeEspec |
MEDIUM |
Internationalization |
We have some parts that are not correctly internationalized |
have more time to fix it |
MEDIUM |
Parsers |
The parser that writes the turtle has the lines directly in the code and it’s not elegant |
Use ldflex or another library to create the triplets of turtle |
HIGH |
Security |
We have the queries directly in the code so we can suffer an SQLInjection |
extract the query and add it to a protected file |
12. Glossary
| Term | Definition |
|---|---|
Asciidoctor |
Lightweight markup language for authoring notes, articles, documentation, books, web pages, … |
Bootstrap |
The most popular HTML, CSS, and JS framework for developing responsive, mobile first projects on the web. |
Cucumber |
Software tool that supports behavior-driven development (BDD). |
Descentralized |
Something that is not controlled from one central place. |
Docker |
Open source software platform to create, deploy and manage virtualized application containers on a common operating system (OS). |
Framework |
A basic structure underlying a system, concept, or text.. |
Geojson |
Format for encoding a variety of geographic data structures. |
GitHub |
Web-based version-control and collaboration platform for software developers. |
Gpx |
Gpx, or GPS Exchange Format, is an XML schema designed as a common GPS data format for software applications. It can be used to describe waypoints, tracks, and routes. |
I/O |
Short for input/output (pronounced "eye-oh"). The term I/O is used to describe any program, operation or device that transfers data to or from a computer and to or from a peripheral device. |
JavaScript |
An object-oriented computer programming language commonly used to create interactive effects within web browsers. |
Jest |
A delightful JavaScript Testing Framework with a focus on simplicity. |
JSON |
JavaScript Object Notation is a lightweight data-interchange format. |
JSON-LD |
JavaScript Object Notation for Linked Data is a method of encoding linked data using JSON. |
Kanban |
Visual system for managing work as it moves through a process. |
Minimalist |
Design approach that is characterized by austerity and laconism in decoration. |
Parser |
Compiler or interpreter component that breaks data into smaller elements for easy translation into another language. |
POD |
A personal storage space in SOLID. |
Popup |
Graphical user interface (GUI) display area, usually a small window, that suddenly appears ("pops up") in the foreground of the visual interface. |
Puppeteer |
Node library which provides a high-level API to control headless Chrome or Chromium over the DevTools Protocol. It can also be configured to use full (non-headless) Chrome or Chromium. |
React |
A declarative, efficient, and flexible JavaScript library for building user interfaces. |
Script |
A type of language for programming computers that is used for finding and showing websites on the internet. |
SOLID |
A web decentralization project. Its mission is to reshape the web as we know it. |
Viade |
Decentralized routes management system based on the solid specifications and React framework. It’s the project that we are talking about. |
WebStorm |
Powerful IDE for modern JavaScript development. |
Free to download messenger app for smartphones. |
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.
© The Viade_ES2C team