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 (Descentralized Delivery) is an e-Commerce application (online retail system) in which users will be able to select and order products.

DeDesktop is the name of the application. It is an online technology store in which it is sold products such as personal computers, laptops, peripherals, etc.

It follows SOLID principles, guaranteeing the client’s privacy regarding the personal data of the client such as the address.

1.1. Requirements Overview

Requirements document:

English: https://arquisoft.github.io/course2122/labAssignmentDescription.html

Spanish: https://arquisoft.github.io/course2122/labEnunciadoPractica.html

  • The system will emulate an online shopping system where end-users can select and order products to buy.

  • Once a user selects the products to buy, the system will calculate the delivery costs by looking up the desired address of the end-users in their pods and calculating the costs according to the distance from the distribution center to that address.

  • The system will show the final costs of the products to buy and once the user decides to buy them, it will record the event simulating that the sale has been done and it can proceed with the delivery.

  • The system will allow the users to visualize the orders done.

  • The application should be accessible and deployed using a continuous integration system.

  • Allow a user to have more than one shipping address in their pods (e.g. Home, work, Gym, School etc.).

  • Add the possibility to include estimation of time people are at a location (e.g. Monday-Thursday work 09.00-18.00) and restrict some of the addresses to be used for delivery at some point in time.

  • Add pick-up locations that the delivery services can use. Based on the delivery address the pick-up location could be calculated (this can either be by one of the addresses in the profile or a pick-up location that’s on the route of the receiver (e.g. between home and work).

  • In order to calculate the delivery costs, external APIs from different carriers could be used and selected, so the users can compare and select the carrier.

  • The system can allow some users with administrative roles to visualize statistics about products ordered and monitor the state of orders.

  • Implement both a web application and a mobile application.

  • Implement an emulator of the delivery system which can notify the users when the products have arrived and keep track of the deliveries.

  • Support for different types of actors like customers, managers, administrators, etc. who can do different actions like inventory management, prices changes, items cataloging, etc.

  • Add the possibility that there are several distribution centers or warehouses where the products are stored.

  • Add the possibility that the users can add or update their address information to their pods directly from the app.

  • Add ratings and reviews to products or distribution centers so the users can provide feedback about their experience.

1.2. Quality Goals

Priority Quality Goal Motivation

1

Privacy

The treatment of private information will be decentralized, ensuring customer privacy

2

Usability

All users must be able to use it, whether they have previous knowledge about the application or not

3

Integrity

Data must be consistent and complete at all times

4

Efficiency

Making a purchase should be easy for the user, reducing response and load times

5

Testability

Major components should be easily tested and fixed

6

Modifiability

The architecture must be easy to modify, adding new features or changing existing ones

Detailed priority in epigraph 10.

1.3. Stakeholders

Role/Name Contact Expectations

Client

They interact directly with the application. They select the products to purchase and view their order history.

The aim is for the customer to be able to interact with the application intuitively and have a comfortable shopping experience. In addition, their privacy is respected in accordance with the SOLID principles.

Administrator

They are in charge of modifying prices, calculating inventories, seeing all orders placed or placing orders with suppliers.

Administrators will be able to access their exclusive functions through a simple login.

Development Team

They are the creators of the application. They can modify, update and improve it.

Develop a complete application that contain the requirements. Learn to work in a team efficiently and learn new technologies.

Delivery business

Dstribute the products to the client’s address

Their objective is to get the list of the products to deliver and the address of the client who ordered.

1.4. Implemented features

  • The system will emulate an online shopping system where end-users can select and order products to buy.

  • Once a user selects the products to buy, the system will calculate the delivery costs by looking up the desired address of the end-users in their pods and calculating the costs according to the distance from the distribution center to that address.

  • The system will show the final costs of the products to buy and once the user decides to buy them, it will record the event simulating that the sale has been done and it can proceed with the delivery.

  • The system will allow the users to visualize the orders done.

  • The application should be accessible and deployed using a continuous integration system.

  • Support for different types of actors like customers, managers, administrators, etc. who can do different actions like inventory management, prices changes, items cataloging, etc.

  • Add the possibility that there are several distribution centers or warehouses where the products are stored.

  • Internationalization

  • Name, price and category filters

  • Microservices: use of 4 principal docker containers: webapp, restapi, mongodb (database), python (data)

  • Use of 3 extra docker container for data bases: local, test e2e and unit test apart from the normal mongodb docker for deployment

  • Unit tests

  • Load tests

  • Continuous integration (CI)

  • Hexagonal architecture

2. Architecture Constraints

2.1. Technical constraints

Constraint

Explanation

React

We will use the React Framework for the UI (User Interface). This ir a requirement

SOLID

With SOLID, we’ll be able to let people be propietary of their own intformation using PODs. This way, they can allow or reject the application to access the data or not. This is a requirement

Docker

The application will be running in a Docker Host

GitHub

We will use GitHub to deploy the project and all the files related with it. This is a requirement

TypeScrypt

TypeScript is the techonology used for the backend. Based on JavaScript is quite similar. This is a requirement

Node.js

Based on JavaScript, is a backend technology wich allows us to execute our code

2.2. Organizational and political constraints

Constraint

Explanation

Team and meetings

This is a course application. Development team consist in 5 (five) people with a very limited experience in techonolgies used in the project. Is our first time working together, so some organizational decisions could be not as agile or accurate as they could. Also we don’t have the same class schedule so find a room for a meeting could be difficult sometimes

Time

The project has a very tight time to be finished. This means that our application will not be as developed as it could be

Deadlines

This application is part of course calification criteria. This means we have several deadlines and important releases in a target date. This means we can have trouble finishing the parts we need to release in some of that targets.

2.3. Conventions

Constraint

Explanation

Aesthetic and ease of use

The UI (User Interface) has to be aesthetic and easy to use. Both of them are very important criteria in our application, so all of our decisions need to have this in mind

Documentation

We will use Arc42 template to develop documentation

Solid

The application must follow Solid conventions

TypeScript

We will use TypeScript/JavaScript naming conventions

Redux

We will use Redux style guide (based on REACT) conventions

MVC

We will follow MVC conventions in naming and layer separation

W3C AAA

Our application will follow AAA conventions. This allow us to make the aplication more usable to everybody

3. System Scope and Context

3.1. Business Context

Business Context diagram

Entity Input Output

User

The user will interact with the application through a computer or other device. The user will see the frontend of the application and send requests to the backend

The output is represented in many parts of the system, reaching almost every point in the system

User Pod

It creates new PODs for users who have not created them, can update the information contained in them, and also handles requests made to it by providing the requested information

Submit the information requested by the application

DeDesktop System

It is the system with which the user interacts, it receives the requests sent by the user through the interface

It processes incoming requests and manages the database so that it is consistent with incoming requests. Once it has the requested information, it shows it to the user via the interface

Database (MongoDB)

Queries, information requests

Storaged and consistent data responding to the system needs

3.2. Technical Context

Our application is divided in frontend(webapp), backend (restapi), testing (e2e and test) fields. In backend, we use an hexagonal architecture improving security and the website performance. The system is made with the microservices idea in mind, using docker containers to contain the FrontEnd, backend and the databases used in both project and testing. We also used SOLID PODs in the Inrupt provider to give a descentralized experience in props of getting the user address. We connect to the public user’s VCARD storaged in it’s POD so we, in our databases, have no personal information aside the email. Now, in frontend, we used the framework React accompanied by bootstrap and MUI components, bootswatch styles, SweetAlert2 alerts and carousel library to make an interactive HomePage.

Technical Context diagram

Technology Explication

MongoDB

We use it to store the location of the SOLID POD. In our architecture, we have two databases, one is used for testing, and the other one is used in the website as main database. Both of them are contained in dockers to get closer to the microservices concept and improve the website performances.

React

Is a technical constraint. We use it to develop the website in frontend

TypeScript

Is the programming language used for the development. It is also a technical constraint

Grafana and Prometeus

They are services used for monitoring our system and verifiying the petitions made in our charge tests.

Postman

It is used for testing the backend functionlity due to it’s popularity and previous tips given by older students

Docker

I’ts one of our main ideas. We use Docker to divide the application in multiple services (containers) based in the microservices idea. We have a container for each service (Grafana, Prometheus, Main database, test database, webapp, and mongo)

Amazon Web Services

Is the platform used for the system deployment. Chosen because after trying to deploy our app in another services like Heroku (we had problems because of our Docker architecture. The free version only allows to deply one container and we had 2) and Azure we couldn’t get a proper result so we decided to try with this one

CSS

CSS is a language to set styles and positions of our components in the application. We used it because of our familiarity with it.

In the project, we use the following libraries, APIs and dependencies

Used Libraries Explication

MUI

Library used because of its predefined components that makes the developing process a lot easier and efficient. Some of tihs kind of components can be really helpful when developing some specific things

Bootstrap

Same as MUI, but this components can be a little less limited in functionalities than the MUI ones. We use them basically because they are more easily customizable and they are compatible with bootswatch.

Bootswatch

Bootswatch gives our app a harmonized style, giving us some things such as a background and styling on the bootstrap components.

SweetAlert2

It’s a dependence that gives the possibility of launching dialogs, modals and alerts in an easy way. Plus, this alerts are animated and give dynamism to the user experience.

Distance Matrix API

This is a Google Maps API used in backend to get the distance between two different points in the world. It’s simple, efficient and quick.

react-material-ui-carousel

Used in fontend to give dynamism to the homepage. It’s very customizable and easy to use and it gives a little information about the website before entering the catalog or the website technology

Cloudinary

Used in Backend to storage the product images in props to save space and increment the website performance. It also makes it easier for the Admin at the moment of adding products so the system does not have to download the photo

4. Solution Strategy

4.1. Technology decisions

The technologies we have decided to use for the development of the app are:

  • React: React is an open source library, which makes it easy for us to program user interfaces. React is responsible for rendering and updating the components of our interfaces in the best way.

  • Node.js: It was created to be used in JavaScript, specialising in the use of asynchronous events. Thanks to Node.js, the use of these events is much easier. This technology is more focused on the management and creation of scalable network applications.

  • SOLID: SOLID provides the user with the peace of mind of knowing that their data is safe and decentralized. As well as giving them the ability to provide their data to other entities very quickly and easily.

  • TypeScript: TypeScript is a superset of JavaScript, meaning that it contains all of the functionality of JavaScript and then some.

  • GitHub: It is a version management system.

  • MongoDB: MongoDB is open source software, which is a NoSQL document database, we use NoSQL as it gives us the ability to work with many different data without spending so much time modeling these elements.

  • AWS: AWS is a cloud server which we will use to deploy our App. AWS makes it easy to deploy and scale Node.js applications. Run any recent version of Node.js. Deploy apps in seconds using dependency caching.

  • Docker: We will use it to launch the application in a container of the technologies we need to carry out the DeDe.

  • Express: Express is Node’s most popular web framework, providing basic mechanisms for Node.

  • Bootstrap: Bootstrap is a style library, which we will use for the frontend.

  • Prometheus: Prometheus is open source software, which gives us the ability to monitor our system through a wide range of available tools. This data is stored together with a time instance, with which we manage to have a fairly accurate record of the events that occur in our system.

  • Grafana: Grafana is an open source software which allows us to analyze, consult, visualize, alert and explore the metrics, records and monitoring of our system. With this data we can make interesting graphs and visualizations.

  • Postman: Postman is an open source software which offers us the necessary help to build, use and test APIs, making the steps easier.

  • Jest: Jest is a delightful JavaScript Testing Framework with a focus on simplicity.

  • Cloudinary: It is an API used to store images, we will save the URL of the images.

4.2. Decisions about the top-level decomposition of the system

  • On the frontend we are going to use the Redux pattern. This pattern was created initially to be used in React, so it optimizes the loading of components since it only reloads the modified components, it will also help us in passing information between components by storing the state of each component in an easily accessible way.

  • In the backend part we are going to use the MVC pattern (model, view, controller) this pattern is one of the most used for this part of the application. The pattern will be used without the view part as this part would be the WebApp.

4.3. Decisions to achieve quality goals

To try to achieve all the proposed quality objectives, we will strive to obtain very good accessibility with a help system for people who need it. We will also focus on making an accessible and adaptable website following the AAA level. To improve the privacy of the users we will use SOLID POD, which decentralizes the personal information of each user. We will store only the location of this data, managing to improve security since we do not have sensitive data of the users.

4.4. Organizational decisions

We will try to hold weekly meetings via Teams, in addition to the meeting classes of the subject, for minor doubts and fluid communication we use WhatsApp. We also communicate via GitHub through the Issues, we determine the work of each member and update these tasks in a Kanban board with the already mentioned Issues.

5. Building Block View

5.1. Whitebox Overall System

Building block view - Whitebox Overall System

We have two types of actors interacting with the application:

  • User: Is the owner of his POD. He interacts with the system through user view (this view will be explained in level 2).

  • Administrator: He interacts with the system via admin view (this view will be explained in level 2).

The application is represented as a whitebox. Inside of it we can see the three layers of MVC (Model View Controller) convention.

5.2. Black Box descriptions of Overall System

Name

Responsability

Model

Store data and get data from data base. Defines business model. Gives information to View layer to represent it on the device

View

Receives data from Model layer to represent it on the device. Is the layer wich interacts with actors (users and administrator)

Controller

Receives inputs and manage the interactions between View layer and Model layer

5.3. Building block view - Level 2

Building block view - Level 2

6. Runtime View

6.1. Register User

RegisterUser

This runtime view shows the process of registering a user, going through WebApp and ApiRest to database, storing the data in the database.

6.2. Login User DataBase

LoginUserDataBase

This runtime view shows the login process of a user, going through WebApp and ApiRest to the DataBase, via the location stored in the database.

6.3. Login User POD

LoginUserPOD

This runtime view shows the login process of a user, going through WebApp and ApiRest to the user POD.

6.4. Visualize orders done

VisualizeOrdersDone

The user presses a button to visualize their previous orders, the WebApp send the petition to the RestApi. The RestApi asks for the client’s orders from the user pod. User pod returns the client’s orders to the RestApi, and the RestApi sends them to the WebApp. The WebApp show a list of client orders.

6.5. Delete a product from the shopping chart

DeleteProductFromTheShoppingCart

The user chooses the product and presses the button to delete it. The WebApp send this petition to the RestApi. The RestApi send the petition to delete a product to the POD, and the POD to the DataBase. Once the product is deleted from the DataBase, success is returned to the client.

6.6. Add products to the shopping cart

AddProductsToTheShoppingCart

The user, identified as a client, selects the cattegory of the product of its choice and the DeDe app returns the filtered products to them. Then, the user can scroll through de app looking for the returned products and press the button "Add to Cart" to add them into the shopping cart and pay for them whenever they want.

6.7. Paying process

PayingProcess

The user presses the pay button on their shopping cart and the DeDe app takes them to the paying page where they can see the total price to pay in addition to the shipping price previously calculated by the DeDe application after asking the user’s pod for their address and calculating the distance from that address to the distribution center. After seeing the final price, the client must press the pay button so the DeDe app registers the order on the database and returns the confirmation

6.8. (Admin) Show users

AdminShowUsers

6.9. (Admin) Add Item

AdminAddItem

6.10. (Admin) Monitor Order Status

AdminMonitorOrderStatus

7. Deployment View

7.1. Infrastructure Level 1

  • Motivation: This diagram helps us to point out the different components that we will have to use and their dependencies. It helps us to visualise the deployment path for the system to work.

  • Quality and/or Performance Features: To improve the quality of our system we have used the best technologies at our disposal, trying to minimise waiting times for user requests. It helps us to use MongoDB, as it is a very efficient DB.

  • Mapping of Building Blocks to Infrastructure: Deployment View Level 1

7.2. Infrastructure Level 2

  • Motivation: This second diagram details the launching of the layers that we have to do ourselves, see WebApp and RestApi.

  • Quality and/or Performance Features: As we can see in the following image, we are going to use AWS to deploy the application, serving as a remote server. We will also use Docker to launch each part of the system.

  • Mapping of Building Blocks to Infrastructure: Deployment View Level 2

8. Concepts

8.1. Domain model

Name Description

Client

User who choose and buy products.

POD

User’s information.

Order

Keep a list of the products that the customer has ordered.

Product

Contains information about a product, such as name and price.

ProductInOrder

Product associated with an order, saves the quantity that the customer wants of the product.

DistributionCenter

Place from where the products are distributed, contains the address of the distribution center.

ProductStore

Entity which join Product with Distribution Center. It has the stock.

Domain Model - UML Diagram

8.2. Persistence

At the beginning there was a debate about whether it was better to use SQL or NoSQL for persistence. After some discussion it was concluded that the best option for this problem is NoSQL. To be more specific MongoDB, which is a NoSQL document database. We will use a NoSQL database as opposed to a SQL database, because our model encompasses many products. These products have several attributes which are very different. For example, a power supply differs in many ways from a graphics card. Because there are so many items, we believe it is best to use a NoSQL DB. But, because of our hexagonal architecture, we can switch from NoSQL to SQL without needing to modify the code, or switch from MongoDB to Cassandra, the change doesn’t matter because the backend is not related to the persistence used

8.3. User interface

DeDe user interface is desinged to give every user an intuitive and familiar experience related using the React framework combined with TypeScript as constraints. We follow the usual standards of e-commerce online sites to make the navigation closer to what most of the people already know. Also, the interface is meant to pass the AAA validation so we make sure it’s usable for almost everyone. In terms of dependencies, we worked with MUI for some of the components (buttons, tables…​), bootstrap alongside with bootswatch to give the app a defined style and use some of it’s components, and, sweetalert2 to throw modal windows at some points of the application.

Prototype version of DeDesktop:

Catalog initial prototype

Other Windows initial prototype

Middle Version of DeDesktop

Login

Catalogo

Final Version of DeDesktop

Login

Catalogo

8.4. Internazionalization

The application will potentially deal with various locations and people, so make a multi-language application looks like the best decision. This decision must be done since the begining of the desing (lately will cost a lot of resources).

This allows us to reach a bigger audience and make the application more accesible.

8.5. Security

For security we have used an asynchronous encryption algorithm called PBKDF2, which is one of the most famous KDF encryption algorithms. The user will put a password in plain text, which will be encrypted using a Hash function, a salt will be added to it, which is a random number added at the beginning of the password, all this string will be saved in the database, achieving a very high level of security. We have a role system, which defines if a user is an Administrator or a normal User, and depending on that he will have one or other options enabled, such as a CRUD of products or users, to avoid a scale of privileges we have made it impossible to be Admin, it always inserts users as User and we have a couple of Administrators created by default.

8.6. Additional libraries

Dependencies in the backend:

Dependencies in FrontEnd

  • @emotion/react: ^11.7.1,

  • @emotion/styled: ^11.6.0

  • @inrupt/lit-generated-vocab-common: ^0.3.11

  • @inrupt/solid-client": ^1.19.0

  • @inrupt/solid-client-authn-browser: ^1.11.6

  • @inrupt/solid-ui-react: ^2.7.0

  • @inrupt/vocab-common-rdf": ^1.0.3

  • @material-ui/icons: ^4.11.2

  • @material-ui/lab: ^4.0.0-alpha.58

  • "@material-ui/styles: ^4.11.4

  • @mui/core: ^5.0.0-alpha.54

  • @mui/icons-material: ^5.2.5

  • @mui/material: ^5.2.5

  • @testing-library/jest-dom: ^5.16.1

  • @testing-library/react: ^12.1.2

  • @testing-library/user-event: ^13.5.0,

  • @types/node": ^16.11.14,

  • @types/react": ^17.0.37,

  • @types/react-dom: ^17.0.11,

  • bootstrap: ^5.1.3,

  • bootswatch: ^5.1.3,

  • cors: ^2.8.5,

  • jsonwebtoken: ^8.5.1,

  • node-sass: ^7.0.1,

  • react: ^17.0.2,

  • react-bootstrap: ^2.2.0,

  • react-dom: ^17.0.2

  • react-material-ui-carousel: ^3.3.3

  • react-router: ^6.2.2,

  • react-router-dom: ^6.2.2

  • sass: ^1.50.1,

  • serve": ^13.0.2,

  • sweetalert2: ^11.4.8,

  • typescript: ^4.5.4

  • web-vitals: ^2.1.2

8.7. Archiutecture and design patterns

8.7.1. Hexagonal architecture

We are using hexagonal architecture in our app. We took this decision because it presents several advantadges.

The hexagonal architecture is an architectural pattern used in software design. It divides a system into different layers or regions with their own responsibility. In this way, it manages to decouple layers of our application, allowing them to evolve in isolation. In addition, having the system separated by responsibilities will facilitate reuse. The components are loosely-coupled and interchangeable, such as the application core, the database, the user interface, test scripts and interfaces with other systems.

Hexagonal architecture is an alternative to traditional layered architecture.

Hexagonal

8.7.2. Microservices

In our application we decided to use microservices to divide the application into webapp, restapi, database and data. With this we achieve a low coupling in these layers, a better control over them and an improvement in the quality of the software. To achieve this decoupling, we use docker, to build the images of each service.

8.8. Code Quality standards

Code quality standars allows us to make an understable, maintainable and reusable code for future revisions and changes. Code should always have a correct structure to be easily understandable.

To achieve this we will use all tools programs give us and make correct decisions like design patters, use convention naming and try to reduce technical debt.

8.9. Testability

Applications should be strongly tested. We use user stories to make acceptance tests and unit test to test the rest of the application components and states during running process. We think this is the best way to be sure the project works correctly.

8.9.1. Postman

To test our code, Postman was used in the backend during the whole development of the work, to check if the requests were being carried out correctly. Postman is an application in which we can test requests and obtain a successfully respond if everything is ok.

8.9.2. Unit tests

Later, once we had a more or less solid project, we added a series of unit tests, which use Jest technology, these tests try to include all the backend and frontend parts, but separately, without joining them.

8.9.3. Integration tests

Once unit tests passed successfully, integration tests were implemented, which test the union of frontend and backend, all these tests were done exhaustively and were performed by people who had not done that part of the code, with that we get that we do not test things that are known to work.

8.9.4. Load tests

We have load tests to check our application under real-life load conditions, it gives us an idea of the respond time having a determined users load.

Get products (catalog)

3 users in 15 seconds Load test - Catalog 1 15 users in 30 seconds Load test - Catalog 2

Login

15 users in 60 seconds Load test - Login 1 5000 users in 60 seconds. We can check that 5000 users in 1 minute is too much and some petitions fail. Most of the responds are slower but don’t fail. Load test - Login 2

Get users list

This load test implicates a login as admin before listing users. Load test - Get users 1

9. Design Decisions

Decision

Details

Advantages

Disadvantages

Internazionalization

We will develop the documentation in english and the application in english and spanish

With this internazionalization we improve accesibility a lot

Time can be a factor to consider and make two language internazionalization can use a lot of time

Design architecture

We will use MVC as architectural pattern for backend and Redux for frontend

With MVC we have better usability and a very organized and understable code. Redux helps us with data synchrony

MVC: We need to structure the code perfectly to comply with the convention. Redux: We never used it. Instead we decided to use React Hooks like CreateContext or UseContext

Frameworks

We used the React Hooks and functionalities in frontend, taking advantage of it’s utilities because it is intuitive

We can use it to facilitate the implementation

Is a new technology to us so we need to improve our knowledge about it

Data Base

We choosed MongoDB to store all the information

MongoDB allows us to make an easier implementation

Is a new technology to us so we need to improbe our kownledge about it

Save images

We have decided to store all images related to the product catalogue in an external API called Cloudiary

With this we manage to decentralise the images of the project, the favourable implications are many, from increasing security, such as lightening the weight of the project by not having to save the images, also highlighting the ease of displaying them as it works through a URL saved in the product

The disadvantages are having to configure the entire API, the fact that the products have to save a URL increases its complexity, we depend on this external API for the correct functioning of the application

Hexagonal architecture

At the beginning of the project we decided that the backend would be governed by a hexagonal architecture, this is due to the recommendation given by Professor Jose Emilio Labra Gayo in theory and because we had already worked with this

One of the advantages we found is that this project is for the subject of Software Architecture, so adding a hexagonal architecture to the project gives it more strength. Also, we have the intrinsic advantages of a hexagonal architecture, which are to decouple ourselves from the database, since the project does not care about the implementation of this, to focus more on the application domain, to decouple the layers of the backend, this leads to the fact that it was easier for us to perform unit tests and added modifications

As disadvantages, I would say that the main ones were that a large part of the project had to be redone, given by the teachers, and that not all the members knew how the architecture worked

Docker Database

The decision to use a docker for the database was taken at the beginning of the project, this decision seemed natural to all of us at the beginning because if we had a docker for the frontend, another one for the backend, it made sense to make another one for the database. Although at the beginning we tried MongoAtlas to host our database, we didn’t like to depend on an external service

This decision has many advantages in terms of architecture; we manage to reduce dependence on external services by taking care of the maintenance of the database as well as its deployment and configuration. The advantages of using microservices instead of using services provided by large companies have been widely discussed in class. We base ourselves on the recommendations given in theory on the use of microservices, as these manage to lower the coupling of the project, the use of individualised docker for each service gives us a freedom that we would not have in SOA, and also gives us greater speed when it comes to deployment

As disadvantages the most notable of all has been the complete lack of knowledge that we have of the use of microservices, we have generated quite a few headaches because not having the same approach as the rest of the groups we could not help each other, but we looked for a lot of information in forums and other websites, to get everything to work

Seeding the database in Docker

Since we had the database in a separate docker, we decided to create another one to seed the database, it was decided to do it in python as it seemed the fastest to do, due to the simplicity of python

By having the database seeding isolated from the rest of the project, we make inserting data into it as easy as adding a line to the file, it is also good because we could use external python datasets to populate our model, this makes our project highly modifiable

One drawback we saw is that if you don’t control in the database that there can be unique items by name (see controlling that no two products are the same), then you could not run the docker-compose several times as it would repeat data. It also complicates the task of getting it up on the web

Distance Matrix API to calculate distances

We decided to use Distance Matrix API to calculate the distance between 2 streets

It gives us the distance by passing 2 addresses in string format

It doesn’t give us the shipping price directly. We have to calculate it manually from the distance.

Various databases

It was decided to create separate databases, one for backend unit tests, one for e2e unit tests, one for docker deployment and one for local deployment

With this we get low the level of coupling of the project, since each part of the project that needs the database, has a dedicated database for it, for example if in the unit tests we put a new user to register, this is not registered in the production database, nor in the unit tests, nor in the local tests. This was easier for us thanks to the hexagonal architecture, as we only had to touch on one file to create as many databases as we needed

There were not many problems with this decision, but if this were a large-scale project I suspect that having 4 databases instead of one would be more costly and difficult to maintain, but at our scale it only brought benefits

MUI & Bootstrap

We used both libraries. MUI because of the facilities given by some of its components and bootstrap because of the easy way to style them any way we want

Both resources are compatible and easy to use and syncronize

When used both components at the sae time, sometimes they are not same-styled

AWS

The decision to use AWS was practically not a decision, but a necessary decision given our resources and focus. By having 3 distinct dockers, we can no longer deploy for free on Heroku, as it is a cloud computing platform as a service that only allows 2 containers simultaneously for free. In Azure we had no credit, so we were left with ASW

A big advantage was the free credit and the good guidance of pglez82 which we followed step by step

We had a hard time getting our whole project to work on ASW, but I think we would have had the same problems on any other platform

PBKDF2

We decided to increase the security of the project by using an asynchronous encryption algorithm such as PBKDF2

We decided on this one because we have taught it in another subject and we know how it works inside. Thanks to it we have managed to save our passwords encrypted, which considerably increases the security of the application

Changes had to be made in many parts of the project, especially in the backend, as the user entity had to be changed

Login to SOLID POD

At the meridian of the project development, the decision was taken to use only the address of the user’s SOLID PODs and not to do the whole login with SOLID. It should be noted that we do have a SOLID login, but this is optional, as we have seen that SOLID does not work as well as we would like, so we leave it up to the user to decide whether to log in to SOLID or just enter their SOLID username and we just take out the address

The main advantages are that we give the user more freedom when buying in our shop, we do not restrict the user to only have SOLID, also by having both options, if one of these does not work we have the other, thus increasing the solidity of the project

Doing the two options functions entailed double the work required for this part

Bootswatch

We used bootswatch to give the bootsrap components a uniform style and also make the website style in a harmony where all components and colours match

I’ts super easy to use and makes you save a lot of work in CSS style sheets

MUI components are not affected so we had to style them manually

SweetAlert2

We used this library to give the user intuitive and animated alerts while using the website

I’ts easy to use and comes with predeterminated settings that makes the programming experience a lot easier

I’ts another dependecy we had to take care of and make sure it doesn’t overlap with anything else ceating bugs

Work

One of the decisions taken was to prioritise the necessary functionalities and polish them, rather than make new ones optional

We were able to polish the functionalities we had, although we would have liked to polish them further

In the end we didn’t manage to polish them at all and lost the option to make them optional

react-material-ui-carousel

This library is used to make our home page a little bit more dynamic and beautiful. This is a library created with @mui components.

Very configurable and easy to use. It gives a very good result with little configuration.

Is another dependency that makes our proyect heavier and more dependent on external libraries. It also makes us to hardcode some code as images URLs and some texts.

CSS

Used to make our application more beautiful and to make all pages elements stay in its positions.

Is a known language for some of our team members, so we can use it properly.

It makes you write more code and sometimes is difficult to make the styles in the proper way.

10. Quality Requirements

10.1. Quality Tree

Quality Requirements

10.2. Quality Scenarios

Quality goal

Scenario

User Priority

Developer Priority

Privacy

The app is SOLID based which means the users have their personal information storaged in pods (personal online data stores) this technology makes it better for the users always respecting their privacy. For example, the client’s address can be consulted on it’s pod in props of calculate the shipping price.

High

High

Efficiency

The system is able to act quickly and with fluidity when the user interacts with it. For example, if a client wants to buy a product, the shipping price should be rapidly calulated not making it tedious to the user.

High

High

Testability

DeDe can be tested with certain ease using technologies such as Prometeus, Grafana and Postman as an external help to make sure everything works properly and finding bugs or mistakes in props to improve the application.

Low

High

Modifiability

The system, divided in Frontend, Backend and documentation (which makes it easer to develop) has a quite reusable code, which increments the possibilities of adding new functions or update the existing ones with more looseness. For example, the code used for the implementation of the function that allows clients see theis orders, can also be used for the function that allows administrators see every single order made on DeDe.

Low

High

Usability

The site has an intuitive design that makes the experience comfortable for every user in the application with them being clients or administrators. They should know where to go or what to do with a glance due to the familiarity of the design.

High

High

Integrity

The data should be always in a valid state following the ACID values. If some process fails, there are not going to be any changes and the system will stay in a consistent state without harming the user. For example, if a purchase fails just before the order confirmation, the system will return to a consistent state where the purchase won’t be made.

High

High

This quality requirements are priorized and more described in the epigraph 1

11. Risks and Technical Debts

11.1. Risks

This is the compilation of the identified risks ordered by priority that we must minimize or avoid.

  • Not having knowledge of the following technologies:

Technology Risk

SOLID

We may have difficulty following SOLID principles as we have not worked on a SOLID project before and handling decentralized data may be difficult.

PODs

We don’t have any knowledge about PODs prior to this project, so we need to learn how to keep user information secure and private, which can take considerable time.

React

We have never used it, so we must learn during the project.

MongoDB

We may run into difficulties using a NoSQL database, as we have experience only using SQL databases, which can cause delays while we learn how to use it.

Grafana and Prometeus

We have never used these tools to monitor a project and we need to adapt to them.

Postman

We have never used this testing tool.

Node.js

We don’t know how to use it.

AWS

It costs time to adapt to it due to we have never used it.

Docker

We have to learn how to use it.

Express

We may have some dificulties, we need to learn about it.

Bootstrap

We have to learn about this style library. It will cost some time.

TypeScript

Some members of the group have some knowledge of JavaScript, and since TypeScript is similar to JavaScript, it won’t be too difficult to adapt, although it will take time to learn this language.

Git

We have little knowledge about using Git, so we can easily go wrong.

Gatling

We use it to do load test. We had no idea about this tool.

  • Other risks:

Risk Explanation

Abandonment of a member

If a member leaves the group, it would mean redistributing the work, suddenly having more workload for the members who remain.

Being just 4 members

It can be more difficult to develop this application being only 4 due to other groups have 5 or even 6 members to do the same work.

11.1.1. Minimize or avoid risks

Risk How to avoid or minimize

Not knowing the technologies

We seek information and practice using them.

Posibility of a team member leaving

We will have good communication and help each other.

Being only 4 members

We have to do a hard work to develop the application.

11.2. Technical debts

  • Even if the app is internationalized, we could’t find a way of automatic translation because of the time and complication of the task. A lot of APIs aren’t free and require a laborious configuration that could pottentialy give us some problems we hadn’t time to resolve.

  • The SOLID Login is implementated and made. But because of our deployment choice we had problems with the https certificate. We had no time to fix it before the last release. Instead, we decided to use the public address on the VCARD od the SOLID POD.

  • We had intention to complete some optional exercises (pick up points, delivery stimation, and delivery services) but we had no time to do them before the last release.

  • We could not add checkboxes on the shopping cart because we were busy doing other mandatory tasks. at the end we could not complete it

  • We wanted to incorporate a drag and drop component so the admin could update a picture of a new product by dragging it to the field but, again, we were concenrated in completing the mandatory tasks

  • SOLID in the deployment is no posible due to SOLID needs HTTPS requests and AWS no allows to do HTTPS.

  • In the deployment, the database could not be seeded because we need to make the package public and we do not have permissions.

  • We would like to have improved the selector to choose the amount of product to add to the cart because when there is a lot of stock, the combobox is huge.

  • Redirect from order placed to my orders.

  • We wanted not not to load the entire catalog directly, but load a few items and add a "see more" button to show more.

  • There are pages and front-end components that are coupled because they have components that render together. Would have to undock to get more coverage.

12. Glossary

Term Definition

ACID

Acronym that refers to the set of 4 key properties that define a transaction: Atomicity (The transaction can be commited or rollbacked), Consistency (the data must be coherent), Isolation (multiple transactions should be able to execute at the same time without interfering with each other) , and Durability (The changes must be persistent)

API

Application Programming Interface. A set of routines and methods provided by a library for use by other software

Backend

Part of the application that implements the logical business and interacts with both the frontend and the database

Bootstrap

Front-end open source toolkit

Bootswatch

Styles for bootstrap components library

Continuous integration system

The practice of making automatic integrations to a project in order to detect errors prematurely

Decentralised data warehouse (DeDe)

Collection of centrally available data stores maintained by individual regions

Efficiency

Hability of working fast consuming the least amount of resources

Frontend

Part of the application that defines the user interface and is on charge of interacting with the user and send the information and petitions to the Backend

Hosting service

Service where Web pages are hosted

Integrity

The hability of being in a consistent state

Mobile application

Tools that a user can use by accessing an application on a mobile device

Modifiability

The hability of something to be modified easily

MUI

React component library

Open Source

Software development model based on open collaboration

POD

Personal Online Datastore. Allows its users store every kind of personal data and manage the external access

Privacy

The right of not sharing information if the user decides so

SOLID

Web data decentralisation project

Superset

A language that is a subset of another language, fully compatible with that language

SweetAlert2

Animated alerts library

Testability

Hability of something to be tested as an experiment and make decisions with the obtained results

Usability

The hability of something to be easily used by the biggest part of users

Web application

Tools that a user can use by accessing a web server

13. Annexes

13.1. Usability survey

To test our application and try to see how users use it, we made a survey with some of our friends and parents.

We tried to test our web with two age groups. The first one is between 20 and 30 years old. All this group is considered as medium-high technology knowledge. The second one, between 45 and 55 years old, is a group with a low knowledges in techonolgy uses.

First of all we made them login and signup in our web. Only one person had problems in this part, due to the little custom of carrying out this type of actions.

log in problems

One of the most important aspects when developing our application has been its usability. For this reason, we have asked the interviewees to tell us what problems they have encountered when browsing the application. The majority have not had problems, but there have been two cases in which there have been slight confusions, due to the language of the store. For these users, since the home store is in English, it could be a bit confusing when changing the language and without it, they could not navigate. There has also been a user who has detected that the header with the links, on small screens, is dislodged to be able to enter. The biggest navigability problem is that almost all those interviewed have found a bug in which one of the images on the home page was loaded incorrectly and was cut off.

In addition, they have been asked to give a numerical score for usability.

web usability

As for the aesthetics of the application, there have been very good opinions and it has seemed attractive to users.

beauty votation

They have also been asked to simulate a purchase. Everyone has been able to add to cart easily. However, there have been a couple of problems in this regard. Some users wanted to know detailed information about the products to decide which one to buy. However, they were not very clear about how they could do it, since some did not see the signaling that appears when the mouse is placed over a product, indicating that it is a button. The filtering of products has been carried out correctly in general, except for one case in which, due to the resolution of its screen, some buttons were slightly pressed and made their use inappropriate. They have also been asked to pay for the purchase. This is the aspect in which there have been problems. Using a slightly different technology than usual, just over half have had trouble uploading their POD data to our app.

satisfaction with the application

None of the interviewees had a POD and in many cases it has even been necessary to help them create one in order to use it. Finally, they have been asked about the response of the application and the load times. In general terms, users are satisfied. As a conclusion of this study, the general opinion is good, although it is clouded by the use of PODs since it is something that has been difficult for them to understand how to use and that most of them do not see as necessary, preferring the traditional method.

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.