1. Introduction and Goals
This is the project viade_en2a and it will consist of a route managing application following the SOLID specification envisioned by Tim Berners Lee.
1.1. Requirements Overview
The main requirement of the project is that the system is based on a decentralized architecture where data storage is separated from the application. Other high level requirements are the following:
-
Users can store their routes in their own PODs.
-
Users can view the stored routes on a map.
-
Users can share pictures, videos or information about a route with other friends.
-
A user should get notifications when some friend shares a route with him.
-
Users can have groups of friends with whom they may want to share a route.
-
Interoperability with other route management systems.
1.2. Quality Goals
The quality goals are the non-functional requirements, i.e the requirements that are not related to how the application functions but its properties as a whole. Some of the most important quality attributes of this application are listed below.
| Quality Goal | Scenario |
|---|---|
Interoperability |
A final user should be able to use other SOLID based route applications and use their own POD the same way it is used for this application. |
Testability |
The application is testable on all its development phases. |
Robustness |
The whole application should be prepared against errors so that the probability of a user seeing one is highly reduced. |
Mobile Friendly |
The whole application can be used and has a pleasant layout on smartphones and other mobile devices. |
Usability |
Any user should have ease when using the application. |
1.3. Stakeholders
| Role/Name | Contact | Expectations |
|---|---|---|
Tim Berners-Lee |
Carry out his idea, SOLID, with the support of software developers creating applications using this technology and the Inrupt company. |
|
ASW Subject Teachers |
--------------------------------------------- |
Quality software developed by their students. |
Inrupt |
Wants to have applications developed using its technology, SOLID, to show how it works and expand the ecosystem around it. |
|
Developers |
--------------------------------------------- |
Expand their knowledge using new technologies and develop a rich SOLID application. |
Experienced Users |
--------------------------------------------- |
Have a route managment application where the work needed to work with SOLID is minimized. |
Hikers |
--------------------------------------------- |
Plan beforehand an optimal route to go hiking. |
Athletes |
--------------------------------------------- |
Plan their training routines and measure their performance analyzing the routes created with the application. |
Travel Agency |
--------------------------------------------- |
Create routes for their pamphlets. |
Tourist |
--------------------------------------------- |
Decide where to go before traveling to their destination. |
2. Architecture Constraints
| Constraint | Motivation |
|---|---|
SOLID |
SOLID(derived from "social linked data") is a technology focused on changing the way data is managed in the web. It aims to decentralize data, giving each user ownership of their data. |
Linked Data |
|
Pod |
Pods(personal online data sotres) store a user personal data. These pods can be hosted wherever the user desires(pod providers or a personal server) The user retains complete ownership and control of data in the user’s pods. |
React |
React is a JavasCript library(by Facebook) that allows us to create interactive UIs. Key features are: Components, Virtual DOM, and JSX or Javascrip XML. |
| Constraint | Motivation |
|---|---|
Timespan |
Development time must match the course duration. |
Language |
The project will be developed in its entirety using English. |
Documentation |
The provided arc42 templates written in AsciiDoc will be used. |
3. System Scope and Context
3.1. Business Context
| Communication partner | Inputs | Outputs |
|---|---|---|
User |
Upload routes. Attaches photos, videos or information to them |
Reads routes from its own pod |
Pod |
Can store routes in a interoperable route format |
Allow viade to read the routes stored inside |
Viade |
Routes and multimedia |
Routes and push notifications |
User’s contact |
Receives push notifications when a route is shared |
3.2. Technical Context
| Object | Description |
|---|---|
User |
Users of the app. |
App |
Decentralised web application. |
Web Server |
The server that contains our web application. |
Client Browser |
It runs on the user’s local device. The user works with the app here, so that the information is always local and decentralized. |
Https |
Communication between the user and the application using the Https protocol. There are https requests and responses. |
Solid-auth-client |
A library for reading and writing to solid PODs. |
Solid Server |
Server provided by SOLID where PODs are stored. |
POD |
Storage unit unique for each user. |
Google Maps API |
An API to be able to see the routes in a map. |
4. Solution Strategy
4.1. Technology Decisions
4.1.1. Backend
-
Solid-auth-Client: users will in the end use this library developed by SOLID, which is open source, and free to use. Solves the problems of accessing the pod.
-
solid-file-client: This a library from github that allow the interchange of files with the POD. It will be used to send and recieve the jsons and multimedia content.
-
JSON-LD: We will be using this specification of JSON to manage the routes in the POD. We are familiar with json, which will help us to manage the information properly, however it is not supported yet by the POD.
-
Domain model classes: We will create domain objects classes in order to have a common specification for objects used by the different modules of the application. We do not fully take advantage of the javascript objects management but we get a more understandable code.
-
Tripledoc: We will use it in order to get the friends of the User.
4.1.2. Frontend
-
Google Maps: We will need a map to show the users the route, we are selecting Google maps because os its simplicity and variaty of entry formats. However, we need an API key.
-
react-bootstrap: we will use this templates for making the design more simple and clean. They are very handy although they can be a bit restrictive in some cases.
-
Gpx: we will allow user to import routes in this format, since it is a standard. This will make the application compatible with a lot of files generated by other applications. There are no parsers that really adapt to what we want (we store jsonld) so we will have to implement ours.
4.1.3. Development Tools
-
Visual Studio Code: It is familiar to us and it has an extense amount of helpful plugins, among them we can point out asciidoctor.
-
As an starting point for the implementation, we will be using this library: https://github.com/inrupt/generator-solid-react. We believe that it would be better a better approach for the developing process not to create the project from scratch. It provides many functionality, but it is quite complex and we will need time to fully understand it.
4.2. Organizational Decisions
We will try to follow an agile methodology, similar to Scrum, where we will develop user stories and assign them among us.
For such a purpose we will be using the "project" option in the github. We are now used to develop with a Kanban, due to other subjects in the degree. Therefore, we are implementing one.
5. Building Block View
5.1. Overall System Diagram
This diagrams stands as the whole structure of our system.
5.2. Whitebox Overall (Level 1)
Motivation
The general structure of the system is an application, where users can see routes that are stored in their PODs, or in their friends PODs. Since the POD structure is already implemented we consider it as a neighbor system in this diagram.
Contained Building Blocks
| Name | Responsibility |
|---|---|
Viade |
The application that the user can see |
POD |
The infrastructure for data that the user needs for using the application |
5.3. Level 2
Motivation
This level provides an overview of the types of code in the project.
Contained Building Blocks
| Name | Responsibility |
|---|---|
App |
Code oriented to solve the functionality of the viade project |
Tests |
Code oriented to test the code un module App |
Modules |
Stands for the npm modules installed in the project and our dependencies to them. |
5.4. Level 3
5.4.1. App
Motivation
During the design of the functionality implementation we were in need of structuring the code. In the degree we became used to use the layer architectural pattern, which does not really fit with the constraint of using REACT. Even though, we structured it in a similar way to the one in the pattern.
Contained Building Blocks
| Name | Responsibility |
|---|---|
Internationalization |
This stands for the cross cutting code that leads to an easy translation process of the app |
Domain classes |
Here we have some Entities commonly used in the management of Routes, for instance a TrackPoint |
Services |
Here we have complex functionality that does not really fit into a component |
Components |
Based on the REACT framework, here we have presentation layer, and some logic |
5.4.2. Tests
Motivation
The code needs to be tested, in multiple ways if possible, so we need several test frameworks.
Contained Building Blocks
| Name | Responsibility |
|---|---|
Jest |
Test for functionality of the app |
Cucumber |
Test for functionality of the app |
5.5. Level 4
5.5.1. Services
Motivation
There is some complex functionality and algorithms that may be need to be changed in the future, or even during the development sprints, such as the translations to the data in the pod. In this particular case, we depend on something that is not really fixed, which is the standard in viadeSpec.
In the end, we believe that this functionality should be separated from the rest, in order to improve extensibility and maintainability.
Contained Building Blocks
| Name | Responsibility |
|---|---|
GPX Parser |
Translates a gpx structure to domain classes objects that we can handle. |
JSON-LD Translator |
Translates domain objects to jsonld format and viceversa. |
5.5.2. Domain Classes
Motivation
Some entities are needed during the develpment of the project. Routes, comments, images, videos… To manage them properly we have created classes that model these entities
Contained Building Blocks
| Name | Responsibility |
|---|---|
Route |
Models a route, not only the geolocalization coodinates, but also, its comments and resources |
TrackPoint |
Models a combination of coordinates, latitude, longitude… |
Comment |
Models a user comment |
Resource |
Models an image or a video |
5.5.3. Components
Motivation
By means of React we have created several components to cover the expected functionality of the app.
Contained Building Blocks
| Name | Responsibility |
|---|---|
Login |
Allows the user to login in the app, by means of a login to their POD |
Register |
Allows new Users to register and get a POD |
Welcome |
This is the first component that can be seen when logged into the app |
NavBar |
Allows the navigation across the different components of the app |
Notifications |
Handles the notification events |
ManageFriends |
Handles friends, and allows to see information related to them |
Map |
Displays the route and information about it to the User |
RouteList |
Displays all the routes of the User |
FriendRoutes |
Displays the routes of a User’s friend |
6. Runtime View
6.1. Login
-
The user selects its pod provider
-
The user types its personal id and password
-
The user clicks the log in button, if success, the application will redirect to the home view, otherwise, the current view will show an error
6.2. View routes
-
The user clicks on the "view routes" button of the nav bar
-
Then, the user clicks on the desired route name
-
Finally, the application shows the route on a map with all the needed information.
6.3. Create a new routes
-
The user clicks on the "Create A Route" button on the navigation bar.
-
The user writes the name and description of the route and creates the points which compose the route using the map at the right, clicking once creates a new point, clicking twice on the same point finishes the route (creating a loop also finishes the route).
-
To finally create the route the user clicks on the "Create Route" button.
6.4. Importing a routes
-
The user clicks the "import route" button
-
The user drags a .gpx file to the view. The routes are now displayed on the map
-
The user clicks the "import" button
6.5. Sharing a route with friends
-
The user clicks on the "view routes" button of the navigation bar.
-
The user clicks on the desired route name to be shared.
-
Then the user clicks the "Share Route" button.
-
Finally he writes the WebID of the user or group with which he wants to share the route and clicks the "Share" button.
6.6. View shared routes
-
The user clicks in the "manage friends" button in the nav bar
-
The user clicks on the friend that shared the route
-
The user clicks on the route that wants to see.
7. Deployment View
7.1. Infrastructure Level 1
The user needs his/her device of choice, which must be connected to the Internet; a web browser is required for the user to be able to access the application. Regarding the device, our application can be used with either a computer or a mobile device; however, it’s not optimized for the latter so the computer is the preferred option. In the case of the browser, any modern web browser should work fine, although Chrome or Firefox are recommended as they’re the ones we have been using during the development. Our application, Viade, is deployed using GitHub Pages, hosted by GitHub. A Solid POD is required for using the application. It can be provided by any POD provider, either Inrupt or Solid Community. This POD will be in a server, which can be anywhere in the world.
- Motivation
-
The motivation behind this deployment structure is that the user can interact with the Solid application to manage his/her routes, which will translate in having to access the user’s POD, where the routes will be stored.
- Quality and/or Performance Features
-
As with any Web application, the performance will be affected by the quality of the network connection and the servers on which the application relies. It’s not possible for us to control that. However, it’s worth noting that performance can also be drained by poorly written code; in our application, we strove to make our code with as much quality as possible, so that this would not represent a problem to the final user.
- Mapping of Building Blocks to Infrastructure
-
As we mentioned, the main components in the deployment of the application are:
-
the user’s device (such as his/her PC)
-
the browser (in the user’s device)
-
the web server in which the application is run (whose execution environment is GitHub Pages)
-
the application itself
-
the user’s POD (provided by a POD provider)
-
the POD server
-
8. Cross-cutting Concepts
8.1. Domain model
A route must contain a name, optionally it can have a description. Its composed by at least one waypoint and may or not have a list of comments and media.
The Waypoint must have latitude and longitude. They can have as optional properties a name, altitude and a physical address.
A userComment must contain the text of the comment, the time it was published and the author, being the last one a IRI to a pod profile shape.
And finally, an Image or a Video must have an IRI to te resource, another IRI to the pod profile of the author and the time it was published
8.2. User Experience concepts (UX)
User Experience is one of the main goals of our application, as apps with bad UX fail often. Therefore, we should make a great effort to build Viade as an intuitive app that facilitates its use to all types of users and proficiency levels.
Performance is too a key factor in User Experience. As Viade will have to show a map most of the time we should strive to achieve the quickest loading times possible.
8.3. Safety and security
The application must use secure communication channels. This is achieved by using the protocols HTTPS and WebID-TLS. With them we ensure te authenticity and integrity of the data sended and received from the pods.
It is also important that the application validates all input data from the users. All the data must be consistent and saved in the persistent storage following the standard RDF under a valid schema.
8.4. Testability
With great tests comes great software.
Tests to consider implementing:
-
Acceptance tests
-
Browser test
-
Load/Stress tests
8.5. Performance
Both performance and efficiency(the degree with which software fulfils its purpose without waste of resources) are essential attributes for any piece of software, especially when the user has a choice regarding which app to use.
As mentioned in UX, how an app performs can determine whether it will succeed or not. In particular, we will have to guarantee the functionality of the app in low spec devices if we want to extend the app towards phones in the future.
Accomplishing this should be done following good architectural/design practices.
8.6. Architecture and design patterns
Viade is a React based app, therefore it follows the Model View Controller(MVC) architecture.
Persistence in Viade will be achieved following the SOLID specification.
General note: our aim is to achieve a system that is maintainable, reliable, scalable and performant. We will work towards these goals using different design patterns to the best of our ability.
8.7. Internacionalization
We believe that support fo multiple languages is an important feature that our sofware should fulfill. Therefore, we try from the beginning to make it internationalizable. It must be easy to add new languages.
Localization should also be considered, showing the formats of dates, units and so on of the corresponding region.
9. Design Decisions
9.1. Framework
We decided to use React JS in the first place in order to develop a nice web application to create, manage and share routes with friends. After debating about using React JS or React Native, we prioritized developing a web application whith full functionality over having two incomplete applications. Also, as the application’s UI we are developing is perfectly scalable, using it with an smartphone is very convenient.
9.2. Inrupt-React Solid Generator
This generator is an open source project used to create a basic Solid application using React JS. By using it as an starting point for our project we could speed up the implementation process a lot. As it is fully tested it also follows the TDD approach we are trying to achieve.
On the other hand, its main disadvantage is that it makes us stick to React JS. This could be a problem if we decided to change the framework, as the migration would be harder. However, as React was stated as a constraint for this project, we considered that in order to develop a high-end product in little time it was something we had to deal with.
9.3. APIs
-
Google Maps: As stated in section 4, we decided to use the Google Maps API to provide a view of the routes to the user. Having considered other alternatives such as OpenLayers or Leaflet, we believe that Google Maps can be the right option for us because we already have experience working with it. Although Google is a company that might not represent the SOLID way of thinking, using their API does not go against any constraint and it provides a very confortable user experience.
9.4. Libraries
-
Solid-auth-client: Developed by SOLID, as it is explained in section 4, this library will be used to manage all the registration and log in processes. This one is really handy as it is already integrated in the Inrupt-React Solid Generator.
File management libraries:
-
Solid-file-client: Its objective is already explained in section 4. We will use it to manage multimedia files such as the images or videos related to a route.
-
Tripledoc: We chose this library to manage links between files in the POD. It is also used to query data such as the name of a person. The main advantage of this library is its simplicity. Its only counterpart is the need to handle profile documents, which are intermediate objects obtained querying with a Web ID.
-
LDFlex: A very powerful library which, as Tripledoc, we will use to query Linked Data. Another alternative to this one would be RDFLib, but we rejected it due to its complexity. The documentation for LDFlex is really poor, but the library is really simple to use and very handy to manipulate friends from the POD.
9.5. Route format
To structure routes data we have created a format using a subset of the existing Trip scheme from schema.org, some properties from the GeoCoordinates scheme, and the ItemList, ImageObject and VideoObject schemas.
Routes will have a list of GeoCoordinates to make up the their itinerary. Each coordinate will have as well another list of both images and videos shared by the user for each waypoint in the route. A route will also have a list of user comments.
This format, updated with proposals from ViadeSpec, will make us able to achieve interoperability between our application and the others, so that users can view and share routes with each other no matter how they were created.
Finally, the language chosen to represent these routes in our application will be JSON-LD. The idea is that our application supports routes stored in GPX or Turtle, but internally they will be converted to JSON objects.
One the one hand, a JSON-LD is just a JSON with a "@context" property, so, as a team, we are familiar with ths format. Futhermore, javascript has a built-in object called JSON, which is really useful to parse route files.
On the other hand, JSON-LDs are not yet supported by the POD’s UI, so as a final user we cannot navigate the data graph with the POD UI. However, this is just a temporal inconvenience, as in the Solid specification it is stated that it must support JSON-LD, so eventually the POD will be able to manage it.
10. Quality Requirements
In this section, we deal with all the quality requirements of the project. They are first represented using a tree structure, and further explained in section 10.2.
10.1. Quality Tree
10.2. Quality Scenarios
Now, some scenarios (stimulus and response) will be described for the previous Quality Requirements described.
| Quality Requirement | Source | Stimulus | Artifact | Environment | Response | Response Measure | Priority |
|---|---|---|---|---|---|---|---|
Interoperability |
End user |
POD login used on another application |
SOLID POD |
Normal operation |
The application logs the user and interprets the information on the assumption that the POD information is stored using the viadeSpec specification |
<1sec |
Medium |
Efficiency |
End user |
Application usage on a low specification mobile device |
Whole System |
Normal operation |
The application responds without problem and fast |
<5sec |
High |
Privacy |
End user |
POD login |
Login System |
Normal operation |
User password is encrypted and then sent |
<1sec |
High |
Maintainability |
Developing and Production phases |
Bug report |
Whole System |
Unusual |
Source code is modified easily |
<1sec |
Medium |
Usability |
End user |
Invalid data on the route creation form |
Route management |
Normal operation |
Application informs the user with the errors on the input data |
<2sec |
Medium |
Efficiency |
Map rendering |
Visualization of the map with the route on a low end device |
Route management |
Normal operation |
The visual map renders fast |
<3sec |
High |
Availability |
POD Connection |
Application connects to a faulty POD |
Login System/Data access Subsystem |
Unusual |
Application informs the user that the connection could not be established and follows its normal operation without crashing |
<2sec |
Medium |
11. Risks and Technical Debts
We have identified the risk or technical debts we might encounter during the project. They are ordered by priority from higher risk to lower.
| Risk | Explanation | Solution |
|---|---|---|
Lack of knowledge of SOLID |
It is a new concept for us and since it is still greenfield, we can find few examples, if any, of similar projects to ours. |
We must work hard, researching and asking other people that have worked with solid in the past. Attending to the SOLID conference at the University will be of great help. |
Lack of knowledge of React |
Although we have some knowledge of JavaScript (very basic), we are new to React. |
It is the same solution as the previous one. We must invest a lot of time in researching and working with it so that we feel more confortable when starting to develop the code. |
Time |
We are limited by the deadlines of the course. |
The only solution is to organize ourselves and try not to leave tasks for the last moment. |
Use of GitHub |
Although we all have used GitHub in previous projects, we have to improve our skills and learn new features such as issues, pull requests, etc. In addition, conflicts could arise with the merges. |
We must be consistent in the way we use the tool in order to avoid conflicts. We should follow good practices regarding branches, merges, etc. We also should keep everything properly organized. |
Team members |
There is always some difficulty while working with other people, as everyone does things their own way. |
We need good comunication and understanding. Well defined separation of tasks could also help. |
| Technical Debt | Explanation |
|---|---|
Can only see shared routes from someone added as friend |
At this very momment a user B who receives a route from a share action from user A, can only see the route if adds the route A first as friend. |
We are not using Solid Addresses Books |
Currently we are handling the groups in our own way, because couldn’t find enough documentation about that. |
Ttl parser ignores comment |
We didn’t find a group that was implementing the comments in TTL, so we are ignoring them when parsing to JSON-LD. |
Corrupted Routes |
Given the case that the route file gets erased, corrupted and so on, then in the route list and in the friend routes views will appear an option for such a route telling that you cannot click, intead of showing nothing. |
12. Glossary
| Term | Definition |
|---|---|
SOLID |
Technology focused on decentralizing data and giving each user ownership of it. |
Solid Server |
Server provided by SOLID where PODs are stored. |
POD |
Storage unit unique for each user. |
Decentralized system |
The control does not belong to a single entity, but to the end users. |
Https |
Communication between the user and the application using the Https protocol. |
GPX |
An XML schema used to describe GPS data and to be common between software applications. |
Waypoint |
Intermediate point on a route. |
Trackpoint |
Points that compose a track and define a path. |
JSON-LD |
A JSON file format that contains linked data. |
Turtle or ttl |
A syntax and file format aimed to represent RDF. |
RDF |
A family of specifications used for conceptual description or modeling of information used in web resources. |
Agile methodology |
It is a people-focused and result-focused methodology that adapts to changes and short delivery times. It is very flexible. |
Aceptance tests |
Tests conducted to see if the specifications and requirements are met. |
Browser tests |
Tests conducted to assure quality in web applications. They are made to ensure they work among different browsers. |
Load tests |
A type of performance test that simulates the different loads of users that the application can have. |
Stress tests |
Tests that determine the stability and robustness of the system. |
TDD |
Acronym for Test Driven Development. |
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.