1. Introduction and Goals
The main purpose of this project is to create a decentralized chat, helping people communicate while preserving their privacy.
1.1. Requirements Overview
The main purpose of this app is to let people communicate with each other while storing their own data, letting them decide who shall view their information rather than storing it in a traditional centralized server, where you are not completely sure who has access to it.
App requirements can be found here.
These requirements revolve around a decentralized app, following the fundamentals of SOLID.
1.2. Quality Goals
Quality |
Motivation |
Q1. Usability |
The app has to be easy to use for non-technical people. |
Q2. Responsiveness |
The app has to be an instant messaging app, so it can be used near real-time. |
Q3. Privacy |
As this is based on SOLID, decentralized means private. |
Q4. Security |
The chat has to be secure so the users know who are they talking to and who has access to the chat. |
1.3. Stakeholders
Role/Name |
Expectations |
ST1. Developers |
A good working project so their reputation and skills (also their mark) improve. |
ST2. Software Architecture Professors |
A good workflow and functional project so they can see we have learned the fundamentals of software architecture. |
ST3. Inrupt |
See their SOLID project implemented in a concrete app so they can start developing more and more SOLID apps. |
ST4. Users |
An app you can use if you feel your privacy is being invaded using other similar apps. |
2. Architecture Constraints
2.1. Technical Constraints
Constraint |
Background and /or motivation |
|
TC1 |
Documentation |
Ascii language must be used, following the arc42 templates. |
TC2 |
Browser |
This web based application must work as planned regardless the browser being used (Chrome, Opera, Safari…). |
TC3 |
Deployment |
Must be deployed using free tools and paying special attention to size limitations. |
TC4 |
Decentralized architecture |
The application is based on SOLID, a project for the decentralization of applications, so the application will have a decentralized architecture. |
TC5 |
Storage |
As TC4 explains, databases will not be used. Rather so, data will be stored in private folders. |
TC6 |
Testing |
The application must be tested using any available technology for the language that are used. |
TC7 |
Open Source |
The application must have an open source MIT license. |
2.2. Organizational Constraints
Constraint |
Background |
|
OC1 |
Time |
The project will be carried out during the Software Architecture course, lasting a total of 4 months. |
OC2 |
Team |
Team members must try to organize their schedule to be able to carry out this project as well as meetings. |
OC3 |
Economic resources |
This project lacks any kind of economic support, so free development tools have to be used. |
2.3. Conventions
Conventions |
Background |
|
C1 |
Architecture documentation |
Structure based on the english arc42-Template using adoc. |
C2 |
Language |
English. The project’s target is an international audience, so English should be used throughout the whole project. |
3. System Scope and Context
Decentralization has nowadays many limitations, although it provides more privacy and security while treating personal data.
These limitations are narrowed down to the PODs own limitations, as communication relies on their use.
Interaction only needs three main parts: application, user and POD. The application manages the storage of information in the PODs while users exchange that same info in a private way, that is deciding who should be able to view that stored data.
3.1. Business Context
Participant |
Action |
P1. DeChat |
Decentralized web based application that connects both PODs and makes the interactions. |
P2. User 1 |
Sends message to User 2 through the app. |
P3. SOLID Pod User 1 |
Stores the message sent, so only User 1 can read it. |
P4. User 2 |
Reads the message from the app. |
P5. Solid Pod User 2 |
Stores the message received, so he can read it through the whole conversation. |
3.2. Technical Context
DeChat is a web based application which relies on the foundation of decentralization. For this to be reached, all data is stored in the users' PODs.
Users will send messages through the chat using POD URLs, meaning it must be connected to the internet.
Object |
Description |
O1. User |
Represents the users of the chat. |
O2. DeChat |
Decentralized and web based application. |
O3. POD |
Individual storage unit for one user. |
O4. POD Server |
Server provided by SOLID in which PODs are stored. |
O5. SOLID |
New web ecosystem. |
4. Solution Strategy
Building the application using Angular is the optimal approach because one of the main quality goals is to learn about it, and almost all of the public resources for Solid apps development are implemented in this language.
The Solid Community provides a simple "Solid Authentification Client" implemented in Angular 6. This project-example will be used as a starting point in which we will include our chat, as it provides all the configurations and resources for working with Solid and Angular.
This project will be developed using Webstorm IDE by Jetbrains. Webstorm is a light-weight and powerful JavaScript IDE that can easily handle complex server and client side development with Node.js. The latest version includes some major improvements regarding Angular and Node.js support, as well as autoimports while using JavaScript.
App display will be carried out using GitHub Pages, as it is provided by GitHub it will be easier to use and will require less technical experience with other tools such as Docker and Heroku.
For new HTML views Bootstrap will be included as it provides a full CSS library, with responsive grid system, extensive prebuilt components, and powerful plugins built on jQuery.
Testing will be implemented using both Cucumber and Jest. Cucumber is a software tool used by computer programmers for running acceptance tests written in a BDD (Behaviour Driven Development) style. Its use is mandatory as it is a basic requirement from the project. As for Test Driven Development (TDD), Jest will be used as it is considered one of the best and most delightful JavaScript testing framework and our team has more experience with this tool.
5. Building Block View
5.1. Whitebox Overall System
- Level 1 - Context Diagram
-
Main schema of the architecture.
Name | Responsibility |
---|---|
User |
Person who is using the app. |
DeChat |
Decentraliced web application. |
SOLID |
Solid PODs provider. Stores PODs. |
POD |
Storage that contains all user’s data. |
- Level 2
-
Zoom in the main parts of the application.
Name | Responsibility |
---|---|
App |
Decentralized chat. |
Tests |
unit, acceptance and load testing. |
Libraries |
External libraries being used. |
- Level 3
-
Specific parts of the application and different types of tests.
Name | Responsibility |
---|---|
Models |
Mapping classes present in the code. |
Components |
Different components integrated in the application. |
Services |
Services being used in the app for it to work properly. |
Cucumber |
Unit testing. |
Jest |
Acceptance testing. |
Gatling |
Load testing. |
- Level 4
-
For the app to be able to send messages in a proper way, models, services and components are needed. In this app the models used where those relating to the main functionality of the app (profile, session, message, friends and SOLID provider).
The main services used are RDF for storing the messages in the POD, Authentication and AuthGuard for login and registration purposes and chat service, where all the code for interacting with the previous libraries is written.
A component for each different view of the application is needed.
6. Runtime View
When a conversation starts for the first time, a new folder with a new turtle file is created in the user’s POD.
The user sends the message through the chat, and the application stores the message in the user’s own POD writing it on the turtle file in ttl format. While writing it, the message is sent to the other user’s POD also in ttl format.
Once both PODs have the data stored, the app runs an update and takes the data present in the turtle file and prints it down on the chat view, so the receiver can read the message.
The messages are stored with all the information relevant to them: date, hour, sender, receiver, and message content.
7. Deployment
GitHub Pages is used to deploy this client side application.
It is a static site hosting service designed to host your personal, organization, or project pages directly from a GitHub repository.
Having the whole project located in the same environment (code, documentation and deployment) is a great advantage when talking about management.
8. Cross-cutting Concepts
8.1. Persistency
As SOLID is decentralized, there is not going to be a database where everyone can check messages sent and received. Instead, we’ll be creating folders for each conversation and only member of the conversation will have access to those folders, where all the relevant data is going to be stored. For this purpose we are going to use the .ttl format
8.2. User Interface
The default interface used for Solid project is written in JavaScript and AngularJS with a minimal Bootstrap template.
8.3. Transaction Processing
The transactions realized across the application are asynchronous
8.4. Session Handling
Session is handled by Solid Authentication Client, so it keeps you logged in and you can navigate through your pod, friends lists or chats.
8.5. Security
The security is provided by the Solid Authentication Client and the POD, that manages the session.
8.6. Safety
No part of the system has life endangering aspect.
8.7. Exception/Error Handling
Errors handling to inconsistent data (in regard to the data models constraint) as well as failures to validation are mapped to HTTP errors. Those errors are handled by the frontends controller code. Technical errors (hardware, database etc.) are not handled and may lead to application failure or lost data.
8.8. Testability
For the testability we used JEST modules to test the JavaScript code and Angular side.
9. Design Decisions
All the design decisions made so far are explained and detailed in section 4 - "Solution Strategy". Here are all the important choices arranged in a table:
Programming Language: JavaScript - Angular 6, TypeScript |
Base project: Solid Auth Client |
IDE: WebStorm by JetBrains |
App deploy: GitHub Pages |
CSS & HTML implementation: Bootstrap libraries |
Testing: Cucumber, Jest and Gatling |
Relating to the Chat view, it will be arranged into a separate component, with its own HTML and CSS implementations. The layout is separated in two columns. On the left, a list of the user’s friends wil be displayed, and on the right, once you choose the friend you want to talk to, the chat view will pop up.
An optimal color combination was chosen so it does not become a problem to colorblind users or those who have any kind of optical disability.
10. Quality Requirements
This section contains a quality tree with scenarios, in order to understand the central quality goals (described in section 1.2.) as well as other required quality characteristics.
10.1. Quality Tree
10.2. Quality Scenarios
Nr. | Quality | Scenario |
---|---|---|
1 |
Usability |
Each section of the technical documentation must be understood without the need to read the rest of the documentation. Any content should be found immediately. |
2 |
Responsiveness |
Tested with Google Responsiveness Test (https://search.google.com/test/mobile-friendly) |
3 |
Securability |
A third party will not be allowed to access the data transmitted between two users in a chat session. While chatting, users can get access only to their own data. |
4 |
Simplicity |
A non-technical user who has never used the application should be able to open a chat session with another user in less than 3 minutes. |
5 |
Efficiency |
When sending a message through the chat, it will be received by the recipient in a reasonable time (less than 10s). |
6 |
Modifiability |
The application should have an appropriate design so that the modifications that must be made during the project can be addressed by the team in less than a week of work.# |
7 |
Robustness |
The system is compiled and passes all the tests without errors. Code coverage is analyzed by means of Codecov (https://codecov.io/), and coverage percent should be at least 60%. |
8 |
Maintainability |
The application must be divided into different modules. All public methods in the application must be well understood. Code quality is analyzed by means of Codacy (https://www.codacy.com/) and must be at least "b" level. |
9 |
Testability |
[.SpellE]#The project must implement continuous integration testing using Travis CI. |
11. Risks and Technical Debts
In the following page we are going to identify, measure and priorize the risks and different technical debts that the project has.
The following, is the list of risks found while developing the project
-
SOLID: No previous knowledge about this technology until it was introduced to the team for this project.
-
AngularJS: Not a familiar framework for any of the team members.
-
Heroku: We are going to use this platform to host our SOLID server. We have to learn how it works and accept that the account has restrictions. The principal restrictions that we have to face with Heroku are related to the number of queries that it allows with the free account that are 75 queries per user, app, hour. Finally it was NOT used due to said limitations.
-
GitHub Pages: web hosting service that must be used for deployment. First time for all team members.
-
Typescript: As we researched, most SOLID apps are written using Typescript and we don’t know anything about it. Adapting to it will be a risk, although it can’t differ too much from Javascipt itself.
-
Cucumber: In order to do the acceptance tests team members must learn Cucumber and Gherkin language.
-
Protractor: Used to run Cucumber tests in a more visual way. Must learn the basics of this tool as well as how it works while used with Cucumber.
-
Jest: Only one team member has experience with this tool. In the project, unit testing will be carried out using Jest.
-
Git: not a lot of experience with this tool.
-
Bootstrap: none of the team members has previous experience with these libraries. It will not be such a huge risk due to the extensive guide and documentation provided online.
-
Cucumber: just one member of the team has used Cucumber as a tool for writing customer acceptance tests. It is not classified as a severe risk.
-
Jest: just one member of the team has used Jest as a tool for writing unit tests. It is not classified as a severe risk.
12. Glossary
Term |
Definition |
AngularJS |
Open source Model-View-Controller framework, developed by Google. [Official Website:](https://angular.io/) |
Cucumber |
Open-Source tool to make tests in a language that can be understood by people that aren’t familiarized with the computing technologies world. |
Decentralized Web |
Web technology where services are distributed rather than localized, where users own and control their own data |
Gherkin |
Programming language to make tests in Cucumber. It could be understood by humans and computers. |
GitHub Pages |
GitHub Pages is a static site hosting service designed to host your personal, organization, or project pages directly from a GitHub repository. [Official Website: ] (https://pages.github.com). |
IDE |
An integrated development environment (IDE) is a software application that provides comprehensive facilities to computer programmers for software development. |
Ionic |
Open source, front-end SDK for developing Hybrid Mobile Applications using web technologies such as HTML, CSS and JavaScript. [Official Website:](https://ionicframework.com/) |
JavaScript |
JavaScript often abbreviated as JS, is a high-level, interpreted programming language that conforms to the ECMAScript specification. |
Jest |
Test framework that allows between other languages JavaScript or React |
Linked Data |
Linked Data is a part of the Semantic Web in which the Data in RDF format are related through similar links to HTML hyperlinks. |
NodeJS |
Open-source, cross-platform JavaScript run-time environment that executes JavaScript code outside of a browser. [Official Website:](https://nodejs.org/) |
npm |
Package manager for the JavaScript programming language. It is the default package manager for the JavaScript runtime environment Node.js. [Official Website:](https://www.npmjs.com/) |
POD |
Derived from "Personal Online Data". It’s a simple file that contains user data. Also can be accessed by other users/apps to write or read data. |
Protractor |
Test framework for AngularJS and Angular applications that allows that your tests will run in a real browser |
RDF |
Model for encoding semantic relationships between items of data so that these relationships can be interpreted computationally. |
Solid |
Derived from "social linked data", is a proposed set of conventions and tools for building decentralized social applications based on Linked Data principles. [Official Website:](https://solid.mit.edu/) |
Stakeholder |
A stakeholder is a party that has an interest in a project and can either affect or be affected by the project. |
WebStorm |
IDE for JavaScript development. [Official Website:](https://www.jetbrains.com/webstorm/) |
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.