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.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 |
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:
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.
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:
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.
- 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.
-
The user click on the login button.
-
The user enters his or her credentials.
-
LoginManager call PodUtilities login method to try to login.
-
The server deny the authentication.
-
The server approve the authentication.
-
The user can start chatting.
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.
-
User 1 sends the message to user 2.
-
The application of user 1 post the message on the user 1’s pod.
-
User 2’s application requests received messages to the pod. The pod makes them available to the application and shows them through the interface.
-
User 2 reads the recieved messages from the application.
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.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.
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.
9. Design Decisions
In this document we’ll show important, expensive, large scale or risky architecture decisions that may greatly influence our project.
-
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
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.