DeDe_en1a

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

Dede is a project developed for the Software Architecture course of the University of Oviedo. This version will be developed by the team En1A:

Landon Brown
Rosa García López
Joaquín Salustiano Britos Morales
Juan Andrés Torrente Bermúdez
Luis Vijande González

Dede Deals is a privacy-oriented, online-based marketplace where vendors publish their products and clients can register with the assurance of their private information not being stored in the application.

1.1. Requirements Overview

The platform will consist on a ReactJS webapp that will communicate with the server-side backend through a REST API. The client will call the API functionalities to offer the user all the functionalities in a decoupled and easy to work way.

The application will store the information about the vendors and their products in a relational database, and the user data (bank and address) will not be stored locally but accessed through their personal SOLID pod.

Through the application, vendors will be able to publish their products, and clients will access the catalog and buy them.

1.2. Quality Goals

Priority	Quality	Motivation
1	Privacy	The use of SOLID pods opens up many privacy and security options in benefit of the users.
2	Usability	As any application, the response time, learning curve and navigability of the application should follow the standards and expected minimums.
3	Maintainability	Good architecture and design to show the team capabilities and make the application easily maintainable.
4	Availability	The application must be accessible the 24 hours of the day.

Priority

Quality

Motivation

Privacy

The use of SOLID pods opens up many privacy and security options in benefit of the users.

Usability

As any application, the response time, learning curve and navigability of the application should follow the standards and expected minimums.

Maintainability

Good architecture and design to show the team capabilities and make the application easily maintainable.

Availability

The application must be accessible the 24 hours of the day.

1.3. Stakeholders

Role/Name	Contact	Expectations
Students	<Contact-1>	Developers of the application. They will try to apply good practises as well as try to learn new technologies and teamwork techniques.
Teachers	<Contact-2>	Supervisors of the development. They will help the students and make sure the development follows the right path.
Users	<Contact-3>	Final users of the application.
Empathy (company)	<Contact-4>	Company that collaborates with the project.

Role/Name

Contact

Expectations

Students

<Contact-1>

Developers of the application. They will try to apply good practises as well as try to learn new technologies and teamwork techniques.

Teachers

<Contact-2>

Supervisors of the development. They will help the students and make sure the development follows the right path.

Users

<Contact-3>

Final users of the application.

Empathy (company)

<Contact-4>

Company that collaborates with the project.

2. Architecture Constraints

Constraint	Description
Technical	The project must be implemented using React and Typescript, using Git as a version control system. In addition, data access must be performed through a SOLID platform whenever possible.
Organizational	The team must carry out meetings in at least a weekly basis, as instructed by the lecturers. Also, deadlines decided by the professors must be followed.
Budget	As this is a school project, we don’t have any budget to spend, nor a need for it.

Constraint

Description

Technical

The project must be implemented using React and Typescript, using Git as a version control system. In addition, data access must be performed through a SOLID platform whenever possible.

Organizational

The team must carry out meetings in at least a weekly basis, as instructed by the lecturers. Also, deadlines decided by the professors must be followed.

Budget

As this is a school project, we don’t have any budget to spend, nor a need for it.

3. System Scope and Context

The application we have developed, DeDe, is an online retail system whose first priority is its clients privacy. In order to achieve this goal we use a new decentralized technology called SOLID where users store their data in POD’s, hence they are in control of the information.

3.1. Business Context

When the user first arrives to the application, they will be able to browse and view the details of every product. In order to make a purchase, they must be logged in.

The login process takes place in the pod provider provided by the user and when finished it creates a session in the application which will be used to manage all internal logic.

Whenever the user wants to make an order, a series of steps will be followed; first, the list of products the client has chosen will be displayed and open to change, second the shipping information will be displayed and in case no valid information is found in the pod, the client will be able to fill it up.

Finally, when the user reaches the end of the checkout process an order summary will be displayed with the order information, total cost and shipping.

Once the order is placed, it is saved in the database and the user is given the option to see their orders or continue shopping.

3.2. Technical Context

The user will execute the application and will interact with the GUI in order to choose what products to buy. When the selection is done and the client wants to make an order the application will require them to Log in its Pod.

Following this, the backend will manage the necessary interactions with the user’s POD and the product database in order to provide an estimated cost of delivery and compute the total cost of the order.

4. Solution Strategy

4.1. Technology decisions

ReactJS

The frontend web application will be developed using React, one of the most used Javascript framework nowadays.

MongoDB

We will use Mongo as database engine, as we have already experience working with it and it is easy to integrate into TS/JS.

NodeJS express + Typescript

These will be the technologies we will use for the application backend. Typescript will be the main programming language for business logic and data access, and the REST API will be written using NodeJS express, a framework commonly used for this purpose.

Docker on Ubuntu

We use Docker running on an Ubuntu host to deploy the different parts of our application. This is one of the most common deployment configurations nowadays.

4.2. Top-level decomposition

We decided to follow an MVC architectural pattern. This seems to us as the most straightforward way to develop the project, as this approach directly supports the use of different technologies on different layers.

4.3. How to achieve quality goals

In order to accomplish our privacy goals, we will try to reduce to the minimum the amount of information stored in our database. To accomplish usability, we will try to follow the GUI standards and achieve minimum performance requirements in relation with response-time. In relation with maintainability, we will keep an updated documentation and try to use design and architectural patterns when possible. The availability quality will be accomplished if we can maintain our application deployed forever.

4.4. Organizational decisions constraints

At least one in-person team meeting will be done every week. More meetings will be organized via a discord server when needed. Smaller details will be discussed via WhatsApp and the GitHub issues. We will keep track of the pending and done tasks with the kanban tool available in GitHub.

5. Building Block View

5.1. Level 1

Building Block View Level 1

Motivation: This figure shows the highest-level view of the DeDe application with its dependent databases.
1) DeDe: Web Application that allows users to order products from an online store to their home in a decentralized manner. Connects to the user’s Personal Online Datastore (POD) and the product database (hosted via MongoDB).
2) POD: The user’s Personal Online Data store, allows the app to be decentralized and only have access to the user’s information when permitted by the user. Stores data such as the user’s personal address, payment information, etc.
3) Product Database: Stores information of products (i.e. name, cost, description, availability, etc.). Built with MongoDB.

5.2. Level 2

Building Block View Level 2

Motivation: This figure shows the decomposition of the DeDe application into its frontend (WebApp) and backend (RestAPI), as well as the most important external libraries/frameworks that support each.
1) WebApp: The WebApp is a web application which provides the user with an interface that allows them to view products, add them to a virtual shopping cart, login to their POD account, and checkout. Aside from displaying database information in a user friendly way, it also manages user requests and communicates with the backend to fulfill them.
2) RestAPI: The restAPI defines DeDe’s API in accordance with REST architecture, which allows DeDe to communicate with the product database and the user’s POD. It also provides service to the WebApp so that the WebApp may grab information from the databases when necessary. Contains the models and business logic used to calculate delivery costs.

Software	Responsibility
Node.JS	Backend runtime environment where the TypeScript code runs.
React.JS	JavaScript library used to build user interface.
Material UI	Framework for building application components.
Express.JS	Node library for API building.
Inrupt	JS library for SOLID (POD) support.
Mongoose	JS library for MongoDB connections and integration.

Software

Responsibility

Node.JS

Backend runtime environment where the TypeScript code runs.

React.JS

JavaScript library used to build user interface.

Material UI

Framework for building application components.

Express.JS

Node library for API building.

Inrupt

JS library for SOLID (POD) support.

Mongoose

JS library for MongoDB connections and integration.

6. Runtime View

6.1. Alice wants to order a new product

Alice discovers this application by recommendation of a friend and wants to buy a new perfume she has been wanting since past christmas.
In the following diagram you can see that Alice first browses through the list of products available in the application, when she chooses one it is added to her cart.

6.2. Bob wants to process an order to buy products

Bob has been browsing DeDe and has added some cool products to his order, but now he wants to process that order and buy the products.
In the following diagram you can see how Bob proceeds to make an order to buy the products. In order to proceed to checkout Bob needs to log in its Solid Pod to retrieve his addresses, then, the total cost of the order is calculated.

6.3. Bob wants to check his placed orders

Bob is a loyal client and has placed some orders, now he wants to check those to verify everything is correct.
In the following diagram you can see how Bob proceeds to check his orders. In order to retrieve Bob’s orders the application will request him to log in.

6.4. Alice wants to become a seller

Alice has been using our wonderful app for some time and trusts our privacy policies. She has decided to start a small business and will use our site to sell her products.
In the following diagram the process to become a seller can be seen. In order to do this, Alice must be logged in.

6.5. Alice wants to log in as a seller

Alice has made an account in DeDe and logged out but now wants to log in again.
In the following diagram the process to log in as a seller can be seen.

6.6. Alice wants to add a product

Alice has made an account in DeDe and logged in, now she wants to add some products to sell.
In the following diagram the process to add products belonging to a seller. We will suppose Alice has already logged in as a seller.

6.7. Bob wants to search a new product

Bob has logged in his pod and wants to buy a new product but there are so many products that he cannot see the one he likes. Fortunately our experienced developers have implemented a search and filtering tool.

6.8. Bob wants to log out from the application

Bob has made some orders and now wants to log out from the application.

7. Deployment View

7.1. Level 1

Top-level Deployment View

Motivation: The DeDe Deals application is deployed in accordance with goals of continuous integration and adherance to SOLID design principles. In addition, hosting the application on a remote server allows it to be accessible from the Internet, from any place in the world.
Quality and/or Performance Features: Hosting the application on the AWS cloud platform allows for continuous integration, so the application is automatically updated as new developments are committed.

Utilizing the user’s POD following SOLID design principles allows the application to be decentralized.

Virtual Environment	Responsibility
Azure	Cloud platform which hosts the DeDe stack on a VPS.
Ubuntu Machine	Linux virtual machine where docker containers and other related software runs.
Docker	Process isolation platform which allows the different parts of the application to be packaged in deployable images which run containerized independently of the underlying operating system.

Virtual Environment

Responsibility

Azure

Cloud platform which hosts the DeDe stack on a VPS.

Ubuntu Machine

Linux virtual machine where docker containers and other related software runs.

Docker

Process isolation platform which allows the different parts of the application to be packaged in deployable images which run containerized independently of the underlying operating system.

Software	Responsibility
WebApp	Communicates database information to User and manages User Input. Displays the different functionalities to the user.
RestAPI	Endpoint for app requests to the backend. Includes backend where business logic is managed.
Grafana	Metrics aggregator. Queries Prometheus for statistics on the application and presents them to the administrator.
Prometheus	Metrics collector. Attached to the RestAPI instance, it collects information about the application.
Node Exporter	Prometheus extension. Collects information about the machine which is fed to the main Prometheus instance.
NGINX	Server software. Acts as a router and as a reverse proxy. Forces HTTPS on connections to and from Webapp and RestAPI and redirects traffic on ports 80/443 to 3000, presenting the webapp.

Software

Responsibility

WebApp

Communicates database information to User and manages User Input. Displays the different functionalities to the user.

RestAPI

Endpoint for app requests to the backend. Includes backend where business logic is managed.

Grafana

Metrics aggregator. Queries Prometheus for statistics on the application and presents them to the administrator.

Prometheus

Metrics collector. Attached to the RestAPI instance, it collects information about the application.

Node Exporter

Prometheus extension. Collects information about the machine which is fed to the main Prometheus instance.

NGINX

Server software. Acts as a router and as a reverse proxy. Forces HTTPS on connections to and from Webapp and RestAPI and redirects traffic on ports 80/443 to 3000, presenting the webapp.

Interlinking Concepts	Responsibility
DeDe Application	Combination of WebApp (front end web application) and RestAPI (backend + business logic).
User POD	Where the user’s personal information is stored, which the DeDe App must be granted permission to access.
Application DB	Database storing product information such as name, description, cost, availability, etc. Built using MongoDB.
User Device	Device from which the user will access the DeDe application.

Interlinking Concepts

Responsibility

DeDe Application

Combination of WebApp (front end web application) and RestAPI (backend + business logic).

User POD

Where the user’s personal information is stored, which the DeDe App must be granted permission to access.

Application DB

Database storing product information such as name, description, cost, availability, etc. Built using MongoDB.

User Device

Device from which the user will access the DeDe application.

8. Cross-cutting Concepts

8.1. Domain model

UML Diagram

8.2. Domain concepts

Domain concept	Description
User	A user represents the end user that will buy products in the application.
Administrator	A user role that can perform upgraded actions.
Seller	An user role that sells products in the application.
Product	Represents every product that will be sold through the application.
Order	Contains necessary data for the delivery, and a collection of products and quantities.

Domain concept

Description

User

A user represents the end user that will buy products in the application.

Administrator

A user role that can perform upgraded actions.

Seller

An user role that sells products in the application.

Product

Represents every product that will be sold through the application.

Order

Contains necessary data for the delivery, and a collection of products and quantities.

9. Design Decisions

Here we will document the technologies that affect the application, and we will be explaining why below.

9.1. MongoDB

Context

While user data will always be accessed from their PODs and never stored, there is still some data the application handles which needs to be stored, such as product information and order placements. For this purpose, we will use MongoDB, since the format it uses is readily translatable to JavaScript objects.

9.2. Nominatim

Context

To calculate the distance between the warehouse and the user address we make use of the Nominatim library. It offers us a simple and easy way of calculating the distances.

9.3. JWT Token

Context

To create user authorization we make use of JWT tokens, which securely store a privileged session.

10. Quality Requirements

This section contains all quality requirements as quality tree with scenarios.

Since quality requirements will have a lot of influence on architectural decisions we should know for every stakeholder what is really important to them, concrete and measurable.

We have already talked about quality goals in section 1.2, but in this section we will expand on that topic, using a quality tree (provides an overview of the attributes) and some quality scenarios (describe what happens when a stimulus arrives at the system).

10.1. Quality Tree

10.2. Quality Scenarios

Here we have an initial table with our quality goals, scenarios, priorities and difficulty:

Quality goal: quality measurable subject which needs to reach a target level.
Scenario: description of the system behaviour and helps the measure of quality.
Priority: priority in the development of the application.
Difficulty: difficulty to archive the quality goal.

Quality goal	Scenario	Priority	Difficulty
Privacy	Private data from the users has to be protected and secure. The application only takes essential data from the user, and in a decentralized approach.	High	High
Usability	Users have to be able to navigate through the application in an intuitive way.	Medium	Medium
Maintainability	The application should be written in a way that code can be reused and modified in a simple way, bugs can be easily found and fixed, and the program should be easy to test.	Medium	High
Availability	Users have to be able to use the application at any time any day.	High	High

Quality goal

Scenario

Priority

Difficulty

Privacy

Private data from the users has to be protected and secure. The application only takes essential data from the user, and in a decentralized approach.

High

Usability

Users have to be able to navigate through the application in an intuitive way.

Medium

Maintainability

The application should be written in a way that code can be reused and modified in a simple way, bugs can be easily found and fixed, and the program should be easy to test.

Medium

High

Availability

Users have to be able to use the application at any time any day.

High

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.

Table 1. Risks Table
Risk	Explanation	Solution
Lack of knowledge of SOLID	It’s a new technology, and we have no idea how to work with it. The documentation is lacklester and there are not many examples. Some of the libraries are in develepment, so they are unstable and buggy.	We must do our own research, ask other students and other developers. We need to have a good understanding of the technology first.
Lack of knowledge of React	Although we have some knowledge of JavaScript, we are new to React and Node.	React has very good documentation, so we can check examples. We have to understand how Node works. This part should be easier to deal with than the previous one.
Lack of knowledge of Typescript	We are not experts on Javascript and we need to adapt to this extension.	Typescript has examples and a good documentation to work on. We have to get accustomed to the language with practice.
Time	We are limited by the deadlines of the course.	All we can do is optimize our working time.
Working on teams	Working with other people is not always easy, since each one does things their way.	We have to do regular meetings and try to comment our code, so everyone can understand it and work with it.
Decentralized application	Working with pods makes development a lot harder, because we have to optimize the network usage so the application can run smoothly.	We have to be concerned about the load tests and try to optimize the algorithms so they do the least network petitions possible.

Table 2. Technical Debts Table
Technical Debt	Explanation
Chaotic dependency tree	Although we have mostly cleaned up our dependency tree vastly improving build times, we still need to give it another look.
Code quality	We are aware that there exist several hotspots on our application and code smell. This could create problems on the future.
Input sanitation	As we were short on time we ended up not sanitating the user input

12. Glossary

Term	Definition
POD	Secure personal web data servers from SOLID. The owner controls who and what can access their pods.
React	Open-source, front end, JavaScript library for building user interfaces or UI components. It is used as a base in the development of single-page or mobile applications.
Node.js	Platform built on Chrome’s JavaScript runtime for easily building fast and scalable network applications.
Mongoose	JavaScript library that helps with building the definition of schemas for the MongoDB database, providing a lot of functionality for that purpose.
Docker	It is an open source project which automatizes the application deployment inside software containers.

Term

Definition

POD

Secure personal web data servers from SOLID. The owner controls who and what can access their pods.

React

Open-source, front end, JavaScript library for building user interfaces or UI components. It is used as a base in the development of single-page or mobile applications.

Node.js

Platform built on Chrome’s JavaScript runtime for easily building fast and scalable network applications.

Mongoose

JavaScript library that helps with building the definition of schemas for the MongoDB database, providing a lot of functionality for that purpose.

Docker

It is an open source project which automatizes the application deployment inside software containers.

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