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

We are going to develop dede, wich is an online sales system.

Dede will respect the customers privacy following Solid principles, so the system will not store customers personal information but it will get the information with the pods as long as customers give necessary permissions.

The theme of the online shop will be related to Asturias, so that the products sold will be typical of the region.

1.1. Functional requirements

  • The project will follow the SOLID principles.

  • The customer will be able to see a list of all products.

  • The customer can choose the point of delivery of the products.

  • The system will calculate the shipping costs.

  • The customer will be able to see his orders placed.

  • The customer can filter the products by type.

  • The customer will have at his disposal a help window with frequently asked questions.

  • The system will pick up the address of solid.

  • The system will automatically log in if there is an inrupt.net account logged into the browser.

  • The administrator can disable products.

  • The administrator can add products.

  • The administrator will be able to see a list of all users.

  • The administrator will be able to view a customer’s orders.

1.2. Quality Goals

Goal Detail

Privacity

The customer will have all his data protected.

Testability

The application must be able to pass several tests.

Usability

The application should be easy for customers to learn how to use.

Maintainability

The application will be able to accept changes easily.

1.3. Stakeholders

Role/Nombre Expectations

Customers

Interested in buying products on the application.

Administrators

They are in charge of managing the application to make sure that everything works properly.

Teachers

They help in the realization of the project and are interested in its outcome.

Other students

They recommend for the improvement of the application and get inspiration for their own applications.

2. Architecture Constraints

2.1. Technical Constraints

Constraint Motivation

TC1

Implementation in TypeScript

The application must be implemented using TypeScript

TC2

Framework React

The application must be implemented using the framework React

2.2. Organizational Constraints

Constraint Motivation

OC1

Team

Lucía García Sopeña, Sergio Salgueiro Monforte, Héctor Lavandeira Fernández, Juan Domínguez Álvarez and María González Otero

OC2

Time schedule

The application will be developed during the second semester of course 2021/22

OC3

Version management

Private git repository with a commit and pull request history

OC4

Deliveries

There will be 4 deliveries, one every three weeks, starting February 22, 2022

OC5

Team meetings

The development team will hold at least one weekly meeting

OC6

Meeting minutes

The team must take minutes in every meeting

2.3. Conventions

Convention Motivation

C1

SOLID

The application must follow the SOLID principles in order to respect customer privacy

C2

Architecture documentation

Documentation structure must follow arc42 template

C3

GitHub Pages

The documentation will be deployed through GitHub Pages

3. System Scope and Context

3.1. Business Context

The application we are going to develop will consist on an online shop of products from our province , SOLID will be integrated on the shop , providing a more secure way of storing personal information to the client.Also we will use a data base which will contain every information that the shop needs.

3.2. Business Context diagram

Fallo imagen

3.3. Business Context table

Entities Inputs Outputs

User of the app

Services from the shop

Tries to access to the shop.

Shop

Return information requested/Information from database/Access request from user.

Data request/Personal Information request from the POD/Servuces requested by user

POD

User personal info/Personal info requests from the app

Personal info requested by the app

OpenStreetMap

The string of the user address

An address from the user data

Database

Data request by the shop

Data requested

3.4. Technical Context

3.4.1. Technical Context diagram

Fallo imagen

3.4.2. Technical Context table

Elements Functionality

Device

The computer who will search for things to buy on the shop.

Online shop

Web app that will provide the services

POD

Will store every user personal information

SOLID

Provides pod used by the app

4. Solution Strategy

4.1. Technologies

React

React is an open source Javascript library designed to create user interfaces with the goal of facilitating the development of single page applications.

Solid

Solid is a specification that lets people store their data securely in decentralized data stores called Pods. Pods are like secure personal web servers for data. When data is stored in someone’s Pod, they control which people and applications can Access it.

MongoDB

MongoDB is an open source, document-oriented, NoSQL database system. MongoDB stores BSON (a specification similar to JSON) data structures with a dynamic schema, making data integration in certain applications easier and faster.

4.2. Key Quality Goals

Privacy

The program must protect the privacy of clients following the SOLID principles. For this, the system will not store personal information of the clients, but will obtain said information from the users' pods as long as the users give the necessary permissions to the sales system.

Software quality

We must develop quality software. An organized structure of packages is important in order to speed up access to the code we are looking for. We also use design and architectural patterns. To correctly understand the project, good documentation must be prepared that explains the functionalities of the system, as well as the use of comments.

Usability

The main purpose of this app is to provide an application that could be used by everyone easily in an intuitive way so every person that wants to buy us some product can solve it with no problem.

4.3. Organizational Decisions

Lenguage

The documentation will be in English for internationalization purposes. The work will be broken down into smaller tasks, which will be assigned to a member or a group. Most of the time, these tasks will be represented as issues on Github, and we assign them in group meetings.

Discord

Regular meetings will be organized. In these meetings all team members will discuss important development topics, such as important design/architectural decisions or the way of organizing a set of functionalities to be implemented, a change in documentation.

These meetings will be in the weekly laboratory classes or telematically on the discord platform, because it allows to make calls from several users at the same time.

5. Building Block View

The general system is represented in a white box and composed of different elements such as the black box and building blocks.

5.1. Scope and context

Fallo imagen

The user interacts with his own Pod over which he has control and ownership of his data, the user performs operations such as creating it or modifying the permissions to his data. It also interacts with the Dede application, which is represented as a black box in this diagram. On the other hand, Dede interacts with the Pod in order to access the files that are in it, being able to save and load data.

5.2. Level 2

Fallo imagen

It seeks to intercommunicate the user interface (Front End), the business logic (Back End) and the session management system. The Front End needs the services of the Back End layer so that it sends data and results of actions to it so that it can display them to the user. On the other hand, the Front End interacts with the authentication system so that the user can log in with their WebID or through a provider. The Front End is also related to the session management system, in order to access the POD data of the user who is currently in session.

5.3. Level 3

Fallo imagen

The third level is divided into the Front End in the main views of login, admin, shoping and the request manager. The credentials entered in the LoginView will be verified by the LoginManager that is responsible for accessing the user’s pod and allowing access to the application. On the other hand, the user Will be able to see the shopping view that interacts with the products manager of the backend for visualice the products options. After the loggin the administrator Will be able to see the admin view that obteins info fron the order manager, products manager and the users manager due to the admin can acces to all this data. Finally, in the database the users ids are saved and all the data related to the order of a user and the products aviables in the shop.

6. Runtime View

6.1. See user orders

Fallo imagen

6.2. Some admin utilities

Fallo imagen

6.3. Search by category

Fallo imagen

6.4. Buying product

Fallo imagen

6.5. See product details

Fallo imagen

7. Deployment View

7.1. Infraestructure

Fallo imagen

7.1.1. Motivation

The application will be deployed on the heroku host platform, will store all data with the mongodb database manager and will communicate with all users through the Solid pods.

The main objective of the application is that the users who use it feel safe and comfortable using it, respecting above all security and privacy on the internet.

7.1.2. Building block mapping for infrastructure

The infrastructure consists of the following components:

Node Description

DataBase

Database manager, in our case mongodb, which we are going to use to make all our queries.

Device

Software that we are going to use to display the shop interface, i.e. any browser, preferably a computer browser as it is not perfectly optimised for mobile phones.

Solid

Place where user data will be stored respecting the privacy and security of the users, using pods to store the information of each user.

Web server

Host service that allows us to deploy both the restapi application and the webapp, the service we used was Heroku.

8. Cross-cutting Concepts

8.1. Persistence

We focused on developing an app that uses MERN (MongoDb,Express,React,Node) so we use mongoDb as a container for our data , pods for user personal data and we will use a extern repository for images.

8.2. Internationalization

Even though we decided to do the documentation part in english , we also decided that our app would be in spanish, just to make us easier to focus on the development part.

8.3. Test

For this part we will be doing three types of test , unitary ones , which will test only little funcionalities without external dependences , end to end to prove full developed functions of the app , and finally load test to see if the app stops if the amount of users is high.

8.4. Domain diagram

Fallo imagen

8.5. Domain table

Entities Description

User of the app

Tries to access to the shop , see all products and buy.

Products

The variety of things that you can buy on this shop

Orders

The list of products that a user has bought

9. Design Decisions

Decission Description Pros Cons Status

Language

The documentation will be in English

Internationalization

More complex wording

Accepted

Theme

The shop’s theme will be products from Asturias

Accepted

HSQLDB

An HSQLDB Database will be used

Portability of the database

It is a local database

Rejected

MongoDB

A MongoDB Database will be used

High speed, availability, simplicity, flexibility

High memory usage and limited data size

Accepted

MUI

React UI Library to implement the frontend

Improves the web’s design

Some elements can be more complex

Accepted

Heroku

It will be the deployment platform

There is more documentation

Unknown by the team members

Accepted

cloudinary

Repository to keep the web’s images

It won’t be necessary to keep the images locally

Accepted

10. Quality Requirements

10.1. Quality Tree

Fallo imagen

10.2. Evaluation scenarios

Testability/Coverage

For this part we will use many tools that allow us to test a 70% at least of our app , also we will do some gatling test in order to test how many requests can the app resist till it breaks .

Testability/Independet from external sevices

The architecture should be designed in such a way that algorithms depending on external services can be tested without having the external service available. That is: All external dependencies should be mockable.

Usability

The application will be designed in such a way that anyone who can access it will be able to navigate as comfortably as possible.

Confindenciality

Clients privacy is respected by using a descentralized delivery following SOLID , in which the user will have a POD where his personal data will be stored so if the app closes the user will still keep his personal information on the POD.

AQ Priority

Testability

Low,High.

Usability

High,Medium

Confidentiality

High,High

11. Risks and Technical Debts

11.1. Possible risks

When implementing the application, risks may arise such as:

Risk Explanation Solution

Working in a group

We are not used to working in groups with so many people and on such large projects

Increase communication and keep track of each other’s tasks so as not to lose each other

Github

We have a very small github base

Learning how all github operations work

Time management

We cannot devote all available time to the project

Try to be organised and communicate in case of time constraints

New technologies

There are new technologies like Solid or React that we have never used before

Learn the basics of them and help each other to improve learning.

11.2. Technical Debts

As technical debts we consider that may arise:

Technical debt Explanation Solution

Low cohesion

When doing individual work there may be a lack of communication and not being able to connect the work.

Try to make the implementation as joint as possible to avoid these problems

Robustness

As we have little experience in some technologies, we could get an application with errors in some options

More extensive testing

Conflicts in github

Sometimes when merging everything together, a series of conflicts can arise that are difficult to resolve

Make good use of the functions provided by github and organise yourself well to prevent them.

12. Glossary

Contents

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

You can also see the glossary as source for translations if you work in multi-language teams.

Motivation

You should clearly define your terms, so that all stakeholders

  • have an identical understanding of these terms

  • do not use synonyms and homonyms

Form

A table with columns <Term> and <Definition>.

Potentially more columns in case you need translations.

Term Definition

Git

is a version control software designed by Linus Torvalds, thinking about the efficiency, reliability and compatibility of application version maintenance when they have a large number of source code files.

JavaScript

JavaScript is an interpreted programming language, dialect of the ECMAScript standard. It is defined as object-oriented, prototype-based, imperative, weakly typed, and dynamic.

TypeScript

TypeScript is a free and open source programming language developed and maintained by Microsoft.

MongoDB

MongoDB (huge, "huge") is an open source, document-oriented, NoSQL database system.

POD

POD means personal online data , it is an online container capable of storing personal information. TypeScript is a free and open source programming language developed and maintained by Microsoft.

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.

Node

Node.js is an open source, cross-platform runtime environment for the server layer (but not limited to) based on the JavaScript programming language, asynchronous, with data I/O in an event-driven architecture and based on Google’s V8 engine.

React

React (also called React.js or ReactJS) is an open source Javascript library designed to create user interfaces with the goal of facilitating the development of single-page applications. It is maintained by Facebook and the free software community. In the project there are more than a thousand free developers.

Dotenv

It is a dependency that allows us to maintain a file where we will leave information that the rest of the people should not access (example: database code).

Heroku

Heroku is a platform as a service (PaaS) that enables developers to build, run, and operate applications entirely in the cloud.

Tokens JSON

JSON Web Token (JWT) is a compact URL-safe means of representing claims to be transferred between two parties.

MUI react

MUI provides a simple, customizable, and accessible library of React components.

Unit test

A unit test is a way of testing a unit the smallest piece of code that can be logically isolated in a system.

Mongoose

Mongoose is an ODM (Object Document Mapping) - it acts as an interface to MongoDB by letting you define Models.

Docker

Docker is an open source containerization platform. It enables developers to package applications into containers—standardized executable components combining application source code with the operating system (OS) libraries and dependencies required to run that code in any environment.

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.