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

WIChat is a project forked from the University of Oviedo latest base repository offered by the Software Architecture course. The development team (es01a) is formed by the following engineering students:

We decided to use as a base a project from last year, with the following authors:

  • Méndez Fernández, Hugo

  • Barrero Cruz, Pablo

  • Lago Conde, Alberto

  • García-Ovies Pérez, Pablo

  • Bustamante Larriet, Samuel

  • González García, María Teresa

  • Andina Pailos, Daniel

This is basically a Trivial Pursuit like game inspired in spanish TV show "Saber y Ganar" aimed to develop its users' general knowledge as well as increasing their reflects, analytical thinking and also their focus. This will be achieved with all the main app functionality that includes:

  • Scoring systems based on response times

  • Different question categories

  • A history of past games

  • A LLM that gives hints to the player

Requirements Overview

The main goal of this project is to develop a web application that will allow users to play a Q&A game with multiple categories. The application must have the following functionalities:

  • A front-end web that allows users to register and play the game.

  • A user registration system with a history of their games.

  • All the questions data must be obtained from the WikiData knowledge database.

  • The application must have an API to obtain users information.

  • The application must have an API to obtain generated questions.

  • Each question should have a correct answer and several incorrect ones or distractors

  • The application must use LLM to give hints to the user

Further information can be found here.

Quality Goals

The following table describes the project’s quality goals in descending order.

Quality Goal Motivation

Efficiency

As it’s a game, one of its main objectives is efficiency, as the game needs to run swiftly and smoothly.

Usability

The application must be not only easy to learn and use but also fun because if a game has no joy in it, then it shall never be called for that name.

Maintainability

Projects must always have enough quality to be able to be modified without making more changes than necessary. Not following this principle would heavily increase costs in new feature implementation or bug solving that may arise in the future.

Security

Security is always key and therefore effort will be put into fighting against unauthorised access of information, including the users' personal or sensitive data that the information system may contain.
Table 1. Stakeholders
Role/Name Description Expectations

Development Team

  • Andrea Fuertes

  • Sara Inés

  • Pablo Pérez

  • Sara Lamuño

  • Saúl Valdelvira

  • Alejandro Aldea

The engineering students are expected to improve communication, teamwork and coding skills adopting a developer role in this project.

Teachers

  • José Emilio Labra

  • Pablo González

  • Irene Cid Rico

Teachers are in charge of supervising the developers work aswell as helping them solve environment, development issues or any other that may arise.

Users

  • Final users of WIChat

They are just expected to use this project as it is intended to work.

ChattySw

  • Software development company

They company that was hired to develop the software

RTVE

  • Client that wants the app

RTVE hired ChattySw to develop the app

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)

There are various architectural constraints that affect this application. They have been divided into the following sections.

2.1. Naming Conventions

Constraint Description

Application name

The name of the developed application will be WIChat

2.2. Application Requirements

Constraint Description

Theme

Online question and answer application. It is similar to the "Saber y Ganar" game show.

Question generation

Both questions and answers will be automatically generated from Wikidata.

Question structure

Each question will have one correct answer and multiple incorrect or distracting answers. There will be a time limit to answer each question.

Frontend

The system will have at least one Web frontend deployed. Access will be through the Web.

User management

Users can register and log in to play. Registered users can also check their participation history in the system (number of games, correct/incorrect answers, times, etc.).

API usage

APIs will be used to access users and generated questions information.

Docker

Docker will be used to deploy the application locally and remotely.

LLM

An LLM will be used to assist the user during their game.

2.3. Documentation

Constraint Description

Use of Arc42

The project will follow the Arc42 documentation standard.

2.4. Organizational and Versioning Constraints

Constraint Description

Project organization

The project is distributed in three established deliveries. Therefore, each module of the project will evolve in several versions, marked by the deliveries. At the end of these deliveries a final presentation will take place. Then, the team will explain the application.

Git and Github

The use of Git as a version control system and the Github platform is mandatory. The public repository will be hosted on this platform.

2.5. Development Team Constraints

Constraint Description

Technical and theoretical knowledge

We are not professional developers and have limited experience. Therefore, we will use tools and languages minimally known by some team members.

Budget

We will use free tools or services for which the University has a license.

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.

Diagram 3.1: Business Context

  • WIChat is a web application that allows users to register, log in, play "Saber y Ganar," and view statistics about their game performance.

  • Wikidata is a free and open knowledge base that serves as a central repository for structured data. Its API will be used to retrieve the information needed to generate questions and answers within the application.

  • Large Language Models (LLMs) are advanced AI systems designed to understand and generate human language.

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

3.2.1. System Scope

Diagram 3.2: Technical Context

Other elements of the system are:

  • WIChat Webapp: The module responsible for user interaction through the UI, serving as the front-end of the entire system.

  • Image Generation Service: An internal service that manages image generation based on data retrieved from Wikidata.

  • Gateway Service: A public-facing Express service that acts as a proxy for user management, enabling sign-up and login.

  • User service: An Express service that handles the registration of new users in the system.

  • Auth service: An Express service dedicated to user authentication.

4. Solution Strategy

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.

4.1. Technology decisions

To develop the app we will use the following technologies:

  • JavaScript is the main programming language.

  • ReactJS, a JavaScript library that streamlines the development of graphical interfaces for web applications, it is used to build the user interface.

  • Docker Compose to deploy all the microservices.

  • GitHub: Platform offering remote repository services for project development, task management, and version control.

  • WikiData API to obtain question and answer information.

  • ExpressJS to build the backend.

We chose these technologies because they were already being used in the project we based our work on. This allowed us to build upon an existing foundation, facilitating development and ensuring compatibility while leveraging JavaScript’s agility and ReactJS’s efficiency in building user interfaces.

4.2. Implementation design

4.2.1. Image generation strategy

For the image generation process, we retrieve data from Wikidata using SPARQL queries based on a structured JSON format. This JSON structure defines categories and properties that guide the generation of image prompts.

The JSON structure allows us to select the desired categories for the images, and in the future, specify the style or format. Based on this, we construct a SPARQL query to fetch data from Wikidata and convert it into an image generation request. Here’s an example of a category element in the JSON:

[
    {
        "name": "country",
        "instance": "Q6256",
        "properties": [
            {
                "property": "P18",
                "query": "SELECT ?capital WHERE { ?country wdt:P18 ?capital . FILTER(?country = wd:{x}) }",
                "image": "https://upload.wikimedia.org/wikipedia/commons/3/3a/Meerkat.jpg",
                "category": ["Geography", "Cities"]
            },
            {
                "property": "P18",
                "query": "SELECT ?currency WHERE { ?country wdt:P38 ?currency . FILTER(?country = wd:{x}) }",
                "image": "https://upload.wikimedia.org/wikipedia/commons/3/3a/Meerkat.jpg",
                "category": ["Economy"]
            },
            ...
        ],
        ...
    },
    ...
]

his structure allows us to dynamically generate SPARQL queries to fetch data from Wikidata, which is then transformed into image generation prompts.

The process consists of the following steps:

Define categories and properties in JSON format.

Generate a SPARQL query based on the selected properties.

Retrieve data from Wikidata using the query.

Convert the data into an image prompt.

Generate the image using an external image generation API.

This approach enables the dynamic creation of images based on specific categories and properties, ensuring a diverse set of visual representations across different topics and languages.

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

We decided to use a microservices arquitecture, having different modules for each functionality. For example, we will use a microservice to generate the images.

4.4. Strategies to Achieve Key Quality Goals

The quality goals are explained in more detail in another section.

Quality Goal Strategies to Achieve It

Usability

We will conduct tests with real users to evaluate the app’s interface and improve it based on their feedback.

Availability

Docker Compose will be used to streamline the app deployment process and prevent issues. Additionally, web hosting will be used to make the app accessible on the internet.

Testability

We have created unit and end-to-end (e2e) test suites to ensure the app functions as expected.

Performance

We will minimize API calls to maintain quick response times, for instance, by using bulk requests when necessary.

4.5. Key Organizational Decisions

Our framework will involve weekly work sessions with meetings scheduled as needed. One meeting will always take place during lab time to assign tasks and make minor decisions.

Additional meetings will be dedicated to more in-depth reviews and major decision-making.

Each task will be tracked as an Issue in GitHub to monitor progress. Moreover, we will use GitHub Projects to streamline the team’s workflow. To merge code into the develop branch, we will utilize Pull Requests, which require approval from all team members.

5. Building Block View

The building block view graphically represents the decomposition of the system’s most essential components.

5.1. Whitebox Overall System

Diagram White Box WIChat

Motivation

This is the main view of the system. WiChat application is related to Wikidata API, which is an external component.

Contained Building Blocks

  • User: Client who interacts with the system.

  • WIChat: Main application. Represented as a blackbox that will be detailed in the following decompositions.

  • Wikidata: External API the system uses to generate questions and answers and get images from.

  • LLM Model: External Large Language Model the system uses to request hints about the image.

5.2. Level 2

5.2.1. White Box WIChat

Diagram White Box WIChat

Motivation

First decomposition of the system. Internal structure of WIChat component.

Contained Building Blocks

  • WebApp: The main module of the application, responsible for the user interface and interaction.

  • Gateway: Handles communication between the user service and question service modules with the WebApp. It acts as a REST API.

  • Questions: Retrieves questions from Wikidata and stores them in the database.

  • Users: Manages user administration.

  • MongoDB: Database used to store the generated questions.

  • SQLite: Database used to store user information.

  • LLM Service: External service that generates hints to help users with questions.

  • Wikidata: Data source used to retrieve images and quiz questions.

Other Important Interfaces

  • Docs: Contains the application documentation.

5.3. Level 3

5.3.1. White Box Users

Diagram White Box Users Service

Motivation

Internal structure of users service black box from level 2.

Contained Building Blocks

  • User Profile: Handles user account data and profile details.

  • Authentication: Manages login and signup processes.

  • Participation history: Records and manages users’ participation data.

  • Gateway: The entry point that routes requests to the appropriate internal component.

  • SQLite: Database used to store user data.

5.3.2. White Box Questions

Diagram White Box Questions

Motivation

Internal structure of questions service black box from level 2.

Contained Building Blocks

  • Question Fetcher: Retrieves question data from Wikidata.

  • Question Processor: Processes fetched questions and prepares them for storage. Requires hints to LLM Service.

  • Gateway: The entry point that routes incoming question-related requests to internal components.

  • MongoDB: Database used to store the generated questions.

  • LLM Service: External service that generates hints to help users with questions.

  • Wikidata: Data source used to retrieve images and quiz questions.

5.3.3. White Box Gateway

Diagram White Box Gateway

Motivation

Internal structure of gateway black box from level 2.

Contained Building Blocks

  • WebApp: The main module of the application, responsible for the user interface and interaction.

  • Profile Controller: Routes user profile requests to Users Service.

  • Authentication Controller: Routes authentication requests to Users Service.

  • Participacion Controller: Routes requests related to participation history to Users Service.

  • Question Controller: Routes question requests to Question Service.

  • Questions: Retrieves questions from Wikidata and stores them in the database.

  • Users: Manages user administration.

5.3.4. White Box WebApp

Diagram White Box WebApp

Motivation

Internal structure of WebApp black box from level 2.

Contained Building Blocks

  • User: Client who interacts with the system.

  • Authentication Controller: Manages login and sign in from users and sends requests to gateway.

  • Profile Controller: Manage requests related to profile and sends this requests to gateway.

  • Question Controller: Manage requests related to quiz questions and sends them to gateway.

  • Participation Controller: Manage participation history requests and sends it to gateway.

  • Gateway: The entry point that routes requests to the appropriate internal component.

6. Runtime View

In this Runtime View section, some sequence diagrams of different interactions with the system will be shown. Most diagrams are taken from the WIQ project, our base project, because that funcionality has not changed. You can find it in https://github.com/Arquisoft/wiq_es04a/tree/master/docs.

It has been changed MariaDB to SQLite.

6.1. Register

Register Sequence

6.2. Login

Login Sequence

6.3. See User Statistics

See User Statistics Sequence

6.4. See Users and Groups Ranking

See Ranking Sequence

6.5. Play Games

Play Games Sequence

6.6. See and edit your profile

See Profile Sequence

7. Deployment View

Content

This part of the documentation for wichat_es1a explains the deployment view, which is in charge of:

  • technical infrastructure required to execute the system, for example environments, computing resources, network topologies, among other things.

  • maps the software building blocks to the infrastructure elements.

Since software typically operates across multiple environments, such as development environment, test environment, production environment. In such cases you should document all relevant and essential environments.

This documentation becomes especially crucial when the system is 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. No special or deep explanation is needed in this level.

In the other hand, hardware architects can go beyond that and describe an infrastructure to any level of detail they need to capture. Here, explaining and detailing this part of the documentation becomes an essential task.

Motivation

Both software and hardware are complementary parts, since software does not run without a proper hardware.

Because of that, the 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.

Deployment approach

Our system is deployed using a single Azure Virtual Machine (VM), letting Docker Compose manage multiple containerized services.

These services will help us to simplify deployment, maintenance, and other features in the project.

The different containers used will be listed below:

  • WebApp: The primary user interface that interacts with the system. Retrieves data from the Gateway Service.

  • Gateway Service: Data access interface for services.

  • Users: Manages everything related to users, for example authentification.

  • LLMService: Manages LLM chat with the user to help them with the questions generated. It is worth clarifying that the LLM has not been chosen yet.

  • Two databases, which are:

  • MongoDB: for questions management (store the questions with the distractors and the correct answer from a specified JSON file, and do several things with that information).

  • SQLite: for users management (create various roles, e.g. User, which has many parameters, a group of users and groups, among others).

  • Questions: Generates questions to use in the game. The questions will have three wrong answers and one correct answer.

  • Multiplayer: Permits users to play multiplayer games with other users.

Deployment View

Further Information

See Deployment View in the arc42 documentation.

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 and secures consistency and integrity.

They can include many different topics, such as:

  • models, especially domain models, which are important for the deployment of the project.

  • architecture or design patterns.

  • rules for using specific technology, to find out what we have implemented and why.

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

  • implementation rules.

Motivation

The most important concepts that our project will follow are 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 in many different ways:

  • concept papers with any kind of structure.

  • cross-cutting model excepts 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.

Some important concepts need to be taken into account so as to a better understanding of the application. These concepts have to do with the following categories.

  1. Domain concepts.

  2. User Experience (UX).

  3. Operation Concepts.

  4. Architecture and Design Patterns.

  5. Development Concepts.

Next, each category will be detailed.

8.1. Domain concepts

At the moment, the application follows this schema:

Current version of the domain model

  • User: it is the person that uses the application. Multiple user sessions are an option in this application.

  • Contest: The contest is the part that the User can see. It contains everything the user can do, such as play games, be part of groups or look for rankings and statistics.

  • Game: The User can play the game here.

  • Question: Each question has different answers but only one of them is correct. Answering correctly to the questions rewards users with points.

  • Statistics: Each user has statistics that show different aspects of their profile, such as the time they invested on each game mode, correct and incorrect questions, etc.

  • Profile: User’s profile has data such as their username and the amount on points they have earned. They can also choose a profile picture from between some given avatars.

  • Group: Users are able to join or create groups, that way the can get to a groups ranking.

8.2. User Experience (UX)

This part is currently in progress.

8.3. Operation Concepts

  • Usability: We tried for the application to be easy to use. For this reason, we will try to spread this application to several types of persons, to complete and expand its strengths and weaknesses and improve them.

  • Usability affects User Experience as well, so it is an important aspect of the application.

8.4. Security

  • We have implemented some security in the application, which will be listed now.

    • Some blocked sites if the user is not logged in an account: This way, we avoid external people to be able to access our application as it could lead to other security issues.

    • Passwords with a minimal security level: They need to be at least 8 characters longs and they must contain upper and lower letters, numbers and special characters.

    • Encrypted passwords: In case that the batabase is stolen, data would still be secure and the passwords will contain other things, which will improve more the security of the app.

    • Passwords with salt: our passwords will have a random secuence of characters before hashing them, so they will have more security and will be more difficult to hack and obtain the passwords.

8.5. Architecture and Design Patterns

  • Microservice: In this application there are some microservices such as the User Management, which involves signing up, logging in and everything related to the points and timing of the user. Microservices provide an easy way of creating a complex application composed by independent systems.

  • Questions generation system: It is a microservice that creates infinite questions related to several topics, with only one type of questions: related to images. In that type of question, an image will be given for the user to guess what it is, with only one correct answer and three distractors.

  • Graphic interface: Users are able to communicate with the application to this service.

  • Generation of the hints with LLM: the app will comunicate with a LLM to provide hints of the question, trying to be accurate with the answer.

8.6. Development Concepts

  • Testing: Includes unit tests for each functionality and end-to-end (e2e) tests for core gameplay features.

  • CI/CD: The application is in continuous integration and deployment. Team members commit frequently into the repository where the project is stored. This makes it easier when assembling project parts involving collaboration from different team members.

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

9.1. Fork a project from last year to use as a base

Since the project specification is similar to last year’s, we need to choose between building the project from scratch, or forking a project from last year.

Our decision is to base our project on last year’s wiq_es04a team.

Advantages

  • A considerable amount of functionality is the same as last year, so we won’t have to implement it.

Disadvantages

  • Using other people’s code can lead to confusion. Understanding an extraneaous codebase is complicated.

Status: Accepted

9.2. Trunk based development

Use the Trunk Based Development git branching strategy.

The proposed workflow is the following.
To make any change to the codebase:

  1. Branch from master

  2. Make all the changes, and commit them

  3. Create a pull request to merge the changes into master

It’s important to constantly merge all the changes into master, and to avoid any aditional long-lived branches. This reduces the effort of maintaining those branches, and keeping them on sync.

Tracking Issue

Status: Accepted

9.3. Database

Last year’s project use two different databases:

  1. MariaDB for users

  2. MongoDB for questions

Because of a problem with MariaDB database, we all agree on still using two databases changing MariaDB to SQLite and maintaining MongoDB. Then project’s databases will be:

  1. SQLite for users

  2. MongoDB for questions

We think that is the easiest option for us in terms of implementation and to adapt old system functionality. SQLite is not only open source but also easy to use and efficient for small applications.

Status: Accepted

9.4. Gemini as our LLM

After discussing which LLM Api use for WIChat we had two options we liked the most: Gemini and Empathy.

Gemini Advantages

  • Better analyzing pictures and creating hints

  • Well-documented

  • Free

Gemini Disadvantages

  • Less natural conversational language

Empathy Advantages

  • Contest

  • More human-like and conversational language

Empathy Disadvantages

  • Less documentation

  • Worst hints

  • More difficult implementation

Finally, Gemini es the best option for us because of its multiple advantages.

Status: Accepted

9.5. Use Typescript

Typescript is a "type-safe" language. It offers a stricter type system than Javascript. We should use it, when possible, since it’s fairly simple to integrate in our project.

This proposal is to use typescript for new modules, guaranteeing compatibility with our existing javascript codebase. Still, new modules could be written on Javascript, depending on what the maintainers of those modules think is best. This is a tradeoff between code safety and inertia. So typescript it’s recommended, not enforced.

Advantages

  • The strict type system allows us to produce safer code, and to avoid runtime errors

  • There is a lot of tooling available to integrate typescript with a javascript application, so we should be able to transition to typescript at our own pace.

Disadvantages

  • Despite the tooling available, typescript is a different language, and integrating it with our javascript code won’t be trivial. But we think it will be worth the effort.

  • Typescript’s safety ends on typescript domain. If we use a typescript module from a javascript program, all the mentioned type-safety will be gone. It’s not a magical solution, just a nice thing that could improve the quality of the code.

Status: Accepted

10. Quality Requirements

The main quality goals are:

  • Usability: The interface should be intuitive, with clear instructions and an accessible design. This will allow users of all abilities to navigate and use the application effortlessly. It must mantain usability in mobile devices.

  • Availability: The system should aim for maximum availability, ensuring it is accessible at all times.

  • Testability: The code must be tested and should be easy to test. The tests improve the stability of the codebase by detecting regressions.

  • Performance: Efficiency is a priority in system usage, particularly in quick question generation, ensuring a good experience for users.

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

Usage Scenario table:

Usage Scenario System Reaction

The user initiates the web application, enters their username and password, and clicks the login button.

The system verifies the information entered by the user, and if correct, redirects them to the main page; otherwise, it indicates an error has occurred.

The user surveys the main window, where several buttons with different options appear.

In response to pressing each of these buttons, the system will display the corresponding content.

The user starts the game and is awaiting the questions.

The system swiftly generates the question and its possible answers.

The user loses the game and decides to stop playing for a while. Five hours later, they decide to play again.

The system remains active and functions correctly.

The user decides to chat with the LLM

The chat window opens, and an interactive chatbot is started

Change Scenario table:

Change Scenario System Reaction

Adding an additional login system to access the account not only through username but also through the email.

The system should be capable of adapting to provide this functionality without affecting the existing ones. The tests verify that the old login is not affected.

Adding a new game mode or functionality.

When adding a new feature, the application’s usage methodology should not be distorted, ensuring it can still be used in the same manner.

Changing the LLM backend

The LLM service should be flexible enough to support multiple LLM’s in the future

Performance Scenario table:

Performance Scenario System Reaction

The user starts a game

The questions should be generated fast, and the user shouldn’t have to wait more than a second or two for the game to start.

The user starts a chat with the LLM, to ask questions.

The chat should work smoothly.

Testing Scenario table:

Testing Scenario System Reaction

A change is added to the codebase

The change should be tested meticulously

A change on the codebase breaks functionality

The existing test suite should fail and reveal the regression

The system starts a test for the LLM service

The tests should run deterministically. Chats are simulated, so no LLM randomness affects the test. Tests for the LLM service should be deterministic.
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 comprehensive list of identified technical risks and technical debts, prioritized based on their potential impact.

Form

A structured list of risks and technical debts, accompanied by proposed mitigation strategies to minimize or prevent negative impacts.

Further Information

See Risks and Technical Debt in the arc42 documentation.

11.1. Risks

To evaluate the significance of the identified risks, we use a scale from 1 to 3, where 1 denotes low relevance, 2 medium relevance, and 3 high relevance.

Risk Relevance Considerations

Limited expertise in specific tools or programming languages

2

The team may encounter difficulties due to varying levels of familiarity with required tools and languages. To address this, we will prioritize the use of well-known technologies within the team while encouraging knowledge-sharing and individual learning efforts.

Lack of prior collaboration within the team

1

Since the team has not worked together before, there is a risk of inefficiencies in coordination. Establishing clear communication channels and regularly updating each other on progress will mitigate this issue.

Large team size

1

A higher number of contributors can complicate communication and workflow synchronization. Implementing structured meetings and documentation processes should help maintain efficiency.

Potential delays in integrating external APIs

2

Depending on external data sources, such as Wikidata, might introduce latency or downtime risks. Developing fallback mechanisms and caching strategies can help mitigate disruptions.

Knowledge disparity among team members

2

Some team members have prior experience, either from retaking the course or external knowledge, while others are learning these concepts for the first time. This can lead to uneven task distribution and communication gaps. Encouraging mentoring and pairing experienced members with those less familiar can help balance the workload and improve overall team efficiency.

11.2. Technical Debts

Technical Debt Considerations

Code maintainability and quality

Adopting new languages and frameworks can lead to inconsistencies in coding standards. To prevent this, we will enforce code reviews through pull requests, ensuring peer validation and adherence to best practices.

Documentation gaps

The absence of comprehensive documentation makes onboarding new developers and maintaining the system more difficult. Creating and maintaining updated technical documentation will help streamline development and troubleshooting processes. We need to update our documentation, since it doesn’t reflect the current architecture.

Code cleanup and adaptation from last year’s project

The project inherits code from last year’s implementation, which may not meet current requirements or best practices. To address this, we will dedicate time to learning how to properly transfer and adapt the previous project to align with the updated requirements. This includes improving code quality, removing redundant code, and ensuring compatibility with the new project scope.

By systematically addressing these risks and technical debts, we aim to enhance project stability, maintainability, and long-term viability.

12. Glossary

In this section, we will define and translate some key concepts we consider essential to understand our application.

The format is simple: a table with the term, its definition, and, if applicable, its Spanish translation.

For more information, check the arc42 documentation: Glossary.

12.1. Acronyms

Acronym Term Definition

ADR

Architectural Design Record

A document where an important decision about the software architecture is recorded. It describes what was decided, the decision’s context, and its consequences. Its purpose is to ensure that the design meets functional, aesthetic, and security requirements before proceeding with development.

API

Application Programming Interface

A set of rules and tools that allow different applications to communicate with each other. It defines methods and data formats developers can use to exchange information between various systems.

CI/CD

Continuous Integration & Continuous Delivery

Development practices that automate code integration and delivery. CI focuses on frequently integrating code changes, while CD automates testing and deployments. Continuous Delivery requires manual approval before moving to production, while Continuous Deployment does this automatically.

LLM

Large Language Model

A type of AI model that processes natural language to generate human-like text, answer questions, and more. Used in applications for enhanced text comprehension and generation.

WICHAT

https://github.com/Arquisoft/wichat_es01a/

The name of the web application where users can register and log in to play different types of rounds.

12.2. Domain Terms

Term Definition Spanish Translation

Discovering Cities

A challenge where participants receive clues about a city and must guess which one it is. Clues can include geographical features, monuments, historical or cultural events.

Descubriendo ciudades

ChattySw

Fictional company name we simulate being hired by to develop the application.

N/A

Know & Win

Spanish television program that mixes quiz contests with learning. It is broadcast on La 2 of Televisión Española and features challenges in general culture, history, science, art, etc.

"Saber y Ganar"

Player

A user who registers in the application to play the various available quizzes.

Jugador

The Challenge

A test where contestants answer questions or perform activities to test their knowledge on various topics. It may include multiple-choice questions, completing phrases, identifying images, and more.

El desafío

Warm Question

A round where contestants must answer questions quickly and accurately. The questions are presented without pauses, requiring fast thinking, but without risking too much because incorrect answers can deduct points.

Pregunta caliente

Wise Men Stack

A challenge with questions from various topics (literature, history, science, pop culture, etc.). The goal is to answer as many questions correctly as possible within a limited time.

Batería de sabios

12.3. Technical Terms

Term Definition Spanish Translation

arc42

A set of recommendations for documenting and designing software architectures. It provides a structured template to better communicate the system’s technical aspects.

N/A

Backend

The part of the software that runs on the server and is not visible to users. It handles data processing, database storage, and business logic.

N/A

Container

A lightweight and portable unit that includes everything needed to run an application (code, dependencies, libraries, etc.), ensuring it works the same in any environment.

Contenedor

Frontend

The part of the software that directly interacts with the user. It includes the graphical interface and the user experience in the browser or an application.

N/A

Git

A free and open-source version control system that allows managing code changes and collaborating with other developers.

N/A

Wikidata

An open and free database that stores structured information from Wikimedia projects and others. It allows sharing and querying data about people, places, events, concepts, etc.

N/A