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

1.1. Requirements Overview

The following diagram represents the functional requirements of the application.

Sequence requirements use case digram

List of requirements:

  • The system will emulate an online shop where the users will be able to select and buy products.

  • The system will calculate the shipping costs of the selected products based on the shipping information provided by the user’s pod. The price will be calculated based on distance between distribution center and client’s address.

  • The system will show the user the total price for the products selected.

  • The system will register the user’s order and will proceed with the shipping.

  • The system will show the user a list of all its orders.

1.2. Quality Goals

Contents

The top three (max five) quality goals for the architecture whose fulfillment is of highest importance to the major stakeholders. We really mean quality goals for the architecture. Don’t confuse them with project goals. They are not necessarily identical.

Motivation

You should know the quality goals of your most important stakeholders, since they will influence fundamental architectural decisions. Make sure to be very concrete about these qualities, avoid buzzwords. If you as an architect do not know how the quality of your work will be judged …

Form

A table with quality goals and concrete scenarios, ordered by priorities

Nº Quality Motivation

1

Confidentiality

The application will respect client’s privacy. Users are going to retrive their personal information stored in Solid Pods.

2

Availability

The application will be available the majority of time, specially at client reviews. System availability will always be above 97%, with about 15 hours of maintenance every three weeks.

3

Usability

The GUI will be easy to use for any user, especially non-technical users. We will do usability tests with different user profiles.

4

Accesibility

Provide equal access and opportunities to people. Increase the number of customers using the application.

5

Efficiency

Server’s response is going to be under 0.5 seconds. This value is considered the minimum acceptable waiting time by users all over the net. Waiting times upper 0.5 seconds are usually negative for websites' popularity.

1.3. Stakeholders

Contents

Explicit overview of stakeholders of the system, i.e. all person, roles or organizations that

  • should know the architecture

  • have to be convinced of the architecture

  • have to work with the architecture or with code

  • need the documentation of the architecture for their work

  • have to come up with decisions about the system or its development

Motivation

You should know all parties involved in development of the system or affected by the system. Otherwise, you may get nasty surprises later in the development process. These stakeholders determine the extent and the level of detail of your work and its results.

Form

Table with role names, person names, and their expectations with respect to the architecture and its documentation.

Role Description Expectations

Client

Fictitious company that hires us to develop DeDe application.

They expect continuous and responsible work. In addition, a product that reflects what has been learned in the course.

Development team + Software Architects

Formed by group ES5A students.

Learn about Software Architecture and teamwork.

Users

People interested in buying online products while maintaining their privacy.

To have an application that allows making purchases and at the same time managing the shared data.

Suppliers

These are the distribution centers of the products offered in the application.

Deliver orders to users.

Inrupt

Company founded by Tim Berners-Lee.

Make known the SOLID project and promote its development.

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)

Table 1. Technical Constraints

Constraint

Description

SOLID

We will use this technology so that the users´ information cannot be centralized in a server, this information will be obtained from the users´ pods, as long as they give permissions.

React/Typescript

Its shared use will offer us different advantages such as having a more robust and bug-proof application.

Arc42

We must use this template because it is suitable for the project to be carried out, it will allow us to document it in a clear, simple and effective way.

GitHub

We must use this version controller. It helps us to have a good organization of the project and facilitates teamwork.
Table 2. Organizational constraints

Constraint

Description

Time

Other task from other subjects will be constraints. Time spent doing them will be time we will not spend in the project. We must take advantage of our organizational skills in order to get success.

Knowledge

Technologies used are going to be constraints due to the few experience we have. We must improve our knowledge as soon as possible so it will be easier to work in the project.

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 of ArquiSocks

  • Client: the main target that should pay attention to our products, he has to interact with the shop and buy products.

  • Database: the infrastructure that stores the orders generated by the client and all the information related to them.

  • Solid pod: external storage which guarantees client’s privacy and personal data management.

  • Maps API: external service of a maps' provider which is going to be the responsible of calculating the distance between client’s address and distribution center address. This distance will be used in order to calculate the price of the 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.

Technical Context of ArquiSocks

  • Web browser: the application used by the client to reach a connection to the shop. It could be an application such as firefox or chrome.

  • Database: the infrastructure that stores all the information related to the shop. Orders, products, etc…​

  • Solid pod: external storage which guarantees client’s privacy and personal data management. We will accede it using http requests to the web using an API key.

  • Webapp: it refers to the UI of the application. It will be the visible part of the shop called ArquiSocks developed using React.js.

  • Restapi: it is a server based on Node.js and Express that receives requests by the webapp. It will return json objects in order to satisfy webapp’s needs.

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.

Table 3. Technology decisions
Decision Reason

MongoDB as DBMS

MongoDB is a non-relational model that is a good choice for this project.

Docker for application deployment

Docker is chosen due to its popularity and there is a lot of information about this technology.

Visual Studio Code, WebStorm as IDE or a text editor

At the moment, everyone can use any IDE that supports Typescript and React. Or even, it is possible to use a text editor instead of an IDE. Because the project continues working regardless of the used tool. However, an agreement may be fine to avoid potential problems.
Table 4. Decisions about the top-level decomposition of the system
Decision Reason

Layered Architecture

Usage of MERN architecture allows us to easily build a 3-tier architecture entirely using only TypeScript and JSON.
Table 5. Decisions on how to achieve quality goals
Decision Reason

Online accessibility testing tools

To achieve accessibility

SOLID

To achieve confidentiality

NoSQL database

NoSQL database provides easy and fast search and thus efficiency is achieved.

Usability tests

Perform usability tests throughout development and do not leave for the last moment can help detect usability problems early.

Server provider

Choose the server provider and the payment plan according to our needs to achieve acceptable availability.
Table 6. Organizational decisions
Decision Reason

Kanban Board as work management tool

It allows stakeholders to visualize the workflow. Also, it helps development team to organize their tasks more visually.

Git Flow as branching strategy

All members have experience with it and find it comfortable.

Wiki to record of meeting minutes

It is an integrated tool in GitHub where the project’s git repository is.

Labels are created as needed

For now, create labels as needed and be careful not to duplicate them.

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 view shows the static decomposition of the system into building blocks, it includes libraries, modules, components…​ And also the dependencies among them.

Whitebox Overall System of ArquiSocks

Restapi and webapp are both balck boxes which are explained more detailed scrolling down a little.

Motivation

This diagram shows the relations of the application among many others systems. It also shows dependency relations with clients. This diagram provides readers a general static vision of the project.

Contained Building Blocks

Building block

Description

Client

Interacts with the application. He also takes care of his data using pods.

Database System

Service to store data. It is used through mongoDB atlas. Packages (npm): mongodb, mongoose.

Solid infrastructure

Mechanism to store data taking care of privacy. Packages (npm): inrupt/solid-ui-react

Maps API

API which allow us to manage distances and many other aspects related to addresses.

ArquiSocks

The main core of the application.
Important Interfaces

Interface

Description

nodo-fetch

Allow us to make asynchronous requests to the maps API so we can get information about coordinates and distances among many addresses.

mongodb and mongoose

Optimize database connections and data management

inrupt/solid-ui-react

Dependency which allows us to have a connection to solid. In this way we can get information from the pods.

5.2. Level 2

Here you can specify the inner structure of (some) building blocks from level 2 as white boxes.

When you need more detailed levels of your architecture please copy this part of arc42 for additional levels.

5.2.1. White Box Webapp

Whitebox Webapp

Motivation

This diagram shows the relations among webapp components and libraries used. The main library is mui used to optimize the development of many components. It has been implemented using React library for user interfaces.

Contained Building Blocks

Building block

Description

Api

Contains functions to connect with the restapi.

App

Main component which contains all other components. Packages (npm): mui.

Components

Contains all ui components of the webapp, like cart, order, navbar, footer…​ Packages (npm): mui, inrupt/solid-ui-react.

Contexts

It allows us to share data across the components more easily. For now, the context is sharing selected products in cart.

5.2.2. White Box Restapi

Whitebox Restapi

Motivation

This diagram shows the relations among restapi components and libraries used.

Contained Building Blocks

Building block

Description

Models

Stores classes which represent objects from database. Packages (npm): mongodb.

Routes

Admin requests and redirect to the service. Includes business logic. Packages (npm): express, mongodb, node-fetch.

Service

Connects to database. Packages (npm): mongoose, dotenv.

Server

Manage users' requests. Packages (npm): express, dotenv.

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

  • …​

6.1. Sign in

Sequence diagram signIn

6.2. View orders and products

Sequence diagram

Many details to keep in mind:

  • The user will interact with UI elements of the webapp such as buttons. These elements trigger events to the restapi.

  • Restapi will manage requests in order to get a response from database system. The response will be shown by the webapp in diferent views.

6.3. Add product to cart

Sequence diagram AddProduct

6.4. Delete product from cart

Sequence diagram DeleteProduct

6.5. Confirm purchase

Sequence diagram Confirm purchase

6.6. Register the sale event

Sequence diagram Register sale event

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.

7.1. Infrastructure Level 1

Deployment view diagram
Motivation

The user will access our app through a website which will communicate with the Web server hosted by Heroku. Also, the user can access our app hosted in Azure. Then, the Webapp will use the RestAPI to respond the user’s requests. The RestAPI will use both MongoDB and the Solid pod from the user in order to correctly respond the WebApp request.

Quality and/or performance features

The performance will depend mostly on the user’s internet connection and device hardware, since most of the infraestructure depends on external services (MongoDB, Inrupt, etc.). However, we can increase the performance of the application focusing on writing better and most efficient code.

Table 7. Mapping of building blocks to infrastructure

Element

Description

Client

Device use by the user to interact with the app.

Web server

Server where we will have the app running, in our case, Heroku.

WebApp

Frontend of the app.

RestAPI

Backend of the app.

Database Server

Server with our Database, in our case, MongoDB Atlas.

Solid Pod Server

Solid pods used by the users to store their personal information.

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

Table 8. Elements of the domain model
Element Meaning

User

Representation of users who are logged in.

Product

Representation of socks of the on-line shop.

Availability

Save the stock and size of the product.

OrderProduct

Represents products in orders.

Order

Represents confirmed orders.

DistributionCenter

Represents distribution centers that are in charge of send orders.

8.2. Architecture and Design Patterns

MERN Stack Architecture

MERN Stack is being used in the application which allows to easily create 3-tier architecture.

  • React.js is used to work with the presentation layer.

  • Express.js and Node.js are used to make up the middle or application layer.

  • MongoDB is used to create the database layer.

8.3. Package Structure

8.3.1. Level 1

Package level 1

The project is named dede_5a and contains the following main folders:

  • docs is the folder that stores the files related to this documentation.

  • restapi is the folder where the REST API that obtains data from the database is.

  • webapp is the folder that stores everything related to the application itself.

8.3.2. Level 2

Package level 2

restapi mainly contains:

  • routes defines API endpoints and they are separated by database collections.

  • models are representations of the data in the database.

  • services contains global services like database connection.

webapp mainly contains:

  • public is the folder where the static and necessary resources for the application are located: images, scripts, etc.

  • src contains the code part.

    • api contains calls to REST API to get data.

    • components are UI components that can be used across various files in the project.

    • contexts contains the state which has to be shared across these components.

    • helpers contains commonly used functions in the project.

8.4. User Experience (UX)

A good User Experience is a key aspect for the success of the application. The application must satisfy the needs of the users effectively. For this, several concepts must be taken into account when designing user interfaces like:

  • Usability

  • Accessibility

8.4.1. Usability

Throughout development, usability tests are carried out on different users. Each test consists of small tasks that test the implemented functionalities.

Thanks to the user’s interactions with the application, usability problems can be detected and it makes it possible to make improvements in this regard.

Usability problems make the application difficult to use and understand for users. So, it is important to avoid or reduce it.

8.4.2. Accessibility

There are different standards to follow to achieve accessibility. One of the standards is WCAG 2.0 (Level AA) which is the most used worldwide. Therefore, it is the one used in this application.

Tools to use are:

8.4.3. User interface

User interfaces should be designed with usability and accessibility in mind.

Mockups

They may not exactly match the final design, but they offer an idea of the functionality and design of the pages that the application will have.

Navigation between pages

8.5. Security

Security is another key aspect to consider. Some measures to ensure security are:

  • The application does not store private data of the user. To obtain it, the application asks the user for permission to access the Solid POD where the data is stored at the time it is needed. In this way, control of the user’s own data is guaranteed.

8.6. Availability

To achieve high availability:

  • On the one hand, try to avoid making software errors by applying the code review process by other team members. The process is carried out before joining the new code with the code that already works correctly.

  • On the other hand, enable autoscaling on the application’s service providers in case of anticipating the success of the application.

  • Moreover, we will try to have more than one deployment technology in order to increase a high availability.

8.7. Efficiency

Try to have a good code quality for better performance. We will develop many load tests which are going to simulate the state of the application as it were deployed and used by many users. There are many tools to prove that. Gatling will be the reference tool to get information of the behaviour of the app. Results will be shown in the wiki which is available in our repository in GitHub. You can follow this link

8.8. "Under the hood"

8.8.1. Persistency

The database management system used is MongoDB and the main reason is the easiness of data passing between the database and the application based on node.js. Another reason is the feature it offers: flexible schema.

8.8.2. Session handling

A node.js module, express-session, is used to handle the application session. There are many reasons:

  • Easy to incorporate into the project as it is a node.js module.

  • The session of this module is stored on the server, therefore it is more secure.

8.9. Operation concepts

8.9.1. Logging

Users just need to log in to any Solid Pod provider to use the app. There are several advantages:

  • The user does not have to register an account in the application. So he does not have to remember the password.

  • Developers do not have to deal with passwords.

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

9.1. MERN Stack usage

Context

We need a set of different technologies and frameworks that can work well together in order to build our project.

Decision

As we are restricted to use the React framework, we might as well use these technologies (MongoDB, Express and Node.JS) knowing that there is a lot of information about them working together.

Status

Accepted.

Consequences

Having this much information about how to combine these technologies will help the team during the development to create a much more robust application.

9.2. Login with Solid

Context

The constraint of Solid use in order to keep client’s privacy has to be done. We need something to manage the use of his data. Client must allow us to use his data when we are creating an order for example, address which is necessary to process those events.

Decision

While looking for alternatives to solve this problem we found out that making a login system based in Solid was the best way. From our point of view, this decision is the easiest and also the most natural for the user while using the webapp.

Status

Accepted.

Consequences

This decision will improve the simplicity of the system because we will not have the need of developing an authentication system. We will only manage webIds from Solid and roles so that we will not store client’s personal info, usernames and passwords. Solid will be the responsible of users' accounts and credentials.

9.3. Shopping cart in session

Context

Every e-commerce platform need a shoping cart where client can see his selection while preparing a purchase. In the same way, we have to take the decision of saving this data among many options such as database, user’s session…​

Decision

Finally we tend to develop it using the session instead of database. It is more natural and it is also the most realistic solution.

Status

Accepted.

Consequences

This decision avoids us from having an entity called shopping cart and also the risk of collapsing the database with a lot of modifying operations. We understand that the cart is something depends on client’s session and it is very related to him so it should not persist when the client is not in the session.

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.

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.

mindmap

10.2. Quality Scenarios

Contents

Concretization of (sometimes vague or implicit) quality requirements using (quality) scenarios.

These scenarios describe what should happen when a stimulus arrives at the system.

For architects, two kinds of scenarios are important:

  • Usage scenarios (also called application scenarios or use case scenarios) describe the system’s runtime reaction to a certain stimulus. This also includes scenarios that describe the system’s efficiency or performance. Example: The system reacts to a user’s request within one second.

  • Change scenarios describe a modification of the system or of its immediate environment. Example: Additional functionality is implemented or requirements for a quality attribute change.

Motivation

Scenarios make quality requirements concrete and allow to more easily measure or decide whether they are fulfilled.

Especially when you want to assess your architecture using methods like ATAM you need to describe your quality goals (from section 1.2) more precisely down to a level of scenarios that can be discussed and evaluated.

Form

Tabular or free form text.

Reference

Atribute

Scenario

Priority

Dificulty

QS.1

Confidenciality

User’s personal data is retrived from their Solid pod.

High

Medium

QS.2

Confidenciality

Only the data necessary for the correct operation of the application will be accessed. (Name, address and profile photo).

High

Medium

QS.3

Availability

The application will be available the majority of time, specially at client reviews. System availability will always be above 97%, with about 15 hours of maintenance every three weeks.

Medium

High

QS.4

Usability

Project documentation shall be kept up to date and consistent with the project. Changes will be made as soon as something changes, and this will be checked with a review every two weeks.

Medium

High

QS.5

Usability

The application must be intuitive and easy to use. This will be verified by testing with different user profiles.

Medium

Medium

QS.6

Accesibility

The web application must pass the AA level in Achecker

Low

High

QS.7

Efficiency

The system will have a response time of less than 0.5 seconds.

Low

Very High

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.

Table 9. List of risks
Nº Risk Explanation Measures

1

Abandonment of a team member

It can be caused by different reasons such as personal or organizational problems.

Do not leave an important task or module for a single person.

2

Not enough experience on technologies which we need to use.

These technologies are Typescript, React, Node.js, Express and SOLID.

Investigate more about these technologies and practice by following tutorials or online courses. There are also materials provided by teachers.

3

Problems with git

Team members can have conflicts when merging branches.

Make sure the result is what we expect before running unknown commands. To do this, we can consult the official documentation or ask other members of the team.

4

Lack of time

This risk is closely related to the others. In addition, team members also have other subjects besides this one.

Combine the completion of this work with the rest of the subjects.

5

Unproductive meetings

It can be caused by not making preparations before meetings.

Have a list of topics to talk about during the meeting.

6

Lack of communication

The communication is not immediate in most of the time because team members have different schedules.

Team members need to be more collaborative. Another measure is to take advantage of scheduled meetings.

7

English

It is not the usual language of the team members. Then this documentation can have linguistic errors.

Use the free online dictionary and language error detection tools.
Table 10. List of technical debts
Nº Technical debts Explanation Measures

1

Security

There are many paths which should not be accesible for some users.

Checking paths and improving role system in order to check and revert those dangerous requests. These will improve security and decrease hacking risks.

2

Versions

During development we have used some old versions which have been quite useful. Npm has report many vulnerabilities, there are 6 moderate vulnerailities while installing webapp dependencies

Updating dependencies in order to reduce those vulnerabilities which could be dangerous for application’s security.

3

Azure deployment

Configuration files are created but deployment could not be finished correctly due to many problems of GitHub actions while creating a release

We will try to solve all this problems. However, webpage has been deployed using Heroku and now is available. Trying to have both deployments will be a challenge for us in order to reach some quality goals such as availability.

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

It’s a version control software designed by Linus Torvalds, thinking about the efficiency, reliability and compatibility of application version maintenance.

Github

Is’s a platform for hosting projects using the Git version control system.

Solid

It’s a specification that allows customers to store their data securely in decentralized data stores.

Solid Pod

Pods are where you store your data. Any kind of data can be stored in a Solid Pod. Once stored in a Pod, you control who can access your data.

REACT

It’s an open source Javascript library that allows you to easily create interactive user interfaces.

Typescript

It’s a Javascript-based web programming language that adds static typing.

DBMS

DataBase Management System is a software that is used to store and retrieve data from a database.

IDE

Integrated development environment is a software that provides facilities to developers.

GUI

Graphical User Interface.

Usability tests

Usability tests is a testing technique to evaluate the functionality of a software product that consists of proposing tasks to real users and observing how they perform it.

Deployment

All the processes and activities that make a software system available to its users.

Accesibility

The attribute of being easy to meet or deal with especially for disabled clients

Confidentiality

The ethical principle or legal right that a physician or other health professional will hold secret all information relating to a patient, unless the patient gives consent permitting disclosure.

Efficiency

The ratio of the effective or useful output to the total input in any system.

Usability

The degree to which an object, device, software application, etc. is easy to use with no specific training.

Availability

The quality of being at hand when needed.

Node.js

An open-source and cross-platform runtime environment on the server-side. It is based on Google’s V8 JavaScript engine, which is designed to execute JavaScript code very quickly.

JavaScript

A programming language used both on the client side and on the server side. JavaScript allows the interaction between web pages.

Express

A web application framework for Node.js used for building web and mobile applications.

Merge branches

The process of incorporating any changes in a branch to another branch.

Achecker

Webpage that allow as to check webpage accessibility using level AA

dotenv

Library from npm used to get environment variables that should not be exposed to the public. API keys, passwords, database links, ports…​ In this way .env files should not be in the repository in GitHub

mui

Npm library used to optimize the development of GUI. It gives us a lot of improvements while creating buttons, panels and many other things. The link to the webpage can be found here.

mongodb

Official mongodb driver for Node.js. Usage documentation can be found in this webpage.

mongoose

Object modeling tool designed to work in an asynchronous environment. Mongoose supports both promises and callbacks. Here is the link to the documentation.

inrupt/solid-ui-react

Module which improves the development of applications using react and Solid architecture. The link to the documentation is here.

node-fetch

Module which is useful to make requests to other web services. Here is the link to the documentation.

MapsAPI

Api which helps to calculate distances between the client and the distribution center. We will use Mapbox in order to implement these features. Here is the documentation.

MongoDB Atlas

Service supported by mongoDB which allows the application to externalize the data storage. Data is stored using serverless architecture managed by mongoDB with AWS, Azure or Google Cloud. MongoDB Atlas.

Mockup

A static design of a web page or application that shows general layout and functionality.

MERN

MERN stands for MongoDB, Express, React and Node.

3-tier architecture

It is a client-server architecture which separates the application into three logical and three physical tiers: presentation tier, application tier and data tier.

WCAG

Web Content Accessibility Guidelines

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.