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

Describes the relevant requirements and the driving forces that software architects and development team must consider. These include

  • underlying business goals, essential features and functional requirements for the system

  • quality goals for the architecture

  • relevant stakeholders and their expectations

A retail company is in the need for an online retail system that ensures the privacy of its users based on the Solid specification (not to be misinterpreted with the SOLID principles of Object Oriented Programming). We will call this app DeDe (Decentralized Delivery).

Moreover, this will be ensured with the utilization of Solid Pods; a specification that lets people store their data securely in decentralized data stores. This grants the user total control of the data that is exposed using this retail service delivery, since they can concede or revoke access when needed (and the app will not store personal info).

1.1. Requirements Overview

Contents

Short description of the functional requirements, driving forces, extract (or abstract) of requirements. Link to (hopefully existing) requirements documents (with version number and information where to find it).

Motivation

From the point of view of the end users a system is created or modified to improve support of a business activity and/or improve the quality.

Form

Short textual description, probably in tabular use-case format. If requirements documents exist this overview should refer to these documents.

Keep these excerpts as short as possible. Balance readability of this document with potential redundancy w.r.t to requirements documents.

These are the main requirements of the application:

  • Emulation of an online shopping system where the user can select and order products.

    • Like any other web app but in a reduced way.

  • Calculation of the delivery cost based on the address of the user in their Pod.

    • The cost is based on an external API.

  • Simulation of the process of buying a product.

    • The user can buy a product and add it to the shopping cart.

    • There is a list of products for the user to buy.

  • Allowing the user to access the orders previously done.

    • Like checking the search history in your browser.

  • Implementation using React and Typescript.

    • This will be for the front-end, for the back-end we will use other frameworks such as SpringBoot.

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

    • That means having a hosting service in which we can access the service.

1.2. Quality Goals

Table 1. Quality Goals, ordered by priority, with the most important ones being on top
Number Quality Motivation

1

Privacy

The task to be done requires the use of SOLID, whose purpose is to secure the data of the users, so no one that is not authorized should be able to access that information.

2

Usability

The application can be used in an easy and intuitive manner, for all kinds of users.

3

Performance

The software should be fast and have as least response time as possible.

4

Availability

The system should be able to be used for as much time as possible.

1.3. Stakeholders

Table 2. Stakeholders
Role/Name Contact Description Expectations

Students

Diego Martín Fernández
Laura Pernía Blanco
Stelian Adrian Stanci

The members of the team that is going to develop this project.

They are expected to deliver a functional version of this product with the use of several different technologies, and which meets the stated requirements.

Teachers

Pablo González González
José Emilio Labra Gallo

Qualified instructors who are able to teach, guide, and supervise students throughout the development process.

The teachers are expected to evaluate the work of the students and to help them achieve their objective.

Users

The ones that will make use of the application.

They are expected to use the application for some purpose, and possibly to even give feedback about it.

Related companies

Inrupt\Empathy

Companies that have contributed to the creation of the SOLID Challenge, which is closely related to this project.

They promote the SOLID Challenge, help solving errors through its forum, and reward the winning project.

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)

We divide the constrains into two parts: technical and business constrains.

2.1. Technical constraints

Contents

The technical constraints for the development of the system.

Motivation

Know the fixed technical constraints for the system.

Form

Table with all the technical constraints and its corresponding description .

Technical constraints are those that are fixed technical constraints decisions. Most of them appear in the description of the system.

Constraint Description

React

React defines itself JavaScript library for building user interfaces. The application has to be implemented using React

TypeScript

TypeScript is a strongly typed programming language that builds on JavaScript.

SOLID

Solid is a specification that lets people store their data securely in decentralized data stores called Pods. When data is stored in someone’s Pod, they control its access.

Continuous integration system

The application has to be accessible and deployed using a continuous integration system.

GitHub

The code has to be deployed in GitHub, a public repository.

2.2. Business constraints

Contents

The business constraints for the development of the system.

Motivation

Know the business constraints for the system.

Form

Table with all the business constraints and its corresponding description .

The business constraints are those decisions affecting the software architecture design or that will affect future decisions.

Constraint Description

Schedule

The system has to be finished by the 13th week of the laboratory, with deliveries by the 4th, the 7th and the 10th weeks.

Team

The team is composed by only three people.

Students

All of us are students with more subjects and projects, so we can not dedicate full time to the project.

Keep track of orders done

The system has to allow users to visualize the orders done, so it has to keep track of them.

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.

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.

Business context diagram

Entity Description

User

Interacts with system by viewing, selecting and buying products. Users have an account in the system that lets them visualize orders done.

SOLID pods

They have information about client’s addresses. The system obtains this information to calculate shipping costs and process orders.

Paypal API

During checkout process, DeDe uses the PayPal API to allow clients to play for their order.

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.

The system will follow the SOLID specification by which the user’s privacy will be preserved. This means non storing personal information and using "pods" (Personal Online Data Store), where the customer’s personal data is stored.

All the application will be developed by using Typescript and the React framework. Using React will allow us to create interactive user interfaces in an easy way.

We are going to use a relational database to store the information about the products. We have chosen MySQL for this.

Technical context diagram

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 commitments

As we commented before we will use React and TypeScript. Moreover, we have also decided that the most optimal decision regarding the database of the product is a relational one, such as MySQL.

This is due to the need of knowing the relations between the different items such as clients, products bought from clients, records, deliveries and so on. On the other hand, the experience that we already have will be of great use, since all of us are experienced in SQL databases usage.

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

We have chosen to build the application around the MVC model. This means that the system will be divided into a View part, which will be the one the user interacts with, a Model part, that will work with data, and a Controller part, that will connect the other two, acting as an intermediary.

4.3. Decisions on how to achieve key quality goals

The goals have already been stated in section 1.2, now we will take a look at how we will work to achieve each one:

Privacy will be accomplished mainly through the use of SOLID pods, and using only the information that is necessary for the operations to work.

We will obtain usability by making easy and understandable interfaces for the users, that can be understood by people that are not necessarily experts in working with computers.

As for the performance, we will work hard to make optimized code, that does not introduce unnecessary complexity and can reduce response times as much as possible.

Finally, the availability will be achieved by making sure that when the user wants to access and use the application, it initializes correctly and does what it is supposed to do.

4.4. Relevant organizational decisions

Working in a project such as this one with many people means that communication is very important, and there are several ways in which our team communicates on a regular basis.

Laboratory classes

Each week we have 2 hours in which all the members of the team are together and can discuss things about the project. It is also a very useful time to review the work done in the previous week and goals for the future.

GitHub

GitHub is a very complete tool, that has tons of options that can help with organizing the work of the project. You can see what needs to be done, what has already been done, what are the plans for the future, all of this combining tools such as the issues, discussions or the wiki of the repository (among many others). It also helps a lot in organizing the changes made in the code or the files of the repository, through the use of pull requests.

Communication channels

We have created a Whatsapp group, where we talk about things related to the project. All of the relevant things that have to do with decisions of the development of the system are also put in GitHub, as it helps with keeping track of these important details. Other means of communication that we sometimes use are Discord or Microsoft Teams.

5. Building Block View

Content

The building block view shows the static decomposition of the system into building blocks (modules, components, subsystems, classes, interfaces, packages, libraries, frameworks, layers, partitions, tiers, functions, macros, operations, datas structures, …​) as well as their dependencies (relationships, associations, …​)

This view is mandatory for every architecture documentation. In analogy to a house this is the floor plan.

Motivation

Maintain an overview of your source code by making its structure understandable through abstraction.

This allows you to communicate with your stakeholder on an abstract level without disclosing implementation details.

Form

The building block view is a hierarchical collection of black boxes and white boxes (see figure below) and their descriptions.

Hierarchy of building blocks

Level 1 is the white box description of the overall system together with black box descriptions of all contained building blocks.

Level 2 zooms into some building blocks of level 1. Thus it contains the white box description of selected building blocks of level 1, together with black box descriptions of their internal building blocks.

Level 3 zooms into selected building blocks of level 2, and so on.

5.1. Whitebox Overall System

Here you describe the decomposition of the overall system using the following white box template. It contains

  • an overview diagram

  • a motivation for the decomposition

  • black box descriptions of the contained building blocks. For these we offer you alternatives:

    • use one table for a short and pragmatic overview of all contained building blocks and their interfaces

    • use a list of black box descriptions of the building blocks according to the black box template (see below). Depending on your choice of tool this list could be sub-chapters (in text files), sub-pages (in a Wiki) or nested elements (in a modeling tool).

  • (optional:) important interfaces, that are not explained in the black box templates of a building block, but are very important for understanding the white box. Since there are so many ways to specify interfaces why do not provide a specific template for them. In the worst case you have to specify and describe syntax, semantics, protocols, error handling, restrictions, versions, qualities, necessary compatibilities and many things more. In the best case you will get away with examples or simple signatures.

Building block level 1

5.2. Scope and context

Motivation

The user creates and interacts with its own Pod and with de DeDe system. The DeDe system has access to the user’s pod.

Building block Description

DeDe

Online retail system that preserves the privacy of its users by following the SOLID principles.

User’s Pod

The user’s Pod is where the user stores its data to control it.

User

Person accessing to the DeDe system and that has its own Pod.

5.3. Level 1

Motivation

The DeDe system is expanded in order to give more details about its internal implementation

Building block Description

Frontend

The part that is seen by the user when using the application.

Backend

The part of the application that deals with its logic and communicates with the database.

Database

Database used by the DeDe system to store the needed information, such as the orders done, the addresses, etc. In our case we will use a MySQL database.

5.4. Level 2

Motivation

The frontend and the backend are expanded to give a further insight into its composition

Building block Description

Views (GUI)

Contains all the user interfaces of the online shop. The user interacts with them to see and select products, visualize past orders and confirm the purchase, among others.

Controller (RestAPI)

It is implemented following the RestAPI architecture. Responds to user events in the views by invoking corresponding actions in the model. It is an intermediary.

Model

Implements all the business logic needed. Accesses the database to retrieve products and clients and to register orders. Besides, it obtains clients' addresses from their PODs.

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

  • …​

LogIn

The user can log in into the application at any time during navigation, following the next diagram:

"Login diagram

6.1. User interaction

The user will follow the next diagram in order to order some products:

User’s interaction diagram

7. Deployment View

Content

The deployment view describes:

  1. the technical infrastructure used to execute your system, with infrastructure elements like geographical locations, environments, computers, processors, channels and net topologies as well as other infrastructure elements and

  2. the mapping of (software) building blocks to that infrastructure elements.

Often systems are executed in different environments, e.g. development environment, test environment, production environment. In such cases you should document all relevant environments.

Especially document the deployment view when your software is executed as distributed system with more then one computer, processor, server or container or when you design and construct your own hardware processors and chips.

From a software perspective it is sufficient to capture those elements of the infrastructure that are needed to show the deployment of your building blocks. Hardware architects can go beyond that and describe the infrastructure to any level of detail they need to capture.

Motivation

Software does not run without hardware. This underlying infrastructure can and will influence your system and/or some cross-cutting concepts. Therefore, you need to know the infrastructure.

Form

Maybe the highest level deployment diagram is already contained in section 3.2. as technical context with your own infrastructure as ONE black box. In this section you will zoom into this black box using additional deployment diagrams:

  • UML offers deployment diagrams to express that view. Use it, probably with nested diagrams, when your infrastructure is more complex.

  • When your (hardware) stakeholders prefer other kinds of diagrams rather than the deployment diagram, let them use any kind that is able to show nodes and channels of the infrastructure.

Describe (usually in a combination of diagrams, tables, and text):

  • the distribution of your system to multiple locations, environments, computers, processors, .. as well as the physical connections between them

  • important justification or motivation for this deployment structure

  • Quality and/or performance features of the infrastructure

  • the mapping of software artifacts to elements of the infrastructure

For multiple environments or alternative deployments please copy that section of arc42 for all relevant environments.

Infraestructure diagram

Motivation

The motivation of this project is to have a functional webapp deployed.

For this purpose we will use Azure. The application is deployed by using GitHub actions over ssh and docker, since there is a container for each of the elements that are inside the VM: * WebApp: with React * Restapi: in SpringBoot * Database: using MySQL

Github Actions and SSH

Github actions is a series of scripts executed inside a virtual machine on github, you can even set up docker containers or databases (although they are short lived). An example could be to set up a database before running the test that the restapi has.

We are using GitHub actions for automating the process described above. We connect to the VM instance using SSH and deploy the application inside it with Docker.

Github actions provides us with the hability to execute the deployment each time a new release is made, we can also change this for making it when a commit is added or a pull request is issued.

The code for this workflow is inside .github/workflows in asw2122.yml. Moreover, since the default implementation was supposed for Nodejs and, because we are using SpringBoot, we had to add new actions.

Docker

Each of the containers has its own DockerFile with the instructions needed for creating the images. There are only two, for the webapp and the restapi, because we are using a mysql image from the marketplace. The ports for each image are the following (refering to the internal and external ports, they have the same value to avoid complications):

  • WebApp → 3000:3000

  • RestApi → 5000:5000

  • DataBase → 3306:3306

Azure

Azure is the provider for this project, we are using an EC2 VM instance. Other alternatives are Amazon Web Services, Google Cloud, etc. Nowadays all of them offer pretty much the same service and the hability to change between different providers with ease.

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

Domain model

8.2. Domain concepts

Concept Description

user (Order)

The attribute user in the Order entity refers to the webId of the user. Regarding users, we only store their webId in hexadecimal form tied to the order.

image (Product)

We store the image as a link to an external site where it is stored.

Rating

Users can leave a review consisting of a comment and a numerical rating in every existing product through the product detail view.

user (Rating)

Ratings can be anonymous, in that situation, "user" value is "Guest". In case the user is logged in, "user" contains the name stored in the POD.

status (Order)

Makes reference to the shipping status. It has three possible values: "PROCESSING", "SHIPPED" and "RECEIVED".

8.3. User experience

Our intention is to make the user interface as intuitive as possible. To achieve it, we follow the usual standars of e-commerce websites:

  • The shopping cart is at the upper-right corner, represented with the typical cart icon.

  • Login is at the left of the cart.

  • DeDe logo takes to the home page.

  • Order detail view has a status progress bar to make it easy to see in which state the order is and what is left to be received.

  • Checkout process follows the usual steps: order overview, payment and order completed message.

  • Side bar button in the upper-left corner and contains direct links to the homepage and products accesible from anywhere.

  • Footer at the bottom with About us page and links to resources relevant to the project.

The entire web is in English, but to make it accesible to more users, the idea would be to internationalize it in the future, specially in Spanish.

8.4. Security

Users do not create an account in DeDe website, they have all their information stored in their own POD. We only store the address and postal code when an order is made to guarantee delivery of the purchased products. Besides, such information is tied to the order and never used for any other purpose. WebId is also saved with the order to allow users to check their order history and current order status. In case there is no address in the POD, a direct way to add one is provided through the website, but always with the permission of the user and storing only the information they provide for that purpose.

9. Design Decisions

Contents

Important, expensive, large scale or risky architecture decisions including rationals. With "decisions" we mean selecting one alternative based on given criteria.

Please use your judgement to decide whether an architectural decision should be documented here in this central section or whether you better document it locally (e.g. within the white box template of one building block).

Avoid redundancy. Refer to section 4, where you already captured the most important decisions of your architecture.

Motivation

Stakeholders of your system should be able to comprehend and retrace your decisions.

Form

Various options:

  • List or table, ordered by importance and consequences or:

  • more detailed in form of separate sections per decision

  • ADR (architecture decision record) for every important decision

Design decisions sort by relevance.

Design decision Context Decision Consequences

Backend language

We need a backend language and framework to implement all the data storage related functionality.

Java with Spring Boot framework

We don’t need to spend time learning how to use it because we already have experience. Every deploy-related configuration file given to us ended up being made for Node.js, so we have to spend time learning how to adapt it to Java.

Application architecture

Architectural pattern used to structure the application

MVC

We have previous experience using this pattern along with Spring Boot and it’s easy to understand and implement.

Database

We need a database to store products and orders

MySQL

We practically only have experience with relational databases, so by using MySQL we don’t need to investigate how to use a non relational one. As a downside, since the only a few tables are needed maybe it would have been simpler to use a document based db.

User login

We need a way to identify users in order to show order history

Use pod login (@inrupt/solid-ui-react and @inrupt/lit-generated-vocab-common libraries) and don’t store accounts

We don’t have to deal with password encryption or with account information. We integrate pod login in our application front-end so the pod provider is the one in charge of all the information. Orders are linked to the pod webId. We depend on an external service that sometimes does not provide the best service.

Shopping cart architecture

We have to decide whether to store the shopping cart in client side or server side

Shopping cart stored in the client side

The number of calls from the front end to the backend is minimized, so performance improves. The shopping cart content is only sent to the backend during checkout.

Payment

We need a way to allow clients to pay for their orders

Paypal API

We integrate Paypal API into our application so we don’t need to spend much time dealing with more complex infrastructures.

Product images

We need to show product images

Links to external website

No need to deal with image storage and transfer from back end to front end. We depend on an external website that may be down or delete any image.

10. Quality Requirements

Content

This section contains all quality requirements as quality tree with scenarios. The most important ones have already been described in section 1.2. (quality goals)

Here you can also capture quality requirements with lesser priority, which will not create high risks when they are not fully achieved.

Motivation

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

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

10.1. Quality Tree

Content

The quality tree (as defined in ATAM – Architecture Tradeoff Analysis Method) with quality/evaluation scenarios as leafs.

Motivation

The tree structure with priorities provides an overview for a sometimes large number of quality requirements.

Form

The quality tree is a high-level overview of the quality goals and requirements:

  • tree-like refinement of the term "quality". Use "quality" or "usefulness" as a root

  • a mind map with quality categories as main branches

In any case the tree should include links to the scenarios of the following section.

Quality tree

10.2. Quality Scenarios

Table 3. Quality Scenarios
Quality requirement Quality scenario Priority Difficulty

Privacy

The application will not access any data of the user without being granted permissions beforehand. Only the data necessary for the correct functioning of the application will be accessed and used.

High

Medium

Usability

The application can be used in an intuitive manner. It should be easy to do the operations in the correct way.

High

Medium

Performance

The users should be able to complete all the operations of the application in a reasonable amount of time (the response time of every operation might be different, but it should not surpass 3 seconds)

High

Medium

Availability

Any time the user wants to use the application it is accessible and runs properly

High

Easy

Accessibility

Users with disabilities should also be able to use the application. They should be provided several different alternatives for doing operations. We will aim for reaching the AA Web Accessibility Guidelines.

Medium

Medium

11. Risks and Technical Debts

Contents

A list of identified technical risks or technical debts, ordered by priority

Motivation

“Risk management is project management for grown-ups” (Tim Lister, Atlantic Systems Guild.)

This should be your motto for systematic detection and evaluation of risks and technical debts in the architecture, which will be needed by management stakeholders (e.g. project managers, product owners) as part of the overall risk analysis and measurement planning.

Form

List of risks and/or technical debts, probably including suggested measures to minimize, mitigate or avoid risks or reduce technical debts.

11.1. Risks

The risks that we might find during the development of the project are the following (ordered by priority):

Table 4. Risks
Risk Remediation

Small team

Prioritize the most important things, as we will probably not have much time to do several extra things

Lack of time

Be as effective as possible with the time we have, keep realistic expectations of what we can achieve in a given span of time

No previous knowledge of React, Typescript nor SOLID

Spend some time learning the basics of this technologies, and build upon that basis to get the knowledge required for working with these technologies in our project

Now we talk about some technical debts, that are also ordered by importance

Table 5. Technical debts
Debt Explanation

Using Springboot and MySQL technologies

At the beginning of the project they looked like a good choice as many members of the team had some experience working with them, but as it progressed we started having some problems, that would not have happened using other technologies.

Not validating user input

Due to the lack of time and with the goal of achieving a functional application in a short period of time, we did not pay enough attention to user input, that should be validated to a bigger extent to preserve security.

Code good practices

In some parts of the code we have neglected code quality (as in the use of suitable design patterns and code design) to obtain a functional product faster. Since we had no prior experience using React nor Typescript, we don’t really know all the good practises and most optimal way of coding with them, so it would have taken us a lot of time to be proficient.

Hardcoded credentials

He have hardcoded credentials in the code, which constitute a very serious security problem. As this is not a real project and we only use sandbox/free services we decided to leave them that way in order to spend more time in more critical aspects of the functionality.

Lack of some tests

We didn’t have enough time to perform integration and load test, so there might be problems we are not aware of that we may have noticed when doing such tests.

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

Azure

Azure is a very big collection of servers and networking hardware, which runs a complex set of distributed applications.

Caddy

Reverse Proxy used and file server

Continuous Integration

Introduce changes to the system as fast as possible in order to detect errors early

Docker

Open source containerization platform. It enables developers to package applications into containers.

React

JavaScript library that helps building efficient interfaces for applications

Rest API

An application programming interface (API or web API) that conforms to the constraints of REST architectural style and allows for interaction with RESTful web services

SOLID

Solid is a specification that lets people store their data securely in decentralized data stores called Pods.

SOLID PODs

They have information about client’s addresses. The system obtains this information to calculate shipping costs and process orders.

SpringBoot

Tool that makes developing web application and microservices with Spring Framework faster and easier, as it helps with several aspects of the configuration.

TypeScript

Language built upon JavaScript that takes into account types

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.