1. Introduction and Goals

The objective of this application is to connect users that want to share the routes they make with other people, as other commercialized apps do, but adding a step further in the level of control of their data, thanks to SOLID specifications. The app is aimed to contact with the pod of each user, allowing them to manage the permissions over their information.

1.1. Requirements Overview

In this application we aim to develop a decentralized routes social network. We aim to achieve the following:

Requirements

The system will be based on a decentralized architecture where data is stored inside the pod of each user.

Users can see their routes in a map, as well as sharing them via multimedia or information with their friends.

The application will provide a notification system.

Users can have groups of friends with whom they may want to share a route.

Interoperability with other route management systems should be taken into account.

1.2. Quality Goals

Ref. Quality Goal Description

1

Usability

It must be a simple application to ensure that any user, independently of their expertise, can use it to its full potential.

2

Performance

Ensure that our app runs fluently and that access to data is fast to avoid loading screens.

3

Testability

The app must be tested exhaustively, so bugs and programming errors are minimized.

4

Security

Although the app must have some security measures, performance and usability limits strict security, so it will not be as important to avoid loosing these other attributes as a tradeoff.

5

Reliability

The number of errors should be minimized to achieve consistency and increase the level of confidence of our users. A good degree of testability should help improve reliance

1.3. Stakeholders

Role/Name Contact Expectations

Developers

Jesús Quesada Matilla, Daniel Finca Martínez, Nicolás Mencía Gómez, Óscar Sánchez Campo, Diego Ramírez Amandi, Pablo Fernandez Martínez

A well designed architecture to acomplish SOLID specifications and fulfill all the requirements planned.

Teachers

José Emilio Labra Gayo, Pablo González González

Obtention of a robust application that shows off everything learned in the course and that proves a well organized team that know how to adapt to new technologies.

Inrupt & Solid community

Sir Tim Berners-Lee, info@inrupt.com

A decentralized product that provides an alternative to massive centralized databases of nowadays companies.

Ana

Client

She works in an office and wants to share with her colleagues the routes she does in the weekend

Michael

Client

He has just retired and wants to look for routes to do in his free time. He can look for it asking to his friends, but they cant explain him everything about some route in a conversation.

Helen

Client

She is worried about sharing her data in a centralized application and prefers to have control over it over time instead of uploading it to a centralized database.

2. Architecture Constraints

Architectural constraints are divided into three sections: * Technical * Organizational * Conventions

Each one of them is broken into two parts: Constraint and a brief explanation of its existence.

Table 1. Technical Constraints
Constraint Explanation

JavaScript

The programming language used for the most part of this project.

React

JavaScript library for building user interfaces. Reference: "https://reactjs.org/"

Git

A distributed version control system.

Node.js

Node.js is a runtime system used mostly for making server side applications with JavaScript. Reference: "https://simple.wikipedia.org/wiki/Node.js"

SOLID

Solid (derived from "social linked data") is a proposed set of conventions and tools for building decentralized social applications based on Linked Data principles. Solid is modular and extensible and it relies as much as possible on existing W3C standards and protocols. Reference: "https://solid.mit.edu/"

Arc42

Template for architecture communication and documentation. This technology will be the base of this project’s documentation.

Travis

As a continuous integration platform, Travis CI supports your development process by automatically building and testing code changes, providing immediate feedback on the success of the change. Reference: "https://docs.travis-ci.com/user/for-beginners/"

CodeCov

Codecov provides highly integrated tools to group, merge, archive, and compare coverage reports. Reference: "https://codecov.io/"

Codacy

Automatically identify issues through static code review analysis. Get notified on security issues, code coverage, code duplication, and code complexity in every commit and pull request, directly from your current workflow. Reference: "https://www.codacy.com/"

Table 2. Organizational constraints
Constraint Explanation

Working in a team

Must work on a team of 6 people.

Release dates

The project has to meet the deadlines of the course.

Version control

Github has to be used for taking keeping track of the progress done on the project.

Meetings control

Minutes of all the team meetings that occur should be recorded and uploaded to the project wiki.

Table 3. Conventions
Constraint Explanation

Clean code

The project follows clean code conventions so it is easier to maintain.

Language

This project has to be internationalized. For that we use react-i18next. Reference: "https://github.com/i18next/react-i18next"

3. System Scope and Context

The stakeholders of the application are described in the next lines and how the communicate.

3.1. Business Context

BusiContext

This is a high level view of the system. Showing the main idea behind the app.

User

The user creates routes on our application or in other compatible aplications that use viadeSpec standard.

User Friends

User SOLID friends can also create routes in their favourite application following the standard.

Applications

Both applications will communicate between each other, showing and editing the routes or creating them. For an application to be considered compatible it must follow ViadeSpec.

3.2. Technical Context

TechContext

Here we show deeply how the communication is done and which are the important parts of the system.

3.2.1. Internally Controlled:

Application Front End

We use React to design it and Bootstrap to ease the design of the interface. It is our framework of choice for the frontend of the application, so this part will be developed in javascript and HTML. Its task is to build the HTMLs views which the user interacts with.

Application Back End
rdflib

It’s a library used to communicate with the Pods (where the information is stored); to fetch and update data whenever necessary.

solid-file-client

A library used to store files in any format to the PODs.

solid-auth-client

A library used to authenticate a user securely and have access to parts of their PODs.

solid-acl-utils

Used to manage POD’s permissions.

ldflex

It’s used to query data from the different PODs.

The application is based on the SOLID project for the re-decentralization of the web, therefore each user is the owner of its own data through the mentioned Pods.

3.2.2. Externally Controlled:

On the above graph we show an example on how would the communication be when creating a route and being shown in another compatible application. Information always goes through the POD, following the order marked by the numbers, and once there, compatible applications will manage to show the routes in the way they do.

Although not depicted by the example, it can also be possible for both applications to swap roles and for our application to correctly display the routes the other application has created.

4. Solution Strategy

4.1. Summary

This application is implemented using Javascript, React.js, SOLID specifications and many other dependencies gathered thanks to npm. Its architecture follows the MVC pattern.

Allows users to authenticate into the system with their SOLID account and manage their routes (stored inside their pod). These routes can be created by the user, already predefined in the system or shared by other users.

Pod decentralised data storage alongside a route shape standard provide our application with interoperability with other route management systems, like all the other Viade proyects.

4.2. Some solution approaches

Quality goal Scenario Solution approach Link to Details

Standards

Route data model

Elaboration of a data model

Viade data model

Perfect imperfection

Application design

The intent of fulfilling our goals while understanding that errors have their place

Examples at Simplicable

Data ownership

Information storage

Personal SOLID pod storage

SOLID webpage

5. Building Block View

5.1. Whitebox overall system

This application has a very simple top level design. This is introduced by System Scope and Context.

BuildingBlockLevel1
Viade application

It’s the application we’re talking about.

External APIs

We use some APIs available on the internet, to manage maps and points. They are detailed in the last point of this section.

PODs

As we said is the service we use to store routes, groups and all the user’s information. Through them, we allow other compatible apps to share data with us.

Contained blackboxes
Name Responsibility

Viade application

Main blackbox, contains every key component. Manages routes in every possible way allowed in our application. As well as with the user’s pod. Also manages connections with other dependencies that will be explained down below.

Other applications

Generation of route serialisation in supported formats to be processed by Viade applications. Blackbox decomposition out of the scope of this documentation.

5.2. Whitebox: Our application - Viade

This whitebox contains several blackboxes that depend on a series of interfaces to external sources of information. These modules can be seen in the diagram image shown below.

ViadeWhiteBoxLevel2

This representation focuses on functionality. Hence some components wont match their corresponding file or might be represented by more than one file. Some other functionalities weren’t represented since they were considered as non-relevant.

Contained blackboxes
Name Responsibility

RouteCreation

Contains the functionalities that can be used by the users to create new routes. Once created, provided a list of values with some requirements, the route is stored inside the user’s POD.

Profile & group management

Provides the users with the ability to inspect their profile and manage their groups of friends.

RouteList

Lists the set of routes stored inside the user’s POD. Gives the option to learn more about the route, such as its points, altitude of them or media related to them.

PODService

Helper module to stablish a connection with the user’s POD. Provides an interface with a series of operations commonly used to manage information such as routes.

ElevationChart

Wraps an interface component in charge of the display of the route points' altitudes.

RouteModel

This blackbox contains the whole model used to represent and manage routes inside Viade. This module is one of the keys of this application.

RouteInfo

This component (yet another interface one) displays information about the route in a fancy way. Some things like its name, description, author, points on a map, altitude of those points and a gallery of images.

Interfaces
Interface Description

Solid-file-client

This one allows the application to manage files when using the POD storage. More on this one here.

Solid-auth-client

This one is needed to obtain and manage user session details with regards to SOLID POD and account. More information about this API here.

Solid-acl-utils

Utilities used to manage POD’s permissions. More info here

N3

A library used to parse turtle files. Required for some files of the POD as, for example, inbox notifications. More info here.

Airmap elevation

This API provides a result for the elevation of a couple of coordinates given latitude and longitude. More info here.

Leaflet

This API is needed to mainpulate the map components that React-Leaflet provides. More on that here.

Nominatim

It’s a free search engine to allow looking for concrete places and get their coordinates. More info here

6. Runtime View

6.1. Route Creation

RouteCreation

The user creates a route using the map in the UI. Each time he creates a new point a temporal object is created which stores name and description. Moreover, at creation time or when it’s position is updated, a real point is created (without name and description) in order to ask the API for its altitude. This process is asynchronous and once we have the response the elevation chart in the view is updated. Finally, when all the points are created, the route is decorated with name and description for all the points. Then, it’s uploaded to the POD.

6.2. Route Listing

RouteListing

The process for listing routes is the following.

  1. The Route Manager gets cleaned in order to then load the new routes.

  2. A POD Storage Handler is created with the current user to gain access to the POD.

  3. The method getRoutes() starts an asynchronous route loading.

  4. For each of the routes retrieved we create a new one, and populate it with the data returned.

  5. The route is then added to the manager and printed in the screen for the user.

7. Deployment View

Viade is a client application, so we don’t have multiple servers or a complex topology to explain here. Therefore, this will be very simple.

7.1. Infrastructure Level 1

DepView
Table 4. Legend
Part Explanation

Internet Available APIs

All the APIs we use are free, and online accesible.

Viade App

Our app will be deployed in GitHub Pages.

Solid PODs

They are allocated in Inrupt or Solid Community servers and maintained by them.

Motivation
  • The use of Internet Available APIs is an advantage. Thanks to this we don’t have to store maps in our central server (which we don’t have) nor in the client.

  • Using GitHub pages avoids us to configure and mantain a server. All system administration is provided by GitHub.

  • The use of Solid PODs is a constraint.

Mapping of Building Blocks to Infrastructure

The mapping seems pretty clear. The "Viade Application" blackbox is the web displayed. The interfaces shown are the ones we refer here and also the PODs.

7.2. Test Environment

Tests of the application are a relevant aspect of Viade.

Test Framework Explanation

Travis

Thanks to Travis we can assure the continuous integration of Viade whenever a new feature is added. Travis takes care of running all the Jest tests as well as running code coverage revisions. Finally, if everything is correct, the application is built and updated.

Jest-Dom Testing Library

Tests whether the intended React components load correctly in the application.

Code Coverage

Checks for the amount of code that was run when performing the tests, useful to know precisely how deep the tests performed.

Codacy

Codacy checks for code quality. With it, we can easily create good quality code that follows the standards.

Cucumber

Helps with the simulation of the user’s experience when using the app. It acts as if a user was using the application, and doing so, tests it for errors that may be present.

POD in Docker

As connection with the remote POD across the internet is not reliable, Docker can be configured to act as a server where a POD is stored. Doing so, the connection is ensured and all POD access tests can be performed risk-free.

Motivation

Testing increases code quality and assures Viade’s viability and security.

Quality and/or Performance Features

Repairing errors and mistakes increases every aspect of quality. All the testing will also ensure we understand where are the most used parts of the application and what should be optimised.

8. Cross-cutting Concepts

8.1. Package Structure

The package structure followed during the development of the proyect is this one. Inside src folder we can find the following.

PackageStructure
Assets

Contains the images to be displayed, as logos or the main window photos.

Components

Reusable components used in many parts of the application. For example, the maps, elevation chart…​

CSS

Some parts need special CSS rules. The files that defined them are here.

Docs

The folder where this documentation is stored.

Model

Contains the classes that define the data model (MyRoute) and also the classes that manage them.

Pages

Has inside those views that are directly shown to the user. It’s the final arrangement of the individual React components.

Tests

Contains all the tests of the application.

8.2. Route Management Model

Class diagram containing the classes that manage routes

ClassDiagram

8.3. Navigation Map

NavMap

8.4. Viade Specification

With the creation of this specification we can follow a standart, making sure we can communicate with other applications and therefore creating a network of route management systems available to the users.

9. Design Decisions

9.1. Not Use React Native

We decided to postpone the use of React Native.

Pros
  • Allows creating apps for Android and iOS with the same code than the web application.

  • Dynamic HTML pages can be easily created.

Cons
  • Will take time to learn the language.

  • Less pre-created components available.

  • Not much advantage in using it, as the main functions can be emulated using a web browser for mobile phones.

9.2. JSON-LD Format for Routes

Pros
  • The use of a standard makes it easy for the application to communicate with other services.

  • We follow Viade Specification, therefore making sure we can exchange information with other compatible applications.

  • JSON notation which is already known by us.

Cons
  • PODs dont have yet a way to view the files in this format.

9.3. Leaflet

We chose Leaflet as our map provider.

Pros
  • It provides the advantage that is OpenSource and that it doesn’t need any API Key. This was the main reason why we discard Google Maps.

  • Also with React-Leaflet library, we don’t have to program the basic components such as Map, Marker or Polyline. They came already implemented.

Cons
  • None of us has previously worked with this tool, so it’s another thing to learn.

9.4. Chart.js

We chose chart_js as our plotting tool.

Pros
  • Has react suport to ease the task of developing the charts

  • It’s free.

  • It’s well documented.

Cons
  • Needs a lot of code to configure the charts.

9.5. Storing altitude for points in the POD

Pros
  • Reduces latency when displaying points as it only checks the altitude of each point once.

  • ViadeSpec points seem to follow this approach.

Cons
  • More space occupied

9.6. AirMap Elevation API

Pros
  • It’s free

  • Doesn’t need API Key

  • Easy to use (just a single GET request)

Cons
  • For some points, such as seas, lakes or oceans may not give a response.

9.7. Sharing of routes

Our approach saves all files in a private directory (that is, viade/ inside the POD). Then, when sharing, giving the user’s friends rights to view the files and sending a notification to each user of the newly shared route to them.

The other approach would have been saving everything on public/ directory.

Pros
  • Privacy and sharing for particular users is allowed.

  • A user can have his own private routes.

Cons
  • Harder to implement.

  • If not careful may result in loss of rights on files.

  • A need of learning a library or method to edit the permissions of the POD.

  • Creating a notification system to inform to the receiver of the share.

10. Quality Requirements

In this section we expand and go into more detail in our quality goals, already defined in the 1st section of our documentation.

10.1. Quality Tree

Here our quality tree is represented, showing the most important quality goals beside their requirements, linked with its quality scenario related

QualityTree

10.2. Quality Scenarios

Ref

Quality Attribute

Quality Scenario

1

Usability - Seamless UI

Ana, Michael and Helen must be able to learn how to use, without external help, our application

2

Usability - Compliance

UI complies with the WCAG level AA

3

Performance - Responsive

User interaction must be reflected with a low response time, with a maximum acceptable limit of 1 second

4

Performance - Loading times

Loading times don’t have to be a bother to the user, with an average of 2 seconds

5

Testability - Fully tested UI

We must reach a suitable coverage percentage, 50% at minimum

6

Security - Data security

If an unauthorized user access is detected it must be reported

7

Reliability - Error handling

95% of the errors have to be handled by the program, not leading to a system crash

11. Risks and Technical Debts

In the developement of the project, we expect to find the following difficulties (ordered by priority):

Ref Risk/Debt Consequence Suggested Solution

1

New technology

A considerable technical debt in regard to the tecnologies proposed, as both SOLID and React are new to us, that might incapacitate us to obtain the desired result.

Read and obtain information beforehand to obtain the necessary information.

2

Working as a team

A possible lack of coordination, due to our inexperience as a working group and differences as individuals.

Make use of tools like github issues and pull requests to improve as a team.

3

Lack of time

Time management migth also be hard as we can not be 100% devoted to the project.

Organize our schedules and plan the work to be done in the minutes.

4

Software conflicts

Incompatibilities in libraries and software used is also a risk that should be considered.

Check issues in the sofware before using it to prevent conflicts with what is already implemented.

5

SOLID little maturity

Added to our technical debt, we have to take into account that SOLID is a new technology, so support and documentation of it might be scarce.

Share all the information found with our colleagues to share knowledge.

12. Glossary

Table 5. Terms
Term Definition More Information

Solid

Solid (Social Linked Data) a web decentralization project led by Tim Berners-Lee

Solid Website

Pods

Personal Online Data Stores, used to deposit the person’s data

Get Your Pod

GPX

XML schema designed as a common GPS data format for software applications

GPS exchange format

MVC

Software design pattern commonly used for developing user interfaces which divides the related program logic into three interconnected elements

Model-View-Controller

Viade Specification

An specification to follow in order to manage the way in which the routes will be uploaded to the user’s PODs

Viade Specification

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.