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

Decentraliced Delivery or DeDe is a new, decentralized, and open-source delivery system. Based on the Solid Priciples for privacy and security. The application focuses on the sale of sporting goods, especially balls and rackets. This application is designed for:

  • Having a virtual shop that can be accessed by anyone

  • Delviering the products to the customers

  • Providing a secure and private data management system

1.1. Requirements Overview

Here is a list of the functional and non-functional requirements that the application will support.

  • Functional Requirements

    • The user can select the products he wants to order or buy

    • The system will calculate the shipping costs through the address stored in the user’s pod

    • The application will calculate the final prices of the purchase and register the event to start shipping

    • The system will allow the user to check their orders placed

  • Non-Functional Requirements

    • System must support SOLID

1.2. Quality Goals

Objetive Motivation Priority

Privacity

The application will guarantee a high level of privacy and security, respecting the personal information of users

1

Usabilty

The graphical interface of the application must not transmit doubts of use to the users. It should be easy to understand for novice users

2

Efficiency

The charging times between windows should be as low as possible so as not to upset the user

3

Availability

The application has to be constantly running. If a problem occurs, maintenance times should be as short as possible

4

Testability

Failures during program execution will be minimized

5

1.3. Stakeholders

Role/Name Contact Expectations

Client

Teachers. They evaluate the project

They check that the project meets the expectations of the subject in addition to its proper functioning

Users

They use the application

They are the users who are interested in using the application

Developers

Team in charge of developing and testing the project (dedeportes)

They create the project from the skeleton iteratively. They are responsible for making the application functional and secure

Admin

He use the aplication with priviliges

It is a special user that has privileges to see all orders placed

2. Architecture Constraints

Contents

Any requirement that constrains software architects in their freedom of design and implementation decisions or decision about the development process. These constraints sometimes go beyond individual systems and are valid for whole organizations and companies.

Motivation

Architects should know exactly where they are free in their design decisions and where they must adhere to constraints. Constraints must always be dealt with; they may be negotiable, though.

Form

Simple tables of constraints with explanations. If needed you can subdivide them into technical constraints, organizational and political constraints and conventions (e.g. programming or versioning guidelines, documentation or naming conventions)

2.1. Technical Constraints

Constraint

Motivation

TypeScript

Is the language that will be used in the project

React

Is the library that help us to make the GUI

SOLID

Help us to follow a descentralized management of the user data

POD

Stores the user data and restricts its use unless the user wants to share it

2.2. Organizational Constraints

Constraint

Explanation

Time

The project will be finish until the 25th of april

Experience

1 out of 5 has some experience on Solid and the development of this kind of projects

Team

The team is composed by 5 members. Each one has his own projects apart from this one so it could be hard to organize a meeting

Data

The products of the catalogue and the orders will be stored in the Database. There will also be a collection that will relate products to orders. The users data will be stored in PODs that will be connected to the app to get the shipping address

Version Control

All changes are going to be commited in GitHub in different branches. The master branch is where the non-error application is going to be and the develop branch is where the team is going to work creating from it the different branches that will be needed

2.3. Conventions

Constraint

Details

Language

The language used for the entire documentation and project will be english

Documentation

The documentation is going to follow the arc42 structure

Control Version

The developement of the application will be controled by git version control on the platform GitHub

3. System Scope and Context

Contents

System scope and context - as the name suggests - delimits your system (i.e. your scope) from all its communication partners (neighboring systems and users, i.e. the context of your system). It thereby specifies the external interfaces.

If necessary, differentiate the business context (domain specific inputs and outputs) from the technical context (channels, protocols, hardware).

Motivation

The domain interfaces and technical interfaces to communication partners are among your system’s most critical aspects. Make sure that you completely understand them.

Form

Various options:

  • Context diagrams

  • Lists of communication partners and their interfaces.

The main objetive of DeDeportes is to create a sports store with products related to sports. The application that contains the online store is going to be descentralized and also be based on Solid so each client will have its own POD. This POD stores the users information and it cannot be acceded unless the user authorized it. The most frequent user of this appplication is going to be the client interested in sport products.

3.1. Business Context

Contents

Specification of all communication partners (users, IT-systems, …​) with explanations of domain specific inputs and outputs or interfaces. Optionally you can add domain specific formats or communication protocols.

Motivation

All stakeholders should understand which data are exchanged with the environment of the system.

Form

All kinds of diagrams that show the system as a black box and specify the domain interfaces to communication partners.

Alternatively (or additionally) you can use a table. The title of the table is the name of your system, the three columns contain the name of the communication partner, the inputs, and the outputs.

Element

Input

Output

User

Recipe

Products that the client want

POD

User info

Shipping Address

Database

Client order

Products

App (DeDeportes)

Order/Products

Recipe/Client Order

Possible topics for crosscutting concepts

First of all the client should sign in the POD sending his information. Then he can pick up products to make the order, once he ended the POD send the shipping address to make the full order and it´s send to the database for a future send. The product´s info are given to the application by the database.

3.2. Technical Context

Contents

Technical interfaces (channels and transmission media) linking your system to its environment. In addition a mapping of domain specific input/output to the channels, i.e. an explanation with I/O uses which channel.

Motivation

Many stakeholders make architectural decision based on the technical interfaces between the system and its context. Especially infrastructure or hardware designers decide these technical interfaces.

Form

E.g. UML deployment diagram describing channels to neighboring systems, together with a mapping table showing the relationships between channels and input/output.

Technology

Description of usage

SOLID architecture

Is used for the secure management of the user data furthermore this data is decentralized

POD

Where the application is going to take the user data, if he allows it. POD stores the user information.

TypeScript

Is the language used to generate the events of the store. It is a JavaScript versión with syntax control

React

Is an open-source library that helps the team to make the GUI with the help of TypeScript

React-Hot-Toast

Is an api that allows us to make floating notifications to the user

MUI

Is a library that help us on the view of the application

Cloudinary

Its the repository where we store the images of the products

4. Solution Strategy

Contents

A short summary and explanation of the fundamental decisions and solution strategies, that shape the system’s architecture. These include

  • technology decisions

  • decisions about the top-level decomposition of the system, e.g. usage of an architectural pattern or design pattern

  • decisions on how to achieve key quality goals

  • relevant organizational decisions, e.g. selecting a development process or delegating certain tasks to third parties.

Motivation

These decisions form the cornerstones for your architecture. They are the basis for many other detailed decisions or implementation rules.

Form

Keep the explanation of these key decisions short.

Motivate what you have decided and why you decided that way, based upon your problem statement, the quality goals and key constraints. Refer to details in the following sections.

4.1. Technology Decisions

4.1.1. Back-end

  • Solid: Gives the user the choice of the data that he wants to share with the application

  • MVC: The arquitecture that we will be using for the project structure

  • MongoDB: The type of data base that we will be using for the application

  • MongoDB Atlas: Is where the data base will be deployed

  • Docker: Will be used for the deployment of the application

  • Heroku: Will be used for the deployment of the application

4.1.2. Front-end

  • React: It’s a JavaScript library used for doing interfaces. It’s based on components.

  • MUI library: It’s a react user interface library that help us on the front-end.

4.2. Quality objectives

Quality objectives

How to obtain them

Privacy

We are going to store the location of the users to calculate the shipping cost and also the client credit card´s information to carry out the payment of the order

Usability

We are going to design easy-to-use user interfaces to help nobel and experimented users

Testability

We are going to do some tests, both frontend and backend, to guarantee the correct and succesfully functioning of the application

Performance

We are going to use technologies that helps the application performance

4.3. Development tools

While we develop the proyect we will use the following tools:

  • GitHub: This platform will help to follow a control of the different versions implemented by each member of the team. We can check as well the work pushed by other members using the pull request to master, to make sure that there are no errors.

  • Visual Studio Code: We will use this as our source code editor as it has some plugins available to download that will help us in our work of develop this proyect.

  • GitKraken: This app allows us to change between the different branches easily and shows the commits done in each branches by the members.

  • Docker: This app makes containers that allows our proyect to be deployed in any machine with Docker installed.

4.4. Organization

We will use different medias to get in touch and discuss decitions. We have choosen the following ones:

  • WhatsApp: We can set up a meeting whith messages by this media.

  • Discord: Will let us to make weekly meetings.

  • Issues: Used to record the work that each memeber has to do.

  • Wikis: Used to record the decitions made in each meeting by the members.

4.4.1. How we work

We will divide the team into three groups:

  • 2 members dedicated to the front-end area

  • 2 members dedicated to the back-end area

  • 1 member dedicated to SOLID and PODs

Regarding the contributions, front-end and back-end work at the same time and together, therefore, even if the commits are from one, the work has been carried out by the two members.

Lastly, pull requests are accepted by the person who does not commit. Only in the case of the person dedicated to PODs is it reviewed. In the other cases, since it is carried out by two people simultaneously, it is not necessary

5. Building Block View

Decomposition of the code structured by levels, showing its internal dependencies.

5.1. Whitebox Overall System

This table explains the main actors that will interact with the application.

Actors

Description

Client

Actor that will interact directly with the application’s user interface. You will give the store access to your data through the POD.

Administrator

You will have access to the application, that is, you will be able to manage everything necessary for the proper functioning of the store.

Whtite box diagram

The database we are going to use is a remote one. It makes the use of it easier and can be used wherever the application is used.

5.2. Blackbox descriptions of Overall System

Name

Description

MongoDB

Database manager that will be responsible for providing the information to the application

SOLID

The client will have a POD with his information and he´s going to allow the application to acced to his information

DeDeportes user interface

User interface the client will interact with

6. Runtime View

Contents

The runtime view describes concrete behavior and interactions of the system’s building blocks in form of scenarios from the following areas:

  • important use cases or features: how do building blocks execute them?

  • interactions at critical external interfaces: how do building blocks cooperate with users and neighboring systems?

  • operation and administration: launch, start-up, stop

  • error and exception scenarios

Remark: The main criterion for the choice of possible scenarios (sequences, workflows) is their architectural relevance. It is not important to describe a large number of scenarios. You should rather document a representative selection.

Motivation

You should understand how (instances of) building blocks of your system perform their job and communicate at runtime. You will mainly capture scenarios in your documentation to communicate your architecture to stakeholders that are less willing or able to read and understand the static models (building block view, deployment view).

Form

There are many notations for describing scenarios, e.g.

  • numbered list of steps (in natural language)

  • activity diagrams or flow charts

  • sequence diagrams

  • BPMN or EPCs (event process chains)

  • state machines

  • …​

The runtime view describes the possible interactions of the different actors with the application.

This will help us understand how the elements of the application interact at runtime. The next schemes are some scenarios of our sport online shop.

6.1. Login with POD

  1. Client will choose My Profile in the home page.

  2. Client will choose in the menu the Login option.

  3. The client will be redirect to the Login page, where he has to press the Login Pod button and then, fill the gaps with his information.

  4. The client will be sent to the Pod’s supplier page.

  5. The Pod will accept or not the data provided.

  6. If the data is right the client will be redirect to the login page.

  7. If the data is wrong the client will continue in the Pod’s supplier page.

Sequence diagram Login

6.2. Get the content of the shopping cart

  1. Client will login in the application.

  2. The client will try to see the content of his shopping cart.

  3. The application is going to ask the database for that information.

  4. The database will return the list of products.

  5. Finally, the application will show the list to the client.

Sequence diagram Shopping cart

6.3. Login as an admin

  1. Client will choose My Profile in the home page.

  2. Client will choose in the menu the Login option.

  3. The client will be redirect to the Login page, where he has to press the Login Admin button and then, fill the gaps with his information.

  4. If the information is right a success notification will appear.

  5. If the information is wrong a failure notification will appear.

Sequence diagram Login admin

7. Deployment View

Deployment View

7.1. Elements

Artifact Description

DEDE development

Where DEDE development takes place.

Atlas System

Using Atlas hosting service for a MONGO Database.

Client Side

The device that the client is using to connect to the aplication

Solid Host

The host for the Client POD, can be choosen by the client and it must be configurated to use the address

Cloudiary System

Used to store all the product images.

Mapbox Api

Used to get some coordinates from an address to calculate the shipping costs.

AWS Host

Using Amazon Web Services to deploy the app by SSH.

Elastic Address

To only have one address in the case of app instances shuting down and changing their address.

8. Cross-cutting Concepts

Content

This section describes overall, principal regulations and solution ideas that are relevant in multiple parts (= cross-cutting) of your system. Such concepts are often related to multiple building blocks. They can include many different topics, such as

  • domain models

  • architecture patterns or design patterns

  • rules for using specific technology

  • principal, often technical decisions of overall decisions

  • implementation rules

Motivation

Concepts form the basis for conceptual integrity (consistency, homogeneity) of the architecture. Thus, they are an important contribution to achieve inner qualities of your system.

Some of these concepts cannot be assigned to individual building blocks (e.g. security or safety). This is the place in the template that we provided for a cohesive specification of such concepts.

Form

The form can be varied:

  • concept papers with any kind of structure

  • cross-cutting model excerpts or scenarios using notations of the architecture views

  • sample implementations, especially for technical concepts

  • reference to typical usage of standard frameworks (e.g. using Hibernate for object/relational mapping)

Structure

A potential (but not mandatory) structure for this section could be:

  • Domain concepts

  • User Experience concepts (UX)

  • Safety and security concepts

  • Architecture and design patterns

  • "Under-the-hood"

  • development concepts

  • operational concepts

Note: it might be difficult to assign individual concepts to one specific topic on this list.

Possible topics for crosscutting concepts

8.1. Domain model

UML Diagram

Although for the project we are using MongoDB, which is a non-relational database, our data model will be based on a model of entities and relationships. This is done like this because it makes us easier to build up the application and we can set up common atributes to all products of the data base.

8.2. Domain concepts

DeDeportes will be based in the sale of sport products.

  • POD: will store the individual information of each user as a repository following the SOLID specifications.

  • Order: will be an order of products of the store done by the user.

  • Product: will be all the sport materials available to buy by all the users in the store.

  • OrderedProduct will store the products of the multiple orders. Each one will have the product´s id and the order´s id.

In our application there´s going to be an administrator wich information is going to be stored in the user collection.

8.3. Development concepts

React is a JavaScript-based library, used for doing user interfaces. Facebook and open-source developers run it.

MongoDb will be used to store the products, the users, the users' orders and the ordered products.

Node.js is the package manager choosen to build the application.

For the time being we haven’t decided what are we using to make tests.

8.4. User Interface

The default user interface for DeDeportes is a Multiple Page Application written in TypeScript using React together with default Bootstrap and MUI templates.

For the POD login we use Solid authentication and the POD API.

8.5. Security

DEDE offers security for its API endpoints only via HTTP basic access authentication. Also by using the POD API we can check the user’s permissions and access only the resources that the user has given permissions.

8.6. Internationalization

Only supported language is Spanish. There is no hook for doing internationalization in the frontend and there are no plans for creating one for now.

9. Design Decisions

9.1. Using a nonSQL database for saving data.

Problem

Using normal SQL database like HSQLDB for this project is a good choice considering that we have knowledge and practice with this tipe, but in the face of pure documentation and examples MongoDb its a better alternative that fits in this project usisg a MERN frame.

Decision

Use MERN as teh project structure. MongoDB used as the project database.

Status

Accepted

9.2. Using POD

Problem

In the project, the application needs to access the client information so it would be a good option to use SOLID to satisfy that need.

Decision

We will use the user´s PODs. The client will give access to the application and then the app will access the client information.

Status

Accepted

9.3. Using a local database at the beginning and then insert it into the project

Problem

Having the database included in the project from the beginning will make it difficult for us to develop it.

Decision

To simplify the beginning of the project we will use a local database at the start. When the project progresses, after the second project´s review we will use Mongo Atlas to deploy the database in the cloud.

Status

Accepted

9.4. Choosing the language we´ll use in the documentation

Problem

Another design decission is the language used in the project. To develop the documentation we have two options, we can write it in English or in Spanish.

Decision

We have decided to carry out the documentation in English since in this way more people will be able to take charge of the project in a hypothetical future and understand what the project is about.

Status

Accepted

9.5. Choosing the storage of images for the webapp

Problem

Saving the stock images localy can be a problem if the cuantity and size of them are big, also the way to store it online is easier than locally

Decision

We’ll use Cloudiary to store the images, we will save on the database the url pointing to the concrete photo to display it on the webapp.

Status

Accepted

9.6. Using an extra database for the tests

Problem

We have to run the backend tests lots of times to test them, so our database will have lots of unused data.

Decision

We will use an extra database to run the restapi tests to not fill up our main database since to run the backend tests we need to run them many times.

Status

Accepted

9.7. Calculate the distance between two points

Problem

To calculate the shipping price we need to get the coordinates of the address of the client.

Decision

We use the MAPBOX api to get the coordinates of the address then with an mathematical formula to calculate the distance, then we asing a cost to the distance.

Status

Accepted

9.8. Deployment service

Problem

To deploy the app we need a provider, we ha thought to use Heroku but at that moment it had a problem.

Decision

We use AWS to deploy the app, also we deploy it by SSH on the CI.

Status

Accepted

10. Quality Requirements

10.1. Quality Tree

Quality Tree

10.2. Quality Scenarios

10.2.1. Security

By saving on the SOLID PODs the information of the user and also by only having esential info on the database. Also we encrypt the data of the petitions.

10.2.2. Testability / Coverage

We use Codecov and Sonarcloud during development to get the most coverage of our code. Also we are using js tests for testing both restapi and webapp, Jest for e2e tests and gatling for performance tests. This ensure code and app quality.

10.2.3. Eficency

We need to ensure a fast conection and transaction between the user and the app. Galting is used to ensure this.

11. Risks and Technical Debts

11.1. Risks

Risk Explication

GitHub

Despite having already worked on several subjects with this tool, there is still a part of ignorance that can lead to conflict resolutions.

React

For many of the development team it will be their first time working with it. So we will have to spend time learning the basics concepts.

SOLID

This is the first project where we have to introduce SOLID principles. So it will take time to get a good grasp of the technique.

MongoDB

Until now we have always used other types of database management systems. MongoDB is a new challenge that the team will face. In this case, having used databases in many other subjects, the learning time may be less

Security

Keeping customer information secure is a vitally important activity. For this, we must find out how to make a security and authentication system as effective as possible.

Team

Working in teams with a certain number of people is never a simple task. The best solution is to hold weekly meetings to get to know each other and have constant communication to solve any problem that arises together.

Pod´s

During the project, mastery of this technology led to different problems that were resolved

URL Api test

Despite trying to use the .env file to make the connection to the database, we had to hardcode it

Deployment

The deployment of the application has been a problem. At first we had chosen heroku, then we try on AWS but didn´t work and finally we did it in heroku.

11.2. Tecnical Debts

Problem Explication

Double order creation

When an order is created from the application, an extra order is generated for each payment. After reviewing the project we have not found the error

Test e2e

During the test we have not been to fill the form. The solution we have taken has been to carry out the tests even if they fail

Menu nav

When you start using the pods in the application, the application’s nav menu changes color

Hardcoding

The compatibility between the URLs of the connections in the .env file and the deployment has given problems. The solution taken has been to hardcode and use the NOSONAR comment

12. Glossary

Term Definition

SOLID

Solid is a specification that allows people to securely store their data in data stores called Pods.

Pod

Personal containers to store data used by solid

MongoDB

NoSQL-type database management system to be used during the creation of the web page

React

It is a JavaScript library that helps you create interactive user interfaces. It allows to create views and generate components easily and simply

mongoose

Mongoose is a Node.js library that allows us to write queries against a MongooDB database, with features like validations

Schema

A schema in Mongoose is a JSON structure that contains information about the properties of a document. It may also contain information about validation and default values, and whether a particular property is required.

Release or tag

A tag allows you to specify uncommit in git and store the current state of the project in .tar format.

Node

Node is an environment that allows you to establish different connections at the same time. Its use is based on events.

Jest

It is a library that allows you to run tests quickly and efficiently.

Crypto

Crytpo is a module that allows passwords to be encrypted when saving them in a database. This increases the security of the application. We use sha-256.

Uuid

Node module that automatically creates id combinations so they are unique.

Heroku

Heroku is a cloud storage platform specialized in react projects. It is a high quality option in terms of safety and maintenance.

AWS

Cloud storage service specialized in shared resources, mobile applications or databases. It is a globalized option that offers guarantees in terms of security, accessibility, visibility and cost.

Dotenv

It is an external tool to handle environment variables. In this way, in the project there is an .env file in which the connection urls are stored

Draw.io

It´s the tool we use to create the domain model

PlantUML

Open source tool with which we create sequence diagrams textually

Mapbox API

API that we use in our code to calculate the distances to the clients

Arc42

Arc 42 is a perfect documentation template for a project specification

MERN

It is the name given to the use of a series of technologies: MongoDB, ReactJS, Express and Node

Mui

It is a library that provides you with all the necessary tools to carry out the design and development of your application

Toast

Informational message that appears on the screen for a few seconds without requiring acceptance

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.