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

Our project is part of a university proposal with a basis in cooperation with the company Inrupt and the use of its SOLID design.

In it we will provide a response to the request for a decentralized chat using SOLID. It will consist of the principle of separating the information from the application giving the user the power to control all their data.

In this documentation we will explain all the relevant concepts of our decentralized chat, based on SOLID, following the Arc42 template.

1.1. Requirements Overview

It is a chat so its most basic requirements are to send and receive messages. But there are other requirements that we are going to explain:

1.1.1. Chat Requirements

Requirement Description

Secure

Connection protocols and personal information security

Descentraliced

The user is the real data’s owner

Fast and Agile

Real time message system

Intuitive and Comfy

Easy to learn and use, familiar to the user

1.1.2. Implementation Requirements.

Requirement Description

Testability

Error and bugs tracking, the architecture should allow easy testing

Pattern design

Facility to extend, update and fix

Fast and Agile

Easy to understand and work with it

1.2. Quality Goals

Quality Motivation

Decentralized

Top priority and objective for the chat, is required to work…​

Usable

Chats are one of most common and famous application,and they are expected to be familiar and intuitive to the user

Clean code and design

Most of our Stakeholders are developers so, it is relevant to maintain a clean product during its implementation

1.3. Stakeholders

Role/Name Contact Expectations

Teaching Staff

Teachers

Teacher and in charge of the subject, seeks development within a project and constant work.

Inrupt

SOLID Team

They establish certain bases to be met in the development and operation of the application, also act as a help factor.

Users

Potential users

Those possible users who use the application for the technologies used and their comfort.

Team

Developtment team

Develop a application that will work and achieve at least the minimum requirements planned.

Developers

External developers

We are deploying an open code product so it might be relevant to bring them some help by coding a clean application

2. Architecture Constraints

In this part we will explain the requirements that we have to keep in mind to make the right design, implementation and development choices.

2.1. Technical Constraints

Code Constraint Motive

TC01

Use of SOLID

The application must be developed following the SOLID specifications with a decentralized control of the user’s data

TC02

Independent operating system and browser

Application must run in any operating system and in the main web browsers

2.2. Organizational Constraints

Code Constraint Motive

OC01

Project developed in open source

The project, including source code and documentation, will be developed and published in open source

OC02

Use of GitHub version control platform

It’s use makes easier cooperation and communication between team members to develop the project

OC03

Limited time to develop the project

Development team must have a beta version, maximum, in May 2019

OC04

Arc42 model

Documentation must follow this template

2.3. Conventions

Code Constraint Motive

CO01

Development and documentation language

English. Application will have no language restrictions and it can be used by anyone

CO02

Documentation completed in AsciiDoc

We will use AsciiDoc and not Markdown

CO03

Coveralls

We use it to check the code coverage

3. System Scope and Context

DeChat must allow communication between two users through text messages. In addition, it may be possible in following versions create user gro ups which all participants can send and receive messages.

Security and privacy is DeChat priority. Messages will never leave user own Solid POD. Instead, recipient system will be asked to retrieve message from senders POD, and will never save messages to recipient POD. DeChat will only store where message is placed, so app knows where are messages stored when user starts application.

Lists of communication partners and their interfaces:

  • Main: login page where the user must enter his or her solid community credentials.

  • Chat room: shows the authenticated user’s friends list and the messages sent and received with the selected friend.

3.1. Business Context

There will be only one communication partner (one role): User. User will be able to send and receive messages. In the background, RDF will be used to share chat details. Data will be kept within sender’s POD and will never be stored outside it.

Communication partner Input Outputs

User

Notifications indicating user to read a message from a given source

Message storing and same notifications from Input column

3.2. Technical Context

Since DeChat is under SOLID architecture, we will be using WebID to communicate between users and add friends. SOLID also makes use of RDF, WebSockets, etc.. More info available in https://github.com/solid/solid-spec

As indicated above, the chat is composed of two main elements: login and chat room. It’s necessary to bear in mind that the application needs a web browser to be able to use it. Here is a case of use that explains how it works:

Chat components diagram

4. Solution Strategy

Due to the social content of the application and other solid apps that we’ve seen we decided that the best option is to do it in a web enviroment so it’s more user-friendly. At the moment the plan for our application structure is based on a JavaScript application with HTML components that follow solid’s style guide and pattern in the app apearence.

For the teamwork, project development and documentation we’ll be using a GitHub repository to keep things in order.

4.1. Technology Decisions

  • Solid: by subject requirements.

  • Solid-file-client: a library for creating and managing files and folders in Solid data stores.

  • Webpack: bundle JavaScript files for usage in a browser.

  • Node.js: JavaScript runtime built on Chrome’s V8 JavaScript engine.

  • Bootstrap: open source toolkit for designing web sites.

  • GitHub: also by subject requierements.

  • AsciidocFX: Asciidoc document editor to perform the documentation.

  • Mocha: Runs unit tests.

  • Cucumber: Runs automated acceptance tests written in a behavior-based development style.

  • Travis CI: It is a distributed and hosted continuous integration service that is used to create and test software projects hosted on GitHub.

4.2. Decisions on how to achieve key quality goals

4.2.1. Decentralized

In the first iteration of the project we have carried out a research task about what the SOLID project means. Once this information was understood, all team members were ready to contribute their own ideas and carry out the implementation of the application in the following iteration.

4.2.2. Usable

We have made a template of what the user interface should be to get an idea about the design of the application before we start to implement it.

The colors purple, lilac and white have been used so that the user does not forget that he is using SOLID.

Chat room sketch

4.2.3. Clean code and design

At first we focused more on chat functionality rather than trying to make a clean code. We realized that this was a mistake, so we decided to restructure the project to make it more modular and no longer a big ball of mud.

To do this, we have based ourselves on clean architecture, to which the following diagram refers:

Clean Architecture

5. Building Block View

The building block view shows the static decomposition of the system into building blocks as well as their dependencies.

5.1. Whitebox Overall System

We have two views, the main one (index.html), which is the one used to perform the user’s logging, and the secondary one (two-people-chat.html) which purpose is to make possible the chat between two people.

It is necessary to incorporate the login module since the application is customized according to the logged user. For example, the friends list will not be the same for all users, but each user will have their own friends list.

Hierarchy of building blocks
Contained building blocks
Name Responsibility

DeChat_es5b

It represents the application and allows the user to chat with any other person.

5.1.1. Level 1

This level specifies the main views with which the user will interact.

Contained building blocks
Name Responsibility

index.html

The purpose of this box is to let the user log in with his own user account, so it allows him obtain an experience of the application as personalized as possible.

two-people-chat.html

The purpose of this box is to ensure that two users can communicate by chatting.

The user interface will show a side navigation bar showing the friends of the authenticated user with whom he can chat.

The interface also shows a panel in which the conversation is shown in real time.

index.js

Both principal viewa contain the index.js script. This script contains all the application functionality, which is specified on level 2.

5.1.2. Level 2

This level contains the application core information. All the functionality of the script index.js.

Contained building blocks
Name Responsibility

main.js

It is the main script of the hierarchy. Its task is to bring together all the main functionalities.

LogInManager.js

It is the script in charge of the functionality that has to do with the user’s login.

popup.html

This is the corresponding view with the pop-up window that appears when you try to log in to the application.

ChatManager.js

The script in charge of all the functionality pertaining to the sending and receiving of messages between users.

NotificationManager.js

It is the script which purpose is to add the notifications functionality to the chat.

PodUtilities.js

It implements an adapter by adding functionality to the solid-file-client library. It is used by all scripts in the logic layer to communicate with PODs.

6. Runtime View

In this section, we will develop the main runtime views of use cases of our application.

6.1. Log in

The login process will be done by users when they log in with their pesonal id to access the chat.

  1. The user click on the login button.

  2. The user enters his or her credentials.

  3. LoginManager call PodUtilities login method to try to login.

  4. The server deny the authentication.

  5. The server approve the authentication.

  6. The user can start chatting.

Log in diagram

6.2. Chat with added friends

The users use the application to chat with their friends. Here we will explain the sequence for send messages.

  1. User 1 sends the message to user 2.

  2. The application of user 1 post the message on the user 1’s pod.

  3. User 2’s application requests received messages to the pod. The pod makes them available to the application and shows them through the interface.

  4. User 2 reads the recieved messages from the application.

Exchange messages diagram

7. Deployment View

The product is a descentralized chat based in SOLID and his PODs. Base application will be able to run in any machine based in web applications like Chrome.

Developing an descetralized app means that a central server is not required to store any information used by the user, beside the server needed to authentificate the user connection. this last requirement may be solved by using the SOLID Community sistem already implemented for the signing up/login process.

A SOLID server and a DeChat instance were deployed in an Amazon Web Services EC2 Server, but were terminated due to server issues.

At this moment DeChat can be downloaded as a Windows app (win32_x64) directly or download source and compile it to Linux or MacOS target. If you do not want to download binaries, you can still use this chat at GitHub Pages (https://arquisoft.github.io/dechat_es5b)

By default, SOLID Servers have a 25 MB disk limit. This can be a problem, for example, when uploading photos or videos to chats, as they can eat up all free space quickly.

8. Cross-cutting Concepts

8.1. User Experience concepts (UX)

8.1.1. User interface:

We have implemented a user interface using the bootstrap library. It’s composed of two main pages: login page and chat room. The interface prototype is shown in the next prototype:

Chat room interface

8.1.2. Internacionalization:

DeChat ES5B is internationalized. At this moment, you can browse our chat in English (default), Spanish, Chinese (Simplified) and Galego.

A browser-based system were implemented. This means that you do not need to reaload the whole page to change language.

8.2. Design patterns

8.2.1. Design Pattern: Adapter

To implement the solid-file-client library (which allows us to communicate with the PODs) we have made use of an adapter that adds functionality to the initial library. The Adapter is called PodUtilities. The solid-file-client library is imported in this class and it is called by the logic classes to communicate with the PODs and get the data.

Adapter pattern

8.2.2. Architectural pattern: Three-tier architecture

We have separated architecture into layers of presentation, logic and persistence. The implementation of the previous architecture has been carried out following the following diagram below:

Three-tier architecture

8.3. Development concepts

8.3.1. Test

We have developed an extensive and exhaustive test layer that can be launched by following the steps indicated in the readme.

8.3.2. Deploy

The chat application is displayed on the page associated with the git repository. It can be accessed from the following deChat_es5b.

Possible topics for crosscutting concepts

9. Design Decisions

In this document we’ll show important, expensive, large scale or risky architecture decisions that may greatly influence our project.

Decisions list:
  • Our team has decided to write the code of this program in JavaScript using Node.js as the execution platform for the sake of reducing the dependence on frameworks.

  • We toke an initial idea from the Solid-chess that has been previously presented to us since it’s a great example of our goal.

  • We chose to use the Solid file client library and WebPack package for the managing of files and folders of this chat as we are based on Solid.

  • We are using Mocha and Chai for the unit tests because it’s convenient.

  • We are using Cucumber for acceptance tests as recommended by our teacher.

  • We are using Bootstrap to design the project because some of our members knew how to use it.

  • We also try to use Angular technology, but we discard it because of its complicity. We agreed to use then Node.js.

  • We also discard to use other programming languages like Java or SpringBoot because they didn’t match the functionality our chat needed.

10. Quality Requirements

Here we will explain using scenarios some of the quality requeriments of this project.

10.1. User stories:

Below we describe the user stories we have used in the acceptance tests:

  • As a dechat_5b user I want to know if i’m chatting with the right friend

  • As a dechat_5b user I want to see my friend’s list

  • As a dechat_5b user I want to know if I can send a message without chosing a friend

  • As a dechat_5b user I want to know if I can recieve a message from a contact

  • As a dechat_5b user I want to know if I can send a message to a contact

List of requirements

Most Basic requirement

  • The first and most important is the protection towards the private information of the user, because it is the main objetive of our proyect. We will acomplish this by saving every information of the user in a POD, but only those of the user himself never those of the other users. This POD can only be accesed by the user and those who have the permission of the user.[High priority]

Diagram quality requeriments 01

10.2. Quality Tree

QualityTree

10.3. Quality Scenarios

Quality attributes Scenarios Priority

Availability

This chat will be available to anyone who has a Solid account and a Solid POD to store user information.

High

Modifiability

If it is necessary to change something in the proyect, it should be possible to do so without modifying the previous code too much.

High

Performance

If you write something in the chat, it will be sent instantly and will not undergo any change or manipulation.

High

Security

The security will depend on the user since he is the one who gives permissions on his own information.

High

Testability

We are using Codecov for code coverage, ensuring it at least reaches 80% of code coverage.

High

Usability

It should be possible to chat with 2 or more users at the same time, without any problems.

High

Usability

If possible we want to add images, gifs or emojis to the chat, giving the users more forms of sharing their emotions with their conversation partners.

Medium

11. Risks and Technical Debts

In this section we will show a list of identified technical risks or technical debts, ordered by priority.

List of technical risks:

  • Unknown framework and technology to work with.

  • Poor group work experience.

  • Conflicts in the version control system.

  • Discard technologies because of their difficulty.

12. Glossary

This section defines the most important domain and technical terms:

Term Definition

Angular

Angular is a JavaScript development framework created by Google. The purpose of Angular is to facilitate the development of SPA web applications and also give us tools to work with the elements of a web in a simpler and more optimal.

Application

An application is a program or a set of programs developed to obtain a specific functionality that serves an end user.

Arc42

arc42 offers a clear, simple and effective structure to document and communicate your software system.

AsciiDoc

AsciiDoc is a human-readable document format that uses plain text marking conventions.

AsciidocFX

Book / document editor to build PDF, Epub, Mobi and HTML books, documents and slides.

Beta version

A Beta version is a software version that has passed the internal testing stage, called "Alpha" and has been released to users for public testing.

Black Box

A black box is an element that is studied from the point of view of its inputs and outputs, without taking into account its internal functionality.

Bootstrap

Open-source front-end Web framework. It contains HTML and CSS-based design templates for typography, forms, buttons, navigation and other interface components, as well as optional JavaScript extensions.

Browser

A program that allows you to surf the Internet or another computer communications network.

Building Block View

The building block view is the documentation’s section that shows the static decomposition of the system into building blocks as well as their dependencies.

Chat

A chat is a computer application that allows two or more people to communicate using instant messaging.

Constraints

Constraints are limitations to which our project must conform. They can be technical or organizational

Coveralls

See the latest code-coverage statistics on all of the project including the total percentages covered and the lines covered

Decentralized computing

Decentralized computing is the allocation of resources, both hardware and software, to each individual workstation, or office location. In contrast, centralized computing exists when the majority of functions are carried out, or obtained from a remote centralized location.

Framework

A framework is a scheme (a skeleton, a pattern) for the development and/or implementation of an application.

Git

Git is a version control software designed by Linus Torvalds, thinking about the efficiency and reliability of maintaining versions of applications when they have a large number of source code files.

GitHub

GitHub is a platform for hosting projects using the Git version control system.

Glossary

The glossary contains the most important domain and technical terms that your stakeholders use when discussing the system.

Interface

An interface provides a functional connection between two systems, programs or devices and allows communication at different levels allowing the exchange of information.

Log in

Log in is the process by which individual access to a computer system is controlled.

Node.js

Open-source, cross-platform JavaScript run-time environment that executes JavaScript code outside of a browser. JavaScript is used primarily for client-side scripting, in which scripts written in JavaScript are embedded in a webpage’s HTML and run client-side by a JavaScript engine in the user’s web browser. Node.js lets developers use JavaScript to write command line tools and for server-side scripting

Open source

Open source is a model of software development based on open collaboration. It focuses more on the practical benefits (access to source code) than on the ethical or freedom issues that are so prominent in free software.

Operative system

Set of commands and programs that control the basic processes of a computer and allow the operation of other programs.

POD

A Solid application stores the information in PODs (Personal Online Data stores) hosted wherever the user desires.Applications that are authenticated by Solid are allowed to request data if the user has given the application permission.

POD Provider

A person or company that has one or more solid pod servers and uses them to host consumer data.

POD Server

Server that allows the application store POD information on it.

RDF

RDF is a web specification that is used for the conceptual description or modeling of information that is implemented in web resources. It was originally created for the metadata model.

rdflib.js

rdflib.js is the library used to manage data on RDF format, which is used by Solid applications.

SOLID

Solid is an exciting new project led by Prof. Tim Berners-Lee, inventor of the World Wide Web, taking place at MIT. The project aims to radically change the way Web applications work today, resulting in true data ownership as well as improved privacy.

SOLID Community

The mission of the Solid Community Group is to try to reshape the web by fostering a new breed of applications with capabilities above and beyond anything that exists today. Participants in this group will create applications, author technical specifications, and capture best practices.

SOLID file client

Library that provides a simple interface for logging in and out of a Solid data store, maintaining a persistent session, and for managing files and folders.

Template

A template or interface device usually provides a separation between the form or structure and the content. It is a medium or device or system, that allows to guide, to carry, or to construct, a predefined design or scheme.

TypeScript

TypeScript is an open source programming language with object-oriented programming tools, very favorable if you have large projects.

User

A person who uses a particular application or computer system.

User account

In order for users to obtain security, access to the system, resource management, etc., these users must identify themselves. To identify themselves, users need a user account, that is, a part of the system where personalized user information is stored.

Webpack

Open-source JavaScript module bundler. Its main purpose is to bundle JavaScript files for usage in a browser, yet it is also capable of transforming, bundling, or packaging just about any resource or asset. Webpack takes modules with dependencies and generates static assets representing those modules.

White Box

White box diagrams offer an internal view of the functionality that an application or module should have; as opposed to black box diagrams focus more on external functionality.

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.