About arc42

arc42, the template for documentation of software and system architecture.

Template Version 8.2 EN. (based upon AsciiDoc version), January 2023

Created, maintained and © by Dr. Peter Hruschka, Dr. Gernot Starke and contributors. See https://arc42.org.

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,

  • essential functional requirements,

  • quality goals for the architecture and

  • relevant stakeholders and their expectations

This project’s aim, in summary, is developing a public web application which has a game consisting on answering multiple choice questions with one correct answer generated using Wikidata. For reference of the general mechanic, see the spanish quiz program 'Saber y Ganar' and its game mode 'Descartando'

Next, important basic aspects of the project will be described in order to give context on how the webapp will be developed.

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.

Further Information

See Introduction and Goals in the arc42 documentation.

The functional requirements are the following:

  • The application must be accesible through the web

  • Users must be able to register into the system

  • Users must be able to see data about their past games (score, correct/wrong answers, number of questions answered…​)

  • Questions must be automatically generated from Wikidata.

  • Questions must be answered before some specific time.

  • Each question must have one right answer and several incorrect ones or distractors. Both the right answer and the distractors should be automatically generated.

  • The system must give access to the information about the users through an API.

  • The system must give access to information about the generated questions through an API.

The functional requirements have been grouped into the different microservices the web application will have:

1.1.1. User and Authorization Services

  1. The User service allows the user to

    1. Register

  2. The authorization service allows the user to

    1. Log in

1.1.2. Ranking Service

  1. A user can retrieve the following information from the Ranking service

    1. Points scored

    2. Number of questions answered

    3. Correct answers

    4. Incorrect answers

  2. The system must be able to manage the user’s access to the system

1.1.3. Question Service

  1. The question service provides the following functionallities

    1. Generate a random question from a given category with 4 options

    2. Validate the answer and update the score accordingly

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.

Consider this overview of potential topics (based upon the ISO 25010 standard):

Categories of Quality Requirements
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

Goal Description

Testability

Test will be developed, so the application has a good quality.

Usability

The application has to be intuitive for its users.

Portability

The application works in different devices and browsers. With different screen sizes.

Performance

The application can handle a big number of users and give good response times.

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/Name Members Expectations

Students

Andrés Cadenas Blanco, Christian Fernandez Noriega , Adrián González Guadalupe and Luis Salvador Ferrero

Are the ones in charge of web development. They will work together to make the application.

Teachers

Pablo González

In charge of supervising the student’s teamwork, ensuring the work accomplishes the goals in the best way possible and helping in the development and solving doubts.

Users

Anyone that wants to use the web

They should be able to understand how to use and move around the web with ease

2. Architecture Constraints

Contents

Any requirement that constraints 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)

Further Information

See Architecture Constraints in the arc42 documentation.

Architects need a clear understanding of the areas where they have creative freedom in their design choices and where they are bound by constraints. These constraints must be addressed comprehensively, as they are non-negotiable factors within the project. However, it’s important to recognize that while constraints are rigid, there may be room for negotiation and adaptation within them.

Constraints Explanation

GitHub

It will be used to coordinate the projects work, tracks changes and manage workflow.

Documentation

In order to keep it clean, efficient and simple, it will follow Arc42 method and be deployed to be able to look at it at any time.

Deployment

The project has to be deployed when a release is made

Time

Since the project will be done in this semester our time is limited, and we need to stick to the deadlines and manage our time in an efficient way.

Testing

We need to have a good coverage of unitary testing (80%+) and some acceptance testing covering all the webapp functionallity

Wikidata

It has to be used for the question generation.

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.

Further Information

See Context and Scope in the arc42 documentation.

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.

The player is the only actor in the main system, which is the one that makes use of the different APIs that will be described later. The player can initially interact with the authentication system to either register or login and then, by playing the game, the question service will be triggered for either generating the questions or validating the player’s answer. The player can also access data about the past games of all users in a ranking.

Context Diagram
Element Description

Player

Plays the game and can consult past scores

WIQ Game

Main system in which generated questions are shown and can be answered by players

Wikidata

External data repository from which questions are generated

Users Info API

Manages data of users, both registration/login data and their past scores

Questions API

Manages generation of questions from Wikidata

MongoDB

Database for storing players' info and scores

4. Solution Strategy

The web application is based on MERN stack, a full-stack combination of technologies for developing JavaScript applications fast.

  • Node: the JavaScript runtime environment.

  • MongoDB: chosen technology for the persistance of the system, that provides a non-relational database approach.

  • Express and Node: they make up the middle tier of the application, providing a powerful server platform.

  • React: front-end framework that will solve the client interfaces of the application.

Regarding the deployment of the application, the strategy chosen is a cloud-based system. This decision was motivated because of the nature of the project, since a web application needs to be live and accesible at any moment. The server will be an ARM Linux VM on Oracle, where some dockerized microservices will be deployed:

  • users service

  • authentication service

  • questions service

  • web application

  • gateway

Contents

A short summary and explanation of the fundamental decisions and solution strategies, that shape system architecture. It includes

  • 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 foundation for many other detailed decisions or implementation rules.

Form

Keep the explanations of such key decisions short.

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

Further Information

See Solution Strategy in the arc42 documentation.

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, data 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.

Further Information

See Building Block View in the arc42 documentation.

The system is based on having a player interact with a GUI which makes use of different APIs that hold most of the important functionallity

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.

Whitebox overall system
Motivation

We made the decomposition separating the functionallities (The names are self explanatory but components will be described later)

Contained Black boxes
Name Responsibility

WIQ Game GUI

Main window in which questions are shown and can be answered by the player. The latter can also see past scores.

questions API

In charge of generating the questions and validating the answer

UsersAPI

In charge of keeping track of the data of the users (registration and scores)

Wikidata

External element used for the generation of questions

Insert your explanations of black boxes from level 1:

If you use tabular form you will only describe your black boxes with name and responsibility according to the following schema:

Name Responsibility

<black box 1>

 <Text>

<black box 2>

 <Text>

If you use a list of black box descriptions then you fill in a separate black box template for every important building block . Its headline is the name of the black box.

Here you describe <black box 1> according the the following black box template:

  • Purpose/Responsibility

  • Interface(s), when they are not extracted as separate paragraphs. This interfaces may include qualities and performance characteristics.

  • (Optional) Quality-/Performance characteristics of the black box, e.g.availability, run time behavior, …​.

  • (Optional) directory/file location

  • (Optional) Fulfilled requirements (if you need traceability to requirements).

  • (Optional) Open issues/problems/risks

5.2. Level 2

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

You have to decide which building blocks of your system are important enough to justify such a detailed description. Please prefer relevance over completeness. Specify important, surprising, risky, complex or volatile building blocks. Leave out normal, simple, boring or standardized parts of your system

5.2.1. Questions API (White Box)

This is the Component that holds the functionallity for the main purpose of the webapp: Allowing players to see questions and answer them, getting a consequent score update.

…​describes the internal structure of building block 1.

Questions API (WhiteBox)
Motivation

We made the decomposition separating the functionallities.

Contained Black boxes
Name Responsibility

question-service

Receives different petitions regarding the generation of questions and validation of answers and responds accordingly.

wikibase-sdk

External library that facilitates and simplifies the use of wikidata for the generation of questions.

6. Runtime View

6.1. User authentication

  • Users will log in through the web interface of the application.

  • The system stores in database (MongoDB) the users of the application. Any data relative to them is accessed via the database of the system and displayed to them on the web interface.

6.2. Rankings

  • Users can see the rankings for a specific category

rankings diagram

6.3. Playing

  • An overview of the runtime scenario of a game.

playing diagram
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

  • …​

Further Information

See Runtime View in the arc42 documentation.

7. Deployment View

Content

The deployment view describes:

  1. 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. 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 a deployment view if your software is executed as distributed system with more than 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 only those elements of an infrastructure that are needed to show a deployment of your building blocks. Hardware architects can go beyond that and describe an infrastructure to any level of detail they need to capture.

Motivation

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

Form

Maybe a 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 one can 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 a deployment diagram, let them use any kind that is able to show nodes and channels of the infrastructure.

Further Information

See Deployment View in the arc42 documentation.

7.1. Infrastructure Level 1

An overall of the infrastructure elements used to execute the system can be seen in the following diagram.

Deployment view L1

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

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

  • important justifications or motivations for this deployment structure

  • quality and/or performance features of this infrastructure

  • mapping of software artifacts to elements of this infrastructure

For multiple environments or alternative deployments please copy and adapt this section of arc42 for all relevant environments.

The gateway service works as an adapter between the micro services and the web client. The web application is the main interface for the user to interact with the system. The wikidata API is used to fetch data from wikidata to generate questions. We must consider the gateway service a black box.

7.2. Infrastructure Level 2

Here you can include the internal structure of (some) infrastructure elements from level 1.

Please copy the structure from level 1 for each selected element.

7.2.1. WIQ Server

Deployment view L2

The architecture of WIQ is based on microservices. Gateway service is the main entry point for the system. The web application is the main interface for the user to interact with the system. The user service is responsible for managing users. The authorization service is responsible for managing user permissions. The question service is responsible for generating questions. The mongo database is used to store data.

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

  • models, especially domain models

  • architecture or design patterns

  • rules for using specific technology

  • principal, often technical decisions of an overarching (= cross-cutting) nature

  • 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.

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
Further Information

See Concepts in the arc42 documentation.

8.1. Continuous integration and development

Our way of working with github is having one developing branch towards which all pull requests are done and have to be reviewed by at least one team member. Sonar Cloud is set up so we know the testing coverage and whether we pass the quality gate with every pull request. Once there is enough change in the develop branch with respect to the main one and it has enough quality we can merge them and make a release.

8.2. Microservice based system

Different business functionallities will be developed in different independent services. This will ensure that if one of them fails, the rest are still working (For example, if the rankings go down that will not affect the main game) as they have their own deployment as well. Other benefits are increased maintainability due to separation in small, more readable modules and the possibillity of using different languages or technologies for each module if needed/prefered without colliding with the rest.

8.3. Gateway service routing

We will use a speciallized service that will route the requests to the corresponding service, acting as a single entry point for the application. Requests to the services are much simpler as only the api base endpoint and the action needs to be known and the gateway can also act as a filter to manage requests conditionally if needed. This approach also favors security as we can control which requests are actually sent based on its content or the context of the app.

9. Architecture Decisions

Contents

Important, expensive, large scale or risky architecture decisions including rationales. 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:

  • ADR (Documenting Architecture Decisions) for every important decision

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

  • more detailed in form of separate sections per decision

Further Information

See Architecture Decisions in the arc42 documentation. There you will find links and examples about ADR.

What we have to decide Options/Proposals - Reasoning Status Decision - Reasoning

Which cloud service provider to use for deploying the webapp

Oracle Cloud - We have access to a VM with this provider with 24/7 free activity

Decided

Oracle Cloud - All advantages

Infrastructure design

Oracle ARM VM with multiple containers inside - Running containers in this VM is free

Decided

Oracle ARM VM with multiple containers inside - It is free

What CI/CD pipeline should we use

Github Actions - Already integrated in the project and fits perfectly our needs for deployment, developing and testing. Azure DevOps - It is more integrated with Azure cloud, where we could have our infraestructure deployed with Terraform using IaC.

Pending

Azure Devops would be a better approach for deploying our infraestructure in Azure containers (serverless) using IaC with Terraform, but there is a lack of time for migrating and GitHub Actions is already integrated and working fine.

Local or cloud data base

Local - There is no need to externalize things that should keep local.

Decided

Local database - Database is kept in local for security reasons and for not overdesigning the infraestructure

New microservice for Rankings

Removing ranking logic from users microservice - It might be a better design as user logic and ranking logic is not exactly the same.

Decided

Keep rankings logic in users microservice - It would make sense to separate services if they scaled too much but in this project this would be overdesign.

Which technologies are we going to use for developing the front end

React - It is a modern framework which is easy to learn and provides usefull predefined components that save time

Decided

React - We have a reference already implemented and its capabilities are what we need

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.

Further Information

See Quality Requirements in the arc42 documentation.

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.

The Quality Tree of the project

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.

10.2.1. Usage Scenarios

Quality goal Motivation Usage scenario Priority

Testability

Test will be developed, so the application has a good quality.

The coverage should be higher than 70% and SonarCloud should give a pass in unit tests

High

Usability

The application has to be intuitive for its users.

Users don’t like to spend a lot of time trying to understand how to use an application. Therefore when they want to do something, they want to know where to go and what to do.

Very high

Portability

The application works in different devices and browsers. With different screen sizes.

Users connect from different devices and browsers, we should ensure that the application works in all of them.

Medium

Performance

The application can handle a big number of users and give good response times.

The application should be able to stand at least 10 users simultaneously and give a response time of less than 20 seconds.

High

10.2.2. Change Scenarios

Quality goal Motivation Change scenario Priority

Maintainability

An application should be easy to update and maintain by the dev team. Respecting the architecture of the web application and the continuous integration.

If a developer wants to add a feauture or include a hotfix, he should be able to do it without major consequences on the system, always respecting the architecture of the web application.

High

Maintainability

An application should be easy to update and maintain by the dev team. Respecting the architecture of the web application.

As there is continuous integration, when fixing a bug or adding a feature, if an error is found, the application won’t be affected as changes won’t be applied.

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.

Further Information

See Risks and Technical Debt in the arc42 documentation.

Risk/Technical debt Why it exists Severity - Explanation Possible solutions

Use of wikibase-sdk version 8 (not final)

It is the last version that supports 'require', which is needed to use express in the same module

Low - The difference is, a priori, merely functional, but retains the needed characteristics

Upgrade only if a newer version supports 'require'

Lack of a security barrier for DDOS attacks

Lack of knowledge and time for implementing it into the project

A DDOS attack can make the application crash

Integrate CloudFlare into the project

Questions types

The design was optimized for image based questions and adding new categories easily.

It would be difficult to add questions that do not rely on images. For example, text based questions.

Refactoring questions microservice to include new types of questions.

12. Tests Report

Tests Status

Unit tests

Passing (85.3% coverage)

e2e tests

Passing

Load tests

Max ~240 users

13. 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.

Further Information

See Glossary in the arc42 documentation.

Term Definition

Microservice

Small and independent component that performs a specific business function

CI/CD pipeline

A series of steps that are carried out to obtain a new software product from its development phase to its deployment

ARM

A type of processor architecture designed for power efficiency

MERN stack

A group of web technologies for developing web applications: MongoDB, Express, React and Node

Docker containers

Packets that include all the software needed for running a service

Oracle Cloud

Cloud infraestructure provider (e.g Virtual Machines)

Gateway

All the endpoints visible for the client, that will redirect to specific microservice API

API

Set of endpoints exposed by the backend server whose purpose is interacting with the client-side