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

1.1. Introduction

WIChat is a project that, following the path of the application developed in the past by the HappySw company, seeks to implement top-notch technologies to take the user experience to the next level when playing this online version of the famous quiz show “Saber y Ganar”. The project is developed by the company ChattySw, and the development team consists of the following programmers:

2. Team Members

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

To achieve this enhanced application experience, its main functionalities are:

  • User Registration and Participation History: Each user will have a personal account where their game data will be stored, allowing them to view their progress at any time.

  • Question and Answer System based on Wikidata: The various questions, accompanying images, and answer options will be generated based on information gathered from Wikidata.

  • Chatbot and Hint System: The user will have the optional functionality of a chatbot that, upon request, will provide a series of hints based on information retrieved from Wikidata, guiding them towards the correct answer without revealing it outright.

  • User Interaction with the Application: The user will interact with the application through a highly intuitive and user-friendly web front-end.

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

Quality Goal Description

Usability

The interface should be intuitive and user-friendly to ensure the user can navigate the application optimally.

Performance

The system should deliver responses within an acceptable time frame to ensure fast and efficient game sessions.

Accuracy

The hint generation mechanism should minimize errors and hallucinations to maximize the chatbot’s functionality.

Scalability

The architecture should allow easy updates and feature expansions, making it adaptable for future improvements.

Security

Because user well-being and comfort are of paramount importance, user data and interactions must be properly managed and protected.

2.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 Description Expectations

RTVE

The client commissioning the development of the updated application.

Get a fully functional app that enhances the existing one by using AI Chat bot.

ChattySw

The software development company responsible for taking the project.

Being able to meet the client’s needs on time and without any inconvenience.

API providers

WikiData and LLM Service.

The external service providing information and the LLM for hint generation.

Final users

General players who will use the WIChat application for entertainment and learning.

Being able to use the application without any impediment and enjoy and learn thanks to it.

Development team

The team responsible for developing the application, consisting of the previously mentioned members.

Develop the application and improve their communication and teamwork skills, taking a step forward toward their professional future.

Evaluators (Teachers)

The people who will oversee and evaluate the application and its correct development.

Keep track of project development, resolve development team issues, and evaluate the final product.

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

3.1. Technical Constraints

Restriction Explanation

Wikidata API

We will use Wikidata as the database for the places where the player can be found.

Deploy the application

The application must be deployed on a server and accessible from a browser. In this case, we will use Docker to deploy it.

GitHub

We will use GitHub for version control and collaboration on the project.

Tests

The application must pass these tests to ensure its functionality; failure of any test will block deployment.

Documentation

The documentation of the entire project will be done following the Arc42 template for better clarity in its details and explanations.

3.2. Organizational Constraints

Restriction Explanation

Team of 4 people

The work will be distributed among the 4 members of the group.

Reports

Every week during the class practice time, we must write minutes documenting what we have done and the next steps to follow.

Issues

The work assigned to each member will be reflected as issues in GitHub, so that everything is recorded and everyone knows what they have to do.

Mid-term evaluations

Every 3 weeks the project will be checked, and corrections that need to be made for the upcoming days will be noted.

Wichat is a trivia-like game that retrieves information from Wikimedia and uses it to ask users questions accompanied by images. It also features its own trained AI chatbot to assist users by providing hints.

4. Context and Scope

Overall System
Contents

Context and scope - 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.

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

Communications Ins Outs

User

Interactions with the application

Responses to said interactions.

Wichat

WikiData information

Various information received from the APIs and the database.

Wikidata

Requests by the application

Responses to said requests with the information stored in Wikidata.

AI chat bot

Questions by the user

Responses in text format with hints about the user’s question, from Wikidata.

4.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 which 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.

Technology Description

JavaScript

Language used for most of the back end development.

React

For user interfaces.

Wikidata

Information base used to formulate questions.

MongoDB

Database used to store question data.

GitHub

Code collaboration platform.

Empathy

AI help bot.

Local server from ElPandaP

Web host.

5. Solution Strategy

5.1. Technologies

  • React: JavaScript library for web and native user interfaces. It allows developers to create interactive web applications by breaking down the UI into reusable components. React uses a declarative approach to efficiently update and render components, resulting in faster and more maintainable code. It’s widely adopted in the industry due to its simplicity, performance, and robustness.

  • Node.js: JavaScript runtime that enables running JavaScript code outside of web browsers. It’s renowned for its event-driven architecture and extensive collection of packages, making it ideal for building scalable server-side applications.

  • Wikidata: Wikidata provides a REST API for retrieving information related to any topic. It helps us to dynamically generate questions for our game using it from any programming language.

  • MongoDB: popular NoSQL database known for its flexibility and scalability. It stores data in flexible JSON-like documents and is widely used in modern web development for its simplicity and ability to handle large volumes of data.

  • Arc42: framework (template) used for documenting and communicating software architectures. It provides a template for describing the architecture of a software system, covering aspects such as stakeholders, requirements, architecture decisions, components, interfaces, and quality attributes. arc42 helps teams create consistent and comprehensible architecture documentation, enabling better communication, understanding, and maintenance of software systems throughout their lifecycle.

  • npm: default package manager for Node.js, providing a command-line interface to install, manage, and publish JavaScript packages. With over a million packages available in its registry, npm simplifies adding functionality to Node.js projects by handling dependencies and providing tools for versioning and publishing packages.

  • Docker: platform that will be used for deploying our services inside containers. Containers are lightweight, portable, and self-sufficient units that contain everything needed to run an application, including the code, runtime, system tools, libraries, and settings. Docker enables developers to package their applications along with all dependencies into containers, ensuring consistency across different environments, such as development, testing, and production.

  • GitHub Actions: built-in automation tool on GitHub that allows us to automate some workflows that are triggered after some specific github branches actions at development. It provides as continuous integration of the game functionality.

  • GitHub: Version control and project management platform used for managing our game project. GitHub provides features for collaboration, issue tracking, and code review, facilitating efficient development workflows and team communication.

5.2. Technological decisions

We have decided to develop the Wikidata API in TypeScript because it is similar to JavaScript but also has static type checking.

5.3. Architecture & Design

  • Microservices: Our game is built using a microservices architecture, which structures the application as a collection of loosely coupled services. Each service encapsulates a specific functionality or business capability, allowing for independent development, deployment, and scaling. By adopting microservices, we promote modularity and flexibility, enabling rapid iteration and innovation.

  • Containerization with Docker: We leverage Docker containerization to package each microservice and its dependencies into lightweight, portable containers. Docker provides a consistent environment across different stages of the development lifecycle, ensuring seamless deployment and scalability. With Docker, we can easily spin up new instances of services, manage dependencies, and streamline our development and deployment workflows.

  • API Gateway: We employ an API gateway as a centralized entry point for all client requests to our microservices. The API gateway serves as a reverse proxy, routing incoming requests to the appropriate microservice based on predefined rules and policies. It provides a unified interface for clients to interact with our system, abstracting away the complexities of the underlying microservices architecture. By consolidating access through the API gateway, we enhance security, governance, and performance while simplifying client interactions.

  • Scalability and Elasticity: With our microservices architecture orchestrated with Docker, we achieve horizontal scalability and elasticity to handle fluctuations in traffic and workload. Docker’s container-based approach enables us to dynamically scale individual services based on demand, ensuring optimal resource utilization and cost efficiency. Combined with automated scaling policies and monitoring, we maintain responsiveness and availability during peak usage periods.

5.4. Team Organization

For developing this project we are using Github as the control version systems. The master branch contains the final version of the product, so that every accepted pull request to master branch will be considered as a new release.

  • Documentation: it must be always updated for making our work valuable and consistent.

  • Weekly meetings: Weekly discussions about what has been done and what needs to be done will be key for our team success.

  • Github: this control version systems not only allows us to share and collabortively write code, but also provides other resources such as issues and project management (kanban board) tools for organizing the work to be done. Also, wiki section allows us to save all of our minutes from each scheduled meeting.

  • Whatsapp and Discord: will allow us to be in constant communication for helping each other out whenever needed.

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.

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

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

Once we have made progress in the development of the application, the following diagrams should be created according to the chosen implementation

6.2. Registering an user

Scenario 1: Registering as a new user or log in as an existing user.  

Runtime view - Registering User

 

When a new user registers, the process starts on the front end, where they enter their details. The front end then sends this information to the back end, which validates it, ensuring, for example, that the username isn’t already taken and meets minimum length requirements. Once the data is verified, it is stored in the database, then the user is finally notified that their account has been succesfully created and they can low log in.

6.3. Logging in

 

Runtime view - Logging in

 

When it comes to logging in, the user firstly enters their credentials, then the back end retrieves the user’s information from the database and verifies if it’s correct.

6.4. Future diagrams

Once we have made progress in the development of the application, the following diagrams should be created according to the chosen implementation:

6.4.1. Questions generation

6.4.2. WiChat quiz game

6.4.3. Obtaining hints via Chatbot

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

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.

Deployment View
Motivation

The deployment diagram provides a clear overview of the system’s architecture, illustrating how its components interact and are distributed. It helps visualize the structure within Docker, showing the connections between the web server, database, apis and client.

Quality and/or Performance Features

By deploying the application in Docker, we achieve a consistent and portable environment, reducing compatibility issues across different infrastructures. To enhance performance, the system leverages cloud services, optimizing resource usage and ensuring availability. The architecture is designed to handle multiple requests efficiently, maintaining low latency and high responsiveness for users.

Mapping of Building Blocks to Infrastructure

The application is deployed in a Dockerized environment, running on a web server that connects to a cloud-hosted database. The client-side interacts with the server via HTTP, while the backend communicates with the wikidata and the selected AI using their respective APIs and manages the database. This setup ensures scalability, reliability, and efficient resource management.

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.

8.4. Authentication

To keep our users' data secure an authentication mechanism has been developed with the use of JSON Web Tokens (JWT). If someone tries to access historical game records for certain users, our KaW application enforces to pass a valid token through the header of the message request. In this way, only authenticated users are able to consult the different data that our application enforces.

8.5. Internationalization

One of the things to increase accessibility is giving our application the capability of being in various languages so people around the world can play our game. Obviously, internationalization is more than just changing the language of the Application but due to time constraints we will just offer Spanish, English, Ukrainian and French languages ( although, our API can generate questions in other languages different from described, to see the whole list, refer to our API documentation ).

The library used for language translation in our KaW game is called react-i18next. For simplicity (and due to just only having three languages), all of the translations of messages are stored locally in properties files. Eventually, if the Application grows and we wanted to have more than 4 languages the best approach is to store those properties in a server and let the application to request those on the fly. Again, for simplicity the option of having all bundle together in the Frontend just fits.

The translation of questions is a bit different from the frontend part since it is done "on the fly" by using the Microsoft translation API . This change has been done since the questions are not fully known until they are generated so storing the translation locally does not provide any benefit. Also, one advantage of it, is its simplicity and ease to use. To meet the restrictions impose by the Free version of this API a series of formatting rules are carried out into the question generation phase to minimize the usage of it and avoid getting suspended.

8.6. Tests

One of the most important aspects is testing our application, and to achieve this, we will conduct different types of tests. On one hand, we will perform tests such as unit testing and usability testing. On the other hand, we will implement a continuous testing system using GitHub Actions, ensuring that all commits pass the required tests.

9. Architecture Decisions

The application will be carried out following a Microservices architecture.

The service in charge of comunicating with WikiData will be coded using TypeSript. As the generation of questions is a huge part of our application we will play it safe by using TypeSript, a language that is similar to JavaSript but with static type checking.

03/02/2025

Microservices Architecture: The application will follow a Microservices architecture to ensure scalability, flexibility, and easier maintenance. This approach allows different services to be developed, deployed, and scaled independently, improving fault tolerance and facilitating continuous deployment.

WikiData Service - TypeScript: The service responsible for communicating with WikiData will be developed using TypeScript. Since generating questions is a critical part of our application, we decided to use TypeScript due to its static type checking, which helps prevent runtime errors and makes the codebase more maintainable. Additionally, TypeScript provides better tooling support and improves developer productivity by reducing debugging time.

Backend & Frontend Technologies: The backend will be built using Node.js, as it is efficient for handling asynchronous operations and provides a vast ecosystem of libraries. The frontend will be developed with React, a popular JavaScript library known for its component-based structure, performance optimizations, and reusability. React’s virtual DOM improves rendering efficiency, making it a great choice for dynamic applications.

Database - MongoDB: We have chosen MongoDB, a NoSQL database, because it provides flexibility in handling unstructured data, horizontal scalability, and high availability. Given that our data structure may evolve over time, MongoDB’s schema-less nature allows us to adapt without complex migrations.

Deployment Strategy: The application will be deployed on a server owned by one of the team members. This decision allows us to have full control over the deployment environment, reduce costs, and customize configurations based on our needs.

03/03/2025

Switching from TypeScript to JavaScript: We initially opted for TypeScript to improve code quality through static typing. However, after encountering integration issues, increased complexity, and longer development time, we decided to switch to JavaScript. JavaScript allows for faster iteration, broader community support, and reduced setup overhead, making it more practical for our project timeline.

CSS Modules for Styling: We have chosen to use CSS Modules for styling because it:

Prevents style conflicts by scoping styles to individual components. Improves maintainability by keeping styles modular and easy to manage. Enhances reusability as styles are encapsulated within their respective components, reducing the risk of unintended global overrides.

These decisions were made to optimize performance, maintainability, and scalability while ensuring smooth development and deployment of our application.

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.

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

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.

10.2. Quality Scenarios

Prority Quality Requirement Scenario Expected Outcome

1

Usability

A user enters the game and wants to play.

They should have no issues logging in and understanding the game rules.

4

Performance

A large number of people join the game.

This should not impact waiting times.

2

Accuracy

A player asks the chatbot for hints.

The chatbot should not give the answer but also should not provide false hints.

3

Scalability

A new feature is added to the game.

Other features should not be affected.

5

Security

A user registers with a password.

The password must be securely encrypted and stored in the database.
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.

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.

11.1. Technical Risks

When identifying and listing the project’s Technical Risks, it is helpful to separate them into Internal Risks (arising within the system development process) and External Risks (coming from factors outside the direct control of the development team).

Prioritized from highest to lowest, they are as follows:

11.1.1. Internal Risks

Internal Risk Description How to Deal With It

Lack of a Clear Work Plan

Since we are starting from scratch, we still have many decisions and tasks ahead, making it difficult to clearly determine how each of us should proceed with the project.

As we progress and become familiar with the framework, we should collaboratively outline a work plan.

Adaptation to New Technologies

The technologies we have chosen to work with are new to several team members, which may cause discomfort and future issues.

Watch instructional videos to learn how to use them and understand their main functionalities.

Limited Experience Working in Large Teams

Since we lack experience working in large teams, the communication process may be somewhat confusing.

Follow teamwork best practices and guidelines, and use tools like Pull Requests to ensure better version control.

Project Deadlines Overlapping with Other Tasks

Since all members are students, the various project deadlines may clash with other important dates, such as exams and assignments.

Keep up with the work, and if any such issues arise, inform the rest of the team so they are aware of the situation.

Team Members with Limited Experience in GitHub and Pull Requests

Not all team members are proficient with Pull Requests, which significantly limits their initial contributions.

Learn and practice using this functionality.

Team members leaving

A certain team member was fired after not putting in any work for a few weeks, leaving all of us with extra work.

Reorganizing our work and spending more time on this project.

11.1.2. External Risks

External Risk Description

Dependence on API Functionality

Since some application functionalities depend on external APIs, their proper operation is crucial for the app.

Server Uptime Dependency

The application is hosted and deployed on a server, making its uptime essential.

New AI Technology

This is a recent technology, and working with it presents a novelty, with less available information compared to other technologies.

GitHub and Cloudflare Issues

Due to recent cases of some companies blocking Cloudflare from their servers, this could negatively impact the project, as it affects GitHub.

11.2. Technical Debts

At this stage of the project, we have encountered with the following:

Debt Description How to Deal With It

Limited Familiarity with the Base Project

We have been given a template to work from, but we are not yet fully familiar with its contents, even though this would be highly beneficial.

During the application design process, the team should review what parts of the application were provided and what is missing.

Technology Choices That Not All Members Are Experienced With

We have chosen to work with certain programming languages in which we still lack experience, aiming to create the best possible application in the long run.

Try to become familiar with these technologies as soon as possible to avoid creating more problems in the future.

Dealing with bad code from fired member

The team member that was fired left us a very broken timer component and other bad practices

We decided to just make a new one from scratch and remade its functionality.

Database schema

The schemas used for our database may appear complex to a user accessing the application.

We have traded off agility and flexibility in favor of future scalability when structuring the database.

Lack of clear criteria in components

In certain views of the application, there are elements that could have been separated into their own components.

Extract these pieces of code into their own classes to improve reusability, structure, and visibility.

Poor HTML practices

Since we are using React, we have over-standardized the use of <div> tags in our page structure.

Improve the structure by replacing unnecessary <div>s with more appropriate tags that better serve their purpose.

Poorly resizable CSS

The CSS rules applied in certain components and views are not resizable.

Redesign the problematic rules with resizability in mind.

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.

Further Information

See Glossary in the arc42 documentation.

Term Definition

<JavaScript>

<JavaScript is a lightweight, interpreted programming language that follows the object-oriented paradigm. It is the language we are using for this project.>

<Node.js>

<An open-source, cross-platform runtime environment that allows you to run JavaScript(or TypeScript in our case) code outside of a web browser. We are using it in the back-end. We are using it in the front-end part of the app.>

<React>

<React is an open-source JavaScript library used to build user interfaces.We are using it in the front-end part of the app.>

<MVC>

< It is a software architectural pattern commonly used for developing user interfaces. It divides an application into three interconnected components, Model, View and Controller.>

<Arc42>

<A set of different guidelines to follow for the documentation of a software process.>

<Docker>

<An open-source platform that automates the deployment of applications within software containers.>

<Front-end>

<The part of a website or application that users interact with directly, including the design, layout, and user interface (UI).>

<Back-end>

<The server-side of an application, where data processing, storage, and business logic happen, and it communicates with the front-end.>

<Wikidata>

<Wikidata is a free, collaborative, multilingual knowledge database that stores structured data.>