Note

This version of the template contains some help and explanations. It is used for familiarization with arc42 and the understanding of the concepts. For documentation of your own system you use better the plain version.

1. Introduction and Goals

The goal of this project is to create a decentralized chat app based on Solid specifications.

In this document, you can find the important requirements of our project, quality goals for the software architecture and the relevant stakeholders and their expectations.

1.1. Requirements Overview

Requirement Description

Decentralized architecture

The application will be separated from the data storage, which means all the data including messages, images will be stored in their own PODs.

Data

the data sent for the moment only includes text messages, emojis and gifs .

Chats

Users can create a new conversation and be asked to join one by their friends-

Files Sent

Users can send images, videos and files.

Security

Users don’t have to worry about their account being stolen because all of their data is encrypted.

Group chats

Users can create or asked to join a group chat by their friends.

Notifications

Whenever there’s a new invitation, the users will be notified and it’s their choice to accept it or reject it.

1.2. Quality Goals

Goal Description Importance

Usability

The main objective of our app is to be used and familiar to all sorts of people

High

Efficiency

The conversation will be in real time to ensure smooth communication

High

Security

Ensure the conversation is seen by the members included Only and the data shared is private

High

Maintainability

The app will be modularized to ensure the simplicity of testing and future case of reusability by others

High

Reliability

We’ll ensure the app is available at all time and ensure fault tolerance for a better user’s experience

High

1.3. Stakeholders

Role Description Expectations

Users

Our DeChat app users

to be able to chat with people and not to worry about data being stolen.

Inrupt

The Solid development company

To see their technology being used and enjoyed by users.

Developers

The two members team

To see their hard work has paid off by ensuring the quality of the app.

José Emilio Labra Gayo

Our teacher and Coordinator of the Software Architecture

To see his students learn something new and investigating our their own to prepare us for the future.

2. Architecture Constraints

Table 1. Technical Constraints
Constraint Explanation

Decentralized Architecture

The project architecture will be decentralized, so that user data is separated from the application that uses it. In order to this beind done, the app will be based on solid specifications which means the data will be stored in the user’s pod.

Cost

As the project is done by university students with zero dollars budget, only free software, libraries and dependencies will be employed to achieve our goals.
Table 2. Organizational Constraints
Constraint Explanation

Software Development

The project is available in this GitHub repository in order to use Multiple Integration options such as Travis and Code Coverage options and to simplify the code sharing and reviewing.

Time

There is limited time to complete the project and the documentation being 30th April 2019 the limit.
Table 3. Conventions
Constraint Explanation

Arc42

As a template for the documentation of the project, we must use Arc 42 format.

3. System Scope and Context

We thereupon proceed to list the communication partners involved as well as their interfaces. We provide two distinct contexts to describe it, one domain-specific (Business) and another technical-related.

Chats created by an user may be either individual or groupal; following diagrams describe a one-to-one situation. Keep in mind, though, that groupal communications adhere to the same structure; the only difference being the number of interlocutor’s PODs chat and message info will be sent to.

3.1. Business Context

Business Context diagram

Business Context

3.2. Technical Context

Technical Context diagram

Technical Context

4. Solution Strategy

4.1. Introduction

In this document, you will find the software decisions and solutions in order to ensure a quality app such as the technologies used and what is used for testing.

4.2. Decisions

The project is developed using the following :

Table 4. Technologies used for developing
Technology Purpose

Solid

Following the solid specs, we’ll ensure the data is stored in a private part of the user’s pod.

JavaScript

As the purpose of our app is to be used on the web, JS is the obvious and best choice for web client applications.

HTML, CSS and Bootstrap

To ensure only the best UI and UX.

Node JS

For server-side. As we will use npm to manage dependencies and it’s pretty good to create real-time apps.
Table 5. Technologies used for testing
Technology Purpose

Mocha JS

Mocha is a feature-rich JavaScript test framework running on Node.JS that are we using and in the browser

istanbul nyc

We’ll be using these frameworks to run Mocha tests and to supply the integration platforms the information needed.

cucumber-selenium

To ensure Behaviour-Driven Development, we’ll be using cucumber and Selenium which are JavaScript browser automation frameworks.

Gatling

To measure the performance of our web application.
Table 6. Continuous Integration Platforms
Technology Purpose

Travis

Our goal is to build healthier software by developing and testing. And as a CI platform, Travis supports the development process by automatically building and testing code changes, providing us immediate feedback on the success of the change made.

Coveralls

In order to ensure a better code coverage by the tests made and remove unused code.

Code Quality

We use this CI in order to be better developers and write quality code and make it understandable and and why not be reviewed and change by GitHub community
Table 7. Managing RDF Data
Dependency Purpose

n3

It is an implementation of the RDF.js low-level specification that lets us handle RDF in JavaScript easily including storing or reading information.

uniqid

We use this as it will always create unique id based on the current time, process and machine name.

winston

For logging and debugging purposes.

uri

URI.js is a scheme extendable URI parsing/validating/resolving for JS.

Q

To return promises read from the pods. A promise is an object that represents the return value or the thrown exception that the function may eventually provide.

Comunica SPARQL RDFJS Init Actor

We use for queries RDFJS queries.

4.3. Solution Aproaches

We started developing in javascript and node because we were inspired mostly by the great solid-chess application developed by Pieter Heyvaert.

5. Building Block View

This section consists of a decomposition of our system into building blocks, showcasing their inner dependencies.

5.1. Level 1

We begin the decomposition by displaying a white box description of the overall system -manifested in section III, Context Diagrams as 'DeChat' black box-.

Building Block Level 1

It can be swiftly perceived that we have chosen a Model-View-Controller pattern for overall system architecture, reasoning being: * It is a fairly suitable and easy-to-grasp architecture for web applications such as ours. * We have created a few applications before using this approach.

Table 8. Black Box descriptions
Name Responsibility

Service

Performs an operation ordered by the Controller or another Service, working with user-provided data to persist or select information through Repository. Creates, joins and opens a chat, as well as storing and loading messages, either written by the user or received at his POD’s inbox.

Repository

Either persists the data provided by a Service -inserts or updates data in current user’s private POD folder as well as interlocutors' inbox- or selects stored/received data from current user’s POD.

5.2. Level 2

5.2.1. White Box Service

Building Block Level 2 - Service

It was determined that, in order to make the main logic more sustainable as well as comfortable to work with, it would be decomposed into 5 classes -services, since we opted for MVC-, which encapsulate the main features needed for basic chat communication. Those being the following:

  • BaseService. Contains basic functionality which is commonly needed and doesn’t fall under any category.

  • CreateService. Creates chats/groups, storing in user’s POD whatever information is needed and sending invites to all participants.

  • JoinService. Processes invitations to create a replica of the chat in invited user’s POD.

  • OpenService. Loads all information about stored chats and any messages it contains-.

  • MessageService. Looks for new messages in inbox to store them if necessary, as well as stores new messages created at current session and sends them to any participants' inboxes.

  • EncryptionService. Encrypts and decrypts data with TRUBIA algorithm.

Since there were common imports to all of them, sharing constructor as well, we abstracted a Service superclass to avoid duplicating code.

5.2.2. White Box Repository

Building Block Level 3 - Repository

There are three main clases conforming persistance functionality:

  • RDFJSSourceFactory. Given an URL, provides a RDFJS Source to make queries with Engine.

  • SolidLoaderRepository. Through the source provided by the latter, it collects chat info from any accesible URL to form a domain object, which will be used by whatever Service has required it.

  • SolidUploaderRepository. Executes SPARQL updates and insertions. Capable of deleting files, also.

The objective of this block is to provide CRUD operations for all of the Services, so that any chat-related information may be recovered or persisted. It plays a rather significant role, since it is the responsible of handling POD usage in both directions.

6. Runtime View

6.1. Scenarios

6.1.1. Main Scenario : the user’s journey flow.

User journey Flowchart

user journey

User journey in details

1 → Entering the main app

2 → Click on Login

-> Login or Sign up
-> Confirm information

3 → The app loads all the data necessary including the user’s friends and invitations and messages.

4 → User wants to send or view messages

-> Already open conversation
-> Creating a new conversation
  -> group
    - user select the members he wants to add
    - click on add
    - the conversation is created and the members are notified
    - now anyone can join and exchange messages
  -> individual
    - user select the friend
    - click on it
    - the conversation is created and the friend is notified
    - now the users can exchange messages

6.1.2. Second Scenario : Login Process

Login flowchart

login flowchart

Login runtime view in details

When entering the webpage, there are two possibilities :

1 → the user’s already logged in or connected in solid.community/ for example

2 → the user’s not logged in, the user nust click on Login

-> If the user has an account
  - click on the provider and fill the login form.
-> If the user doesn't have an account
  - there is the possibility to register and create a personal POD.
  - Login using the entered informatin in the register process.

3 → the app will load automatically all the user’s data including the conversations, friends and invitations.

4 → now the user is in the main UI.

6.1.3. Third Scenario : User A Sends Message to User B

Sending messages Flowchart
messages flowchart
sending messages in details

In the case of an already open conversation, the user User A selects it and decides to send a message to his friend User B

1 → User A send the messages.

2 → The app places this conversation for User A in the first place.

3 → User B receives it and the app places the conversation in the first place with a notification.

4 → The UI view is updated for User A and User B with the message sent.

7. Deployment View

Deployment View - Service
Figure 1. Infrastructure overview

7.1. Motivation

It was established as an early constraint that SOLID was to be used as the basis for our communication app. Thus, its presence in the infrastructure as the final step for data management is not a surprising view. However, we did decide to go for a Web Application, since a) we had the most resources to take as guidance, b) it provides ease of usage for the average user and c) GitHub provides an option to serve our web app. Hence, the presence of the Web Server and Web Browser blocks in the infrastructure.

As it has been stressed previously, its web server may be found at https://arquisoft.github.io/dechat_es6a2/, thanks to GitHub Pages feature. A secondary approach is provided, given the circunstances ask for it: after having cloned the repository, the user may run the command http-server at root directory; he will be provided with some IP directions to access (it is mandatory to add "/src" to the URL).

7.2. Mapping

Previously defined building blocks are always deployed the same way: a file is generated through the processing of ChatController, an action which in cascade maps all involved classes into a main.js file, with all of the Node dependencies solved. This file is linked to the View (index.html) as an script, so that related code is executed by the browser of choice in response to user’s actions on the presentation layer.

8. Cross-cutting Concepts

This section describes overall, principal regulations and solution ideas that are relevant in multiple parts of our system.

8.1. Concepts Mind Map

concepts.png

8.2. Concepts Detailed

8.2.1. User Experience concepts (UX)

The user interface is for the moment only available in English and it’s inspired and that’s because we want to the user to feel at ease and use a familiar UI instead of complicating it.

8.2.2. Safety and security concepts

The main objective of this whole app and Solid Specs is to ensure the security of the user by choosing the person who he’d like to speak and not having to worry about his data stolen because as we know, the messages and data shared is stored in his private pod and no one will see it except him.

8.2.3. Architecture and design patterns

The application is in main.js and it is managed by the ChatController.js which uses additional libraries and services included in the lib/ folder.

8.2.4. "Under-the-hood" Concepts

  • Persistency :

the Data shared between the users is stored in each user’s personal solid pod.

  • Transaction handling :

In our app we ensure the correct use of ACID properties by sending and receiving the correcting messages without any changes in real time and concurrently.

  • Exception and error handling :

The main error not controlled by the app is having a not stable internet connection as it could damage the app’s correct functioning.

  • Reporting :

For reports, we use travis and code coverage to make sure everything is okay and also track all the changes made.

8.2.5. Development concepts

  • Build

To build the app we use Node Js webpack running the following command

npm run build:web

  • Test

It is very important to test our application in order to ensure the correct use of it and that’s why we use various frameworks including mocha and cucumber.js.

  • Deploy

We will be using Docker to deploy our app in the future.

9. Design Decisions

This section describes all the decisions made to develop our decentralized chat app.

9.1. Design Decisions Mind Map

DesDesicions.png

9.2. Design Decisions Detailed

9.2.1. Chat Storage

Firstly, a decision had to be taken about the approach to data storage; two options were available for us.

Either we stored chat data at one of the interlocutors' POD (chat creator, presumably) or we stored the data at both sides.

The former required of some permission system to allow other users to access the host’s private folder, but reduced work volume by limiting storage to one user, instead of 2+.

However, we opted for the latter, since we consider that data being in custody of all participants was both a fairer deal for the parts involved as well as preferable to data integrity and fault-tolerance. This requires some more resources to proceed with the operations, but it doesn’t affect the user experience since the visual showing is done independently.

9.2.2. Encryption

We decided to encrypt all data stored at a POD, for we learned that they might not be as secure as one would like.

Hence, we created a simple encryption system which, actually, is nothing more than the combination of two popular ones: Enigma -which nowadays does not provide much, but serves as a signature of our work- and AES, which provides true security to the system.

We thought about making the encryption process invisible to the user, by autogenerating a password and storing it at the POD. However, this does not solve much, in the end, since if an attacker gains access to the container he’d have no trouble accessing the data. Therefore, we opted for a password input by the user after logging in, which is less conspicuous, but improves its security considerably. Besides, it allows for multiple encryptions at one POD, which work independently.

Salt is added to every field encrypted, so that two identical texts -commonly, users- are not revealed. Such salt is stored along the encrypted info, as it is conventional.-

Whereas every information stored at a private folder is locked by the chosen password, a decision had to be made about the data sent by one interlocutor and received by the others at the inbox, since they would need to agree a common password to work with it. To avoid making the system harder to use -a password would have to be established for every chat-, it is handled automatically and without affecting the user, by appending the key to the message.

Obviously, this makes it decryptable, if someone really wishes to do so. Since it is a temporal operation, it is a window of insecurity within the system. However, there is no time to implement a more complex system; its purpose is that of making it unintelligible for the casual, non-desirable visitor.

It’d be fine to improve it for the far future, though.

9.2.3. Front End

To design the UI and offer the best UX possible, we are using HTML and CSS and Bootstrap in addition to jQuery.

We chose to mix a popular chat UI style -in order to make it familiar and intuitive to new users- with a retrowave feel for a more unique touch. A set of random, slightly inspirational phrases is shown while chat is loading, so that the user is somewhat entertained for the duration of the process.

9.2.4. Back End

Moving to the functionality part, we are using basically JavaScript and Node.JS to manage dependencies and libraries such as n3 and Q to work with RDF and Linked Data.

Code was organized into sets of classes such as Services and Repositories to improve its clearance of purpose and maintenance ease. Such estructure has already been detailed at previous chapters, so we shall not explain it any further.

For the testing part, we are using mocha and nyc for unit tests, and cucumber-selenium for BDD tests.

9.2.5. Persistence and Data Storage

Following Solid specifications, all the data shared between users are private and stored in their respective POD.

9.2.6. Continuous Integration

We are using Travis for running the tests and checking the correct build of our app, Coveralls for code coverage to make sure of not forgetting any part of app and Code Quality .

10. Quality Requirements

In this document, you’ll see the project’s important quality requirements.

We will start by seeing a quality tree with all these quality requirements, as well as its most significant quality scenarios.

At the end, you can see more details.

10.1. Quality Tree

quality tree

10.2. Quality Scenarios

In this section you can see a little more in depth the main quality scenarios that have already been seen before in the quality tree.

Reference AQ Scenario Priority

1

Portability

The system must be able to operate on different platforms

High

2

Performance and usability

A user will send and receive messages instantly to ensure smooth communication

High

3

Usability

Facilitate the use and understanding of the system to user

High

4

Reliability and usability

If an error occurs without too much importance the system should continue working

High

5

Performance

A user can send a message in less than 1.2 seconds

Medium

6

Modifiability

The system must be open 2 hours after having made changes in the algorithms and methods that comprise them, without impairing functionality

High

7

Scalability

The system must be designed so that, if the number of users increases in a short period of time, the availability and performance is not affected

Medium

8

Scalability

Support for at least "X" mb content

Medium

9

Availability

The system must be accessible at least 90% of the time

Medium

10

Availability

Messages sent by the user will not be lost, until he deletes them

High

11

Security

An unauthorized intrusion will be reported in less than 60 seconds

High

12

Security

The system will not allow a user to read messages from a conversation where the user is not included

High

11. Risks and Technical Debts

In this document we will be talking about risks and technical debts we faced or we might face in the future.

11.1. Problems Mind Map

quality tree

11.2. Problems Detailed

11.2.1. Solid

Solid is a whole new world for us and it took us a while to adapt its specifications and functionality to our project.

11.2.2. JavaScript and Node.JS

Although we used JavaScript many times in the past but it was very difficult adapting to this language and managing node libraries as well as what dependencies and versions to choose.

11.2.3. Libraries

There aren’t much libraries to manage Linked Data and RDF resources and SPARQL and it was difficult to find them and use them but with time we got used to it.

11.2.4. Security and Confidentiality

We had to make sure all data stored in the user’s pod are encrypted. Therefore, we had to search an original and secure way to do it.

11.2.5. BDD

We have never used Cucumber and we are new to the Behavior-Driven Development world, so it took us a few days to learn how to use it with Node and adapting it to Travis to build our app.

11.2.6. Deployment

We were originally goint to use Docker to deploy our app. Howerver,at the end, we decided to use gh-pages for simplicity.

12. Glossary

In this glossary, you will find a list of words relating to this project and SOLID.

Term Definition

Arc 42

Template divided in 12 sections for architecture communication and documentation.

Bootstrap

is the most popular CSS Framework for developing responsive and mobile-first websites.

BDD

Behaviour-Driven Development is is a software development approach. its tests are written in a shared language, which improves communication between tech and non-tech teams and stakeholders.

chai

BDD assertion library used with Mocha and other JavaScript test frameworks.

CI

Continuous Integration is the process of automating the build and testing of code every time a team member commits changes to version control

Code Coverage

It is a measurement of how many lines/blocks/arcs of your code are executed while the automated tests are running.

CSS

Cascading Style Sheets describes how HTML elements are to be displayed

cucumber

It is a tool that supports BDD. It offers a way to write tests that anybody can understand, regardless of their technical knowledge.

Decentralized Web

it refers to a series of technologies that replace or augment current communication protocols, networks, and services and distribute them in a way that is robust against single-actor control or censorship.

Docker

is a tool designed to make it easier to create, deploy, and run applications by using containers.

FOAF

Friend Of A Friend is an RDF based schema to describe persons and their social network in a semantic way (in links to put it in simple words). It could get used within many wikis for annotating user pages, or describing articles about people.

HTML

is a computer language devised to allow website creation. These websites can then be viewed by anyone else connected to the Internet.

JavaScript

is the Programming Language for the Web. it can update and change both HTML and CSS OR calculate, manipulate and validate data.

Linked Data

it is used to describe a method of exposing and connecting data on the Web from different sources. Currently, the Web uses hypertext links that allow people to move from one document to another.

Mocha

JavaScript framework to run asynchronous tests on Node.js.

n3

is a node dependency that lets us handle RDF in JavaScript easily.

Node.JS

is an open source server environment that uses JavaScript on the server.

nyc

is a JavaScript test coverage tool.

POD

Personal Online Data is where all the data is stored Photos or Videos you take, comments you write, contacts in your address book, calendar events,…​etc. You give people and your apps permission to read or change them.

POD Provider

is a Person or Company that has one or more solid pod servers and uses them to store/host data.

POD Server

Server that allows the application store POD information on it.

Profile

is all the information related to the user including the full name, phone number , personal inbox , storage,…​etc.

Q

is a node module that manipulates Promises instead of objects in JavaScript.

RDF

Resource Description Framework is a specification that defines how metadata, or descriptive information, should be formatted. This means the data can be transmitted in various syntaxes like JSON-LD (JSON with a "context")

Selenium

is a portable framework for testing web applications. It provides a playback tool for authoring functional tests without the need to learn a test scripting language.

Solid

Social Linked Data is a proposed set of conventions and tools for building decentralized Web applications based on Linked Data principles.

SparQL

is the standard query language and protocol for Linked Open Data on the web.

Stakeholder

is a person or group of people with an interest or concern in something, in this case, this project. It can be a technical or non technical user, a company, developers or even , in our case, our professor .

Travis

is a hosted, distributed continuous integration service used to build and test software projects hosted at GitHub.

User

is a person who uses/owns a Solid Pod.

WebID

is a standardized method for internet services and members to know who they are communicating with.