Note

This project is based on live documentation, currently in WIP.

1. Introduction and Goals

The goal of this project is to create a decentralized routes management system based on Solid specifications.

1.1. Requirements Overview

Requirement Description

Decentralized arquitecture

The application will be separated from the data storage, and users will store routes in their own PODs.

Multimedia

The app will allow users to share photos and videos of the routes with their friends.

Notifications

The user will receive a notification when a friend shares a route with him.

Group of friends

Users can make a group to share routes with all the members simoultaneosly.

Interoperability

It will be possible to view routes loaded from a different app.

1.2. Quality Goals

Goal Description Priority

Usability

The application must be easy to use for non-technical people.

High

Efficiency

Routes will be shared instantly with other users, who will be notified at the moment.

High

Security

Only the user will be able to see the routes he stored and those that have been shared to him.

High

1.3. Stakeholders

Role/Name Description Expectations

Users

Users of Viade app

Store and share routes with their friends.

Inrupt

Solid development company

See their technology being used in a new app.

Developers

Students who develop this app

Develop a functional application that satisfies teachers and Inrupt expectations.

Teachers of ASW subject

Teachers who will evaluate our work

Prepare us to work with different technologies and learn Software Architecture.

2. Architecture Constraints

In the next paragraphs, we set forth the constraints in a tabular format. By reading the table, you will be able to see the constraint itself, a brief explanation describing the main details and an alphanumeric identifier describing the constraint type.

At the end of this section, there is a table legend describing the different types of the constraints that we must deal with.

ID Constraint Explanation

TC01

SOLID Specifications

Creating a descentralized route management system (by using PODs) is a lead point in our Viade application taking into account SOLID specifications.

TC02

REACT Framework

This JavaScript Library is a highlighted issue in our project given the fact that GUI has a remarkable weight our for final product.

TC03

Viade Spec

This specification allows us to have interoperability between different applications

PC01

ARC42 Template

Documentation must be completed using templates in the bosom of Arc42 architecture, with Asciidoc format.

OC01

Time

Viade application will be on deck by May.

Table Legend

Element Meaning

TCXX

Technical Constraint with number XX.

OCXX

Organizational Constraint with number XX.

PCXX

Political Constraint and Convention with number XX.

3. System Scope and Context

The system must be a web application based on the new technology called SOLID. This must be a system that allows you to upload and share routes with friends.

The main advantage of this system is to avoid storing personal information in a external server. The user is the owner of their information and decides with whom to share it. It allows us to have a clear separation between the data and the application because the information is stored in a POD, which is unique for each user, and allows to store their information inside it. This provides us privacy, security and guarantees.

The following information must be allowed to be stored:

  • Routes (ttl)

  • Milestones (ttl)

  • Comments

  • Images

  • Videos

  • Plain text

The information exchange will be done by typing in the POD of the user logged in. If you want to share some information, the other user will be given permission to read only the recurring information.

3.1. Business Context

The different users in the software product we are dealing with are the following:

  • Anonymous user

  • Logged user

  • Friend user

In addition, we have the following services involved in the system:

  • POD

  • POD Server: Composite of PODs

  • Google Maps

Business context diagram
Communication Partner Input Output

Anonymous User

Text

Access to POD

Logged User

Route

Route, Milestones, Comments, Media

POD

Data models, images, videos, text

RDF

POD Server

Text, SPARQL

Text, RDF

Google Maps

GeoJSON

Javascript

3.2. Technical Context

The implementation of the system should be done using the React framework that provides the developer the facility to design a usable web page for the user. This will allow to create a path storing milestones, images and videos.

The processing of the files must be done using RDF, a system that SOLID is compatible with. The information will be treated and processed in the client and will be sent to the server where it will be stored. If any information is received, this action will be carried out in the opposite direction.

Solid’s POD server will allow us to store the information in our POD, and access the information in the PODs where the user has permissions.

For the representation of the routes, Google Maps API will be used. It corresponds to the most advanced and used map-related service.

On the other hand, all communication in the application should be through HTTPS using TLS. It is necessary that all TLS requirements that this implies are met, as well as having a valid certificate.

Technical interfaces Implied entities

Viade

Anonymous User, Logged User

POD

Logged user, Friends user

POD Server

POD, Logged user, Friends user

Google Maps

Logged user, Friend user

HTTPS

Anonymous User, Logged user, Friend user, POD Server

4. Solution Strategy

In this section, we present the decisions in a tabular format. By reading the table, you will be able to see the strategy itself, a brief explanation and an alphanumeric identifier describing the decision type.

At the end of this section, there is a table legend describing the different types of the decisions/strategies.

ID Decision Explanation

TD01

SOLID Specifications

Decentralization as well as Security will be fulfilled by using SOLID and SOLID PODs, letting users store routes in their owned PODs

TD02

REACT Framework

This JavaScript Library is a breaking point for Maintainable and Usability in Software Designing and Software Quality by 'puting together' simple modular components. It will also help with the approach of making a simple-to-use user interface

TD03

RDF

The Resource Description Framework standard model will be use to interchange data.

AD01

Multitier architecture

A n-tier architecture must be use in order to ensure scalability, maintainability, security, and reusability, among others by dividing presentation, logical domain and data storage.

OD01

Login Process

Login task will be 'delegated' to a third party (SOLID login/registration process) to ensure and strengthen Security requirements in our application.

OD02

Agile methodology

Our self-organizing and cross-functional team will follow an agile methodology, with week-long meetings and continual improvement that will lead to a complete final product.

OD03

Version Control

GitHub Pages has a place in our organizational decisions, its version control functionality will smooth our incremental working process worries.

OD04

Communication

According to our methodology type, communication will take place diary, expressing our problems by using 'Issues' along with our weekly team meetings

Table Legend

Element Meaning

TDXX

Technological Decision with number XX.

ODXX

Organizational Decision with number XX.

ADXX

Architectural Decision with number XX.

5. Building Block View

This section will show the static decomposition of the system into building blocks as well as their dependencies. We will zoom into black boxes of the different levels to show their components.

For reference, we are going to use the scope and context diagram that has been described in the third section of the documentation.

Motivation

The motivation of this diagram is to have a general vision of all different modules of the application.

5.1. Level 1

5.1.1. White Box Viade

At a first glance, we can identify the main modules that make up the application. We have the Viade Client modules developed in this project and SolidServer with whom it interacts.

Viade First Level
Contained Building Blocks
Name Responsibility

Viade Client

 It allows users to share routes and multimedia.

Solid Server

 It provides the PODs which store the information.

Important Interfaces

Client-Server high level communication (HTTP).

5.2. Level 2

5.2.1. White Box Viade Client

If we break down ViadeClient, we get three modules.They make use of an n-layer based architecture, namely three.

Viade Client: Second Level
Contained Building Blocks
Name Responsibility

Route Module

 It manages the routes and multimedia that users can share.

Data Service Module

 It links Front-End layer with SolidAdapter. Includes business logic and data models.

Solid Adapter Module

Link between Viade and Solid Server.

5.2.2. White Box Solid Server

External module to the project. For more indepth information relative to this blocks, click here.

Solid Server: Second Level
Contained Building Blocks
  • Authentication

  • Authorization

  • HTTP

  • LDP

  • Storage

5.3. Level 3

5.3.1. White Box Route Module

In this module you will find all the components that are related to the UI layer.

Route Module: Third Level
Contained Building Blocks
Name Responsibility

Login

 It allows to log in to a Solid Server provider.

Add route

Create new routes.

My Routes

 List routes were created by logged user.

List friends

List your friends

Register

It allows to sign up to a Solid Server provider.

Add Milestone

Create a new point.

Shared Routes

Share created route.

Inboxes

Inbox with received notifications.

5.3.2. White Box Data Service Module

The decomposition of DataService is complex. On the one hand, we have the services in relation to Solid User, Friend Service and NotificationService. On the other hand, we have the services for route management.

Data Service Module: Third Level
Contained Building Blocks
Name Responsibility

Friend Service

 User friends are managed.

Route Service

 It manages all actions relative to routes.

Milestone Service

 It manages all actions relative to milestones.

Notification Service

When a user shares a route, it allows to publish and suscribe a notification.

Comment Service

Allows publish and get messages.

Media Service

It manages the processing of media.

5.3.3. White Box Solid Adapter Module

Finally, the lowest level module is SolidAdapter. It provides us with the logic for the necessary interaction with RDF. It looks similar to an ORM (Object Relational Object).

Solid Adapter Module: Third Level
Contained Building Blocks
Name Responsibility

Solid Adapter

 Link between DataModel and Solid Helper. First layer with fundamental functions.

Solid Helper

 It distributes work among low-level modules.

LdFlex

 Low-level functions that manage SPARQL query and create Turtle files.

Notification

Low-level functions that create and receive notifications.

Storage

Low-level functions that allow to manage Solid’s POD.

Permission

Low-level functions which allows to control the ACL.

6. Runtime View

Sequence diagram

7. Deployment View

Deployment diagram

8. Cross-cutting Concepts

This section describes overall, principal regulations and solution ideas that are relevant in multiple parts (= cross-cutting) of your system. Such concepts are often related to multiple building blocks. They can include many different topics, such as:

  • Domain Model

  • Architecture patterns and design patterns

  • Rules for using specific technology

  • Principal, often technical decisions of overall decisions

  • Implementation rules

  • Domain concepts

  • User Experience concepts (UX)

  • Safety and security concepts

  • "Under-the-hood"

  • Development concepts

  • Operational concepts

The following image shows most of the concepts to be treated, as well as the elements that form each of these.

Possible topics for crosscutting concepts

The following points will provide an overview of each concept mentioned.

8.1. Domain Model

Below is the domain model of the route management application.

Domain Model

8.2. Architecture Patterns and Design Patterns

Architecture Patterns

Throughout the development of this project, we will build on the architectural pattern based on Layered Arquitecture:

  • Divides an interactive application in n layers. In our case, we have a very similar pattern to MVC. We have 3 layers:

    • SolidAdapter: it contains the core functionality related about persistency in Solid’s POD.

    • DataService/Model: it contains the core functionality and data view. This layer includes the data services that allow us to decouple Solid context and our app model. It brings us efficient code reuse and maintainability. This is done to separate internal representations of information from the ways information is presented to, and accepted from, the user.

    • RouteModule/Front-End: it displays the information to the Front-end layer controller.

Design Patterns

As for design patterns, patterns such as Observer are likely to be used: * It is mainly used to implement distributed event handling systems, in "event driven" software. In those systems, the subject is usually called a "stream of events" or "stream source of events", while the observers are called "sink of events".

More patterns will be used such as the Factories: * It is a creational pattern that uses factory methods to deal with the problem of creating objects without having to specify the exact class of the object that will be created.

8.3. Rules for Using Specific Technology

For the use of the application, only a series of steps will be necessary:

  • Open browser

  • Enter the URL corresponding to the application

  • In order to access more features of the application a registration will be necessary. This step can be skipped if you are already registered in the route management application.

  • Log in to your Solid Server Account

  • From here you can already do private actions. Now you have extra functionalities such as being able to list friends, create your own routes and publish them. You will also have configuration options like editing the profile, etc.

8.4. Principal, Often Technical Decisions of Overall Decisions

The team of developers reserves the right to be able to modify the application at any time, always to try to fix or improve existing aspects or to add any other that is considered convenient. Therefore we do not take care of any problem caused by such change.

8.5. Implementation rules

As for the implementation, we will always try to make the decision that assumes that the code is less coupled, dividing the code by layers. In this way it will be much easier to modify any type of change and in turn fix any existing fault. Any type of pattern that assumes a good balance between the difficulty of understanding and modifying the code and the increase in performance that this entails will be used. Duplication of the code will be avoided.

8.6. User Experience concepts (UX)

We will try to make the user have a good experience with the application, providing a friendly interface that will consist of fundamental things such as:

  • A registration / login

  • Search and filter routes, being able to access them for a more detailed description.

  • Possibility that the user can create their routes.

  • Configuration of the user profile.

8.7. Safety and security concepts

We will not be as dedicated to security as to other aspects, but if we focus on data privacy, this application will be safe, since based on solid, you will get all the route data that the customer will be providing throughout your stay in the application they will be stored in your terminal and not in a centralized data system as other important companies like Facebook and Instagram do. To this we add the "https" protocols that increase security in the browser.

8.8. Development concepts

Within the development concepts, the concept of "Build, Test, Deploy" should be highlighted. This concept is what we will rely on to fulfill a good design. The design process looks more or less like this:

  • Generating a concept

  • Refining ideas through visual exploration

  • Preparation of approximate designs that detail the design directions

  • Establish preliminary specifications for typography and graphic elements such as photography, illustration, pictures or graphics, icons or symbols

  • Presentation of short designs and general designs for customer consideration

  • Refining design and complete designs, if necessary

  • Obtain customer approval of designs and text before the next phase

There are other concepts such as code generation, migration, configurability that we will not enter but that we will take into account when making our application.

8.9. Operational concepts

There are numerous operational concepts among which the following stand out:

  • Disaster-Recovering: independent infrastructure of advanced technology superior to Backup that focuses on business continuity and is the recommended solution for Critical Mission roles. It protects and restores not only 100% of the Client’s data, but also restores the operation of an entire organization in a matter of minutes regardless of the size of the data.

  • Clustering: Group potential customers in similar characteristics according to their visits and behavior on a website.

  • Monitoring: It is based on the continuous supervision of the application to detect possible errors early and that these can be solved in the shortest possible time.

It should be noted that we will not use the disaster-recovering option due to the lack of resources we currently have at our disposal. Also we will use another technique called backup. In this way we can restore the web application in case of an unexpected error.

9. Design Decisions

In this section we will talk about the design decisions made to implement our routes application.

  • For the project interface, we are going to use Bootstrap libraries along with Solid React components and PrimeReact.

  • Programming language: we will use JavaScript together with ReactJS libraries, all using the Node.js framework.

  • Data storage: the data storage will be done through POD’s implementations and through use of RDF/Turtle.

  • CQRS: Command Query Reponsibility Segregation is a pattern used to separate the logic between commands and queries.

    • A clear read model with a list of queries and domain objects you can use.

    • An isolation of each command inside a write model.

  • Object/Turtle: All the information used by the application will be from the data model defined in section 8.1. Domain Model. We use the SolidAdapter, which acts as a mapper between the model objects and the objects that can be stored in the Solid POD. It could be the equivalent of an ORM when working with relational databases, in this case we call it Object Linked Data Mapping. Through contexts, we use ldflex proxy to map the model object and save the data in the POD in RDF format. Then, when we download the data from the POD we obtain a js object that, when the corresponding factory processes it, becomes a model object.

  • Testing: we will use unit test to business logic (Jest) and Cucumber for aceptance tests.

10. Quality Requirements

There are numerous quality requirements but then the most essential and which we will focus on:

  • Efficiency

  • Reliability

  • Availability

  • Maintainability

  • Testability

  • Portability

  • Security

  • Modifiability

10.1. Quality Tree

Possible topics for crosscutting concepts

10.2. Quality Scenarios

Ref AQ Scenario Priority

1

Efficiency

A user can access any route in less than 10 seconds

High, Medium

2

Reliability

All those actions that you want to do on the routes (CRUD) must appear updated in the application and can be delayed at most 1 minute.

Medium, High

3

Availability

Any route stored in the database must be visible by any user who has the privilege for at least 100% of the time throughout the year.

Medium, Medium

5

Maintainability

If you have to modify, update or make any changes to the application, it must be easily added thanks to the clean and precise code structure

Medium, Medium

6

Testability

Everything that involves functionality in the application must be tested before offering the new service to customers.

Low, Medium

7

Portability

The application must be able to be used in mobile devices and others that have the ability to be used in the street.

Medium, Medium

8

Availability

In case of failure of the servers, these will be replaced by ones that work correctly within 48 hours

Medium, High

9

Security

The application must support any type of external attack that directly affects the application and the users that use it.

Low, Low

10

Modifiability

In case you want to modify some aspect of the application, it must be possible to do it without any problem.

Medium, Medium

11. Risks and Technical Debts

In this section we will find all the risks and technical debts that can arise throughout the project, from start to finish, sorted by priority.

  • Inexperience in the following technologies:

    • SOLID: we have practically no previous knowledge of this technology. Moreover, as Solid project is continuously changing and updating it makes it more difficult for us to develop our application.

    • PODs: the main risk is the implementation of the SOLID server instead of using an existing one and this entails that is functional, stable and safe.

    • Node.js: the working environment of Node.js can be troublesome because when it comes to updating libraries, the npm package manager can load libraries that do not correspond to those needed.

    • Javascript: the lack of practice we have in this language can be a problem translated in time since Javascript is a language that it is not at all easy.

    • ReactJS and React Native: the first is a library and the second is a framework that we have never used, besides they are very recent (2013 and 2015 respectively), both require native developers and are subject to the restrictions of Facebook (creator).

    • Bootstrap: although it is easy to learn, it is necessary to adapt, understand and become familiar with its structure and nomenclature.

    • Git: Except for one member of the team, the rest of us have a basic understanding of how git works, which can lead to delays or missed codes.

  • The poor maintenance or abandonment of some libraries.

  • Lack of documentation in Solid libraries.

  • Abandonment of members due to lack of motivation and time. It can cause us delays in the development of the application.

  • Lack of cohesion in the team due to lack of previous relationship.

12. Glossary

Term Definition

POD

Personal storage space that you can access from anywhere.

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.

LinkedData

Solid (derived from "social linked data") is a proposed set of conventions and tools for building decentralized social applications based on Linked Data principles.

Object-Triple

Mapper allows to convert object in RDF file.

Turtle

It allows an RDF graph to be completely written in a compact and natural text form, with abbreviations for common usage patterns and datatypes. Turtle provides levels of compatibility with the N-Triples [N-TRIPLES] format as well as the triple pattern syntax of the SPARQL.

RDF

It is a family of World Wide Web Consortium (W3C) specifications originally designed as a metadata data model. It has come to be used as a general method for conceptual description or modeling of information that is implemented in web resources, using a variety of syntax notations and data serialization formats. It is also used in knowledge management applications.

2020 - ViaDe_es5a

About arc42

Thanks to: 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.