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

The goal of this application is to develop an application which functionality is similar to the “Saber Y Ganar” Spanish program on TV. Users will have to choose an answer in several questions proposed extracted from WikiData, these questions will be automatically generated by its API.

Furthermore, for the development of this application the use of GitHub is required to have a repository with all members of the development team using several tools provided by this service. In addition to that the application will have to save the entrance of different users on a database, allowing them to make different tracking and having previous results of that specific user.

Also, it must be said that during each question an IA assistant should be helping the user in case of need. This would require us, the development team, to use different LLM that is still to be decided which one will be use.

Our overall goal is to generate user satisfaction while playing this game, trying out different modes and using certain aids that, when used correctly, will be key to achieving a good number of points and placing yourself in a good position in the rankings.

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

1.1.1. Functional Requirements

Related to the WebApp Service:

  • The game must allow users to play a game with several rounds and each of them having 4 possible answers with only one correct. Also, several modes can be choosen in order to make the game different each time.

  • The application must save the correct answers and tracking them in a good way to the data base for having correct stadistics that then can be check by the user, in its home page.

  • The system for hints must work properly in order to not use them in all rounds. Only when the cost can be payed correctly.

Related to the LLM Service:

  • The game must have a chat that needs to have a conversation with the user when it is required, giving clues but without saying the correct answer under any circumstance.

Related to the Question Service:

  • This service must provide different possible questions and save them in the database, then randomly one will be choosen.

Related to the Gateway Service:

  • The game should have the endpoints in this service, making all the application working around it.

Related to the User/Auth Service:

  • This two services are under the same directory. They will be in charge of adding users to the aplication and then allow them to enter with their credetials. Moreover, this service (userservice) must be also in charge of saving the stadistics of the user.

1.1.2. Non-Functional Requirements

Related to the LLM Service:

  • The given chat must not give large answers without any reliable information.

Related to the QuestionService:

  • The time to response from the moment when a question is required to when it is printed on the screen must not be huge.

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.

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

Our application is going to gave more than 85% of code coverage so the tests are going to be strong.

Usability

Our application is going to be very intuitive, allowing new users to navigate through it quickly. People from all ages will be checked that are capable of playing.

Portability

Our application will allow its deployment of different devices at different times, without having a huge penalization on response times.

Security & Privacy

Our application will only allow the users themselves to see its own results, without considering some rankings that will involve all users. Also for entering into the application you must be authorized, you cannot jump through the url between different windows.

Performance

Our application will be loading tests to confirm that runs correctly under “heavy conditions” in which there is much traffic of users. For example, for 10 users our application is going to answer in the same way, related with response times, than if there is only one user.

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 Contact Expectations

RTVE

rtve.dircom@rtve.es

- High-quality, functional quiz platform
- On-time delivery
- Easy-to-use interface
- Detailed user stats and APIs

ChattySw

chattySw@projects.es

- Clear requirements and deadlines
- Collaboration and timely feedback
- Efficient code reviews and testing

Professors

Pablo González: gonzalezgpablo@uniovi.es
Jose Labra: labra@uniovi.es

- Regular progress reports
- Adherence to academic guidelines and criteria
- Proper documentation of work and development process
- Develop interpersonal skills and team dynamics

Development team

Víctor Llana Pérez - uo294629@uniovi.es
Lara Haya Santiago - uo289684@uniovi.es
Alba González Arango - uo289041@uniovi.es
Marco Lorenzo Martínez - uo294324@uniovi.es
Javier Menéndez Osendi - uo294866@uniovi.es
Daniel Rodríguez Fernández - uo293655@uniovi.es

- Clear requirements and deadlines
- Collaboration and timely feedback
- Efficient code reviews and testing

Wikidata (Data Provider)

wikidata@lists.wikimedia.org

- Accurate and reliable data used for question generation
- Compliance with licensing and data-use policies

Empathy

https://empathy.co/contact-us/ & us@empathy.ai

- Increased user engagement through their LLM
- Integration of Empathy’s LLM for dynamic, diverse question generation
- Opportunity for users to participate in Empathy’s contest

Users

-

- Easy registration and login
- Engaging quiz experience
- Accurate tracking of progress (games, questions, stats)

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.

TECHNICAL CONSTRAINTS

Constraint Explanation

Name

The application must be called WIChat.

Game description

The game will consist of showing a picture and the users guessing what it is about.

Obtaining the hints

Some hints for the game must be obtained from an external Large Language Model (LLM) through an API.

Source of information

Information about the questions and answers must be directly obtained from Wikidata. So should be the disctractors and the images.

Access to information

The system will give access to the information about the generated questions and users through an API.

Deployment

The application must be accessible through a web interface.

Tracking the work

The development of the application must be on a given public repository in GitHub.

ORGANIZATIONAL CONSTRAINTS

Constraint Explanation

Developers

The application must be developed by a team of approximately 4 members.

Developing time

The application must be developed by May. Also, it has to follow some deliveries throughout the semester.

Organization of the work

Several meetings will be held by the group members to discuss further things to do.

Project management

Git will be used to manage and document the project and advances.

3. Context and Scope

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.

3.1. Introduction

WiChat is a game designed for an online experiment done by RTVE, with the typical TV quiz contest format. To implement this application, we need to call several external APIs. Wikidata is the one in charge of giving us the information we require for the questions and the answers, and also the images the user is going to see, which are the main part of the application. We also use an LLM for generating some hints for the user (in form of wildcards) and a database for storing the user log-in information.

3.2. 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
Communication Partners Input Output

User

The user sees the web application in real time and makes decisions accordingly.

Performs actions on the application such as answering a question, using a wildcard or asking a question to a chatbot.

WebApp

Receives user inputs and data from backend services.

Updates the interface to show to the user.

Gateway Service

Takes actions from users received from the web application.

Sends the requests to the corresponding endpoints.

Question Service

Receives a query about a theme or category.

Returns a page corresponding to the given query.

LLM Service

Gets relevant information about the question the user has to answer.

Interacts or answers the user in several ways, depending on the used wildcard.

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

Diagram
Communication Partners Explanation

WebApp

The user can play the game using Internet, via HTTP.

Gateway Service

Manages the requests and redirects them to the respective APIs.

Database

MongoDB database for storing users information and the required information about the answers and distractors of the question, each of them with an image.

Question Service

Data is obtained throught SPARQL queries and stored in the database due to this service. Furthermore, each round of the game, the four options (and the image of the correct one) are requested to this service, which takes them randomly from the database according with the selected topic/s.

LLMService

Gives relevant hints about the question the user has to answer.

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.

Further Information

See Solution Strategy in the arc42 documentation.

The application is built on the MERN stack, a full-stack combination of source-available technologies used for building web-based applications on a simpler and more agile manner. It consists of:

Name Explanation

MongoDB

NoSQL database which uses JSON-like documents with optional schemas. We choose it over relational databases to make use of its scalability and flexibility to store large amounts of data.

Express.js

Backend framework for Node.js. It will simplify the process of building APIs.

React.js

Front-end JavaScript library. Despite the loading overhead, it will help us build a modern and fast UIs for the application.

Node.js

Open-source cross-platform JavaScript Runtime environment which will be used to build the backend of the application. It is widely used and has an enormous amount of available libraries, wich makes it one of the best approaches for most web applications.

4.1. Decompositon of the system

The main architectural pattern to be used in the application is to divide different responsibilities in their own respective microservice, creating a logical separation between modules. This will help to coordinate the team and reduce conflicts while working on different microservices of the application, easing development. For the authentication microservice, we will be combining statelessess, a token-based model and API Gateway orchestration for a robust and scalable authentication system. Other microservices, such as the game microservice, or LLM microservice and WikiData querying microservice, will be based on either a MVC pattern or a Client-server or Controller-Responder model. As for design patterns, we will use template method to manage the behavior of the questions in different gamemodes and possibly the factory pattern to create the different questions.

4.2. Achieving quality goals

Goal Steps to achieve it

Testability

We will aim for a high test coverage of the code for the application, using the adequate tools to achieve this.

Usability

We will perform usability tests, like using dummy users and testers, and we will extend the application to be accesible.

Portability

We will test the application in different environments, and use up-to-date frameworks and tools to ensure maximum compability.

Security

We will follow best security practices, and use checklists to ensure there aren’t major security flaws in our application.

4.3. Other organizational decisions

Since we will be building a microserviced application, we will be using a microservice-oriented gitflow for version control. It will be a single repository (monorepo) where there is a folder for each service. We will also follow GitHub Flow for a straightforward development strategy.

We will also follow SCRUM with 1-week sprints for the development cycle. Since we are heavily constricted by time, this will be our best alternative.

With respect to testing, we will use Jest for unitary testing, which helps us improving our productivity by executing tests automatically and in a fast way. It also includes very clear reports of the tests and, in case they fail, the reason why this happens. The tools it provides for mocking modules or functions are really great, which allow us to test just the parts of the application we want for each test in an efficient way. Furthermore, it is compatible with several frameworks, such as React and Node.js (the ones we are using), which makes it perfect for testing our application.

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.

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.

Diagram
Motivation

The purpose of this diagram is to represent the system in the most general way possible, outlining the main application from the external components that are also in use.

Contained Building Blocks
Name Responsibility

WIChat

Central web Application, acts as the primary interface for the user and acts as mediator between external data sources and services.

Wikidata

Repository of factual, well-organized, and machine-readable data that can be queried and leveraged to support the system’s functionality.

LLM

Will generate appropiate hints in response to user queries, will also process data from Wikidata to generate said hints.
Important interfaces

  • User ↔ WIChat: Direct interaction through UI.

  • WIChat ↔ Wikidata: Structured data retrieval for factual information and images.

  • WIChat ↔ LLM: Natural language understanding and response generation.

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.

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

Diagram
Name Responsibility

Frontend

Manages user interaction and presentation.

Backend

Handles logic, coordination, and communication between the frontend, database, and external services.

Database Layer

Provides secure and efficient storage and retrieval of data for the application.

5.3. Level 3

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

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

Diagram
Name Responsibility

Authentication Service

Handles user authentication, login and signup.

User Service

Retrieves the data of the users as well as their stadistics to generate the ranking.

Game Service

Manages game state and logic. Uses more concrete services like LLM and Question to divide responsibilities.

LLM Service

Provides chat functionality, sending requests to an LLM, receiving and processing responses to show hints to the user.

Question Service

Creates and provides questions using data obtained from Wikidata.

Gateway Service

Manages the interaction between the frontend and the backend. Handles the requests, assigning them to the corresponding backend endpoint.

We have decided that the communication between the backend (Question service) and Wikidata takes place when the application starts, storing all the necessary information in the database for using it later. We do this communication so early in the application because this approach helps up optimizing the performance. This way, when a user arrives to the actual game, all the information is already stored and ready to be used, because it has been obtained and stored in the back while the user was navigating through the screens that appear previous to the game (login, topic selection, mode selection…​).

6. Runtime View

Contents

The runtime view describes concrete behavior and interactions of the system’s building blocks in form of scenarios from the following areas:

  • important use cases or features: how do building blocks execute them?

  • interactions at critical external interfaces: how do building blocks cooperate with users and neighboring systems?

  • operation and administration: launch, start-up, stop

  • error and exception scenarios

Remark: The main criterion for the choice of possible scenarios (sequences, workflows) is their architectural relevance. It is not important to describe a large number of scenarios. You should rather document a representative selection.

Motivation

You should understand how (instances of) building blocks of your system perform their job and communicate at runtime. You will mainly capture scenarios in your documentation to communicate your architecture to stakeholders that are less willing or able to read and understand the static models (building block view, deployment view).

Form

There are many notations for describing scenarios, e.g.

  • numbered list of steps (in natural language)

  • activity diagrams or flow charts

  • sequence diagrams

  • BPMN or EPCs (event process chains)

  • state machines

  • …​

Further Information

See Runtime View in the arc42 documentation.

6.1. Sign up

The user wants to create a new account and register it for the future. Data must be valid and not collide with some account that already exists.

SignUp

6.2. Log in

The user wants to log in with an account that has already been created.

LogIn

6.3. Playing a game

Selecting the game mode and playing it.

Playing

6.4. LLMChat during a game

The application has a chatbot which can give hints during a round in the game, under no circumstances will it say the correct option. This is the procedure that follows when is invoked:

Hints

6.5. Show statistics

Seeing the statistics of the round, and general at each category.

Rankings

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

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 diagram above represents the initial version of our architecture, outlining the separation between its components. Our design follows a client-server model, where the server communicates with Wikidata to retrieve questions. This clear distinction between the frontend (client) and backend (server) ensures modularity, allowing different implementations to remain interchangeable as long as they adhere to the common API.

We utilize a server hosted on Oracle, providing an isolated and pre-configured environment optimized for running our services. Hosting on Oracle helps reduce infrastructure costs and enhances flexibility.

We use Docker because it helps package our application and its dependencies into a standardized unit, ensuring it runs consistently across different environments, regardless of the machine’s setup. Instead of using a monolithic architecture, we’ve chosen a microservices approach with Docker containers. This allows each service to be isolated, with its own resources, preventing conflicts and improving scalability and resilience. Each service has its own Docker image, which gives us flexibility in development and deployment. Our project includes services like the web application, gateway, user authentication, and MongoDB server. This Docker-based setup makes deployment, management, and resource use more efficient, while boosting flexibility and scalability.

Quality and/or Performance Features

Our Docker-based microservices architecture enhances both quality and performance by ensuring each service runs independently in its own container, optimizing resource allocation and preventing conflicts. This setup improves scalability, allowing services to scale as needed without affecting others. Additionally, it streamlines deployment and maintenance, reducing downtime and ensuring a consistent, high-performing system across different environments.

Mapping of Building Blocks to Infrastructure

The web app, gateway, and services run within Docker containers, all hosted on a server. The server manages these containers and communicates with Wikidata to retrieve questions. The gateway connects the web app with the services, while the services handle user data and generate questions.

Component Description

Web App

User interface that interacts with the rest of the application.

Gateway

Manages communication between the web app and various services.

User Service

Manages user data and statistics, providing some functions for API consumers.

Auth Service

Handles user authentication.

LLM Service

Provides hints to the user while playing.

Question Service

Manages pictures and data for the questions.

Database (MongoDB)

Stores user data and game history.

Empathy

External LLM used to obtain the hints.

WikiData

External API used to retrieve information from WikiData.

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.

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

The cross-cutting concepts form the foundation of the system’s conceptual integrity, enabling a coherent and consistent approach to development. They help achieve key qualities like accessibility, user experience, security, and scalability, which are important across various components of the system.

8.2. Domain Concepts

The quiz game is designed to allow users to choose from predefined categories sourced from Wikidata, creating a dynamic and personalized experience. The system supports multiple categories that users can combine to create customized quizzes. The following domain concepts are integral:

  • Categories and Questions: Categories are predefined areas from Wikidata, such as history, science, or geography. Users can select any number of categories to tailor their quiz experience. The system retrieves relevant questions from Wikidata based on these categories.

  • Game Modes: The game supports different modes, such as playing with a time limit or in rounds. Players can also choose to play a single category or a mix of all available categories. This provides flexibility and variety in gameplay.

  • User Profiles: Users can log in, track their progress, and view their historical performance and rankings. Each user profile includes a personalized quiz history, best scores, and achievements.

8.3. User Experience (UX) Concepts

  • Responsibility and Accessibility: The design is focused on ensuring the game is accessible to a wide range of users, including those with color blindness. To ensure inclusivity, the game avoids color schemes that could cause issues for color-blind players and focuses on accessible contrast and fonts.

  • Round-based Play: Users can choose to play in rounds, where each round presents a set of questions, and the game tracks performance across multiple rounds.

  • Time-based Play: Alternatively, players can play against the clock, answering questions as quickly as possible to compete with others or themselves.

  • Clues and Help Options: Players have the option to use several clues, such as hints or using an LLM chat to help them answer difficult questions. Users can mimmick a call a friend for assistance using game stats to determine the best options for asking for help or even ask the audience.

  • Ranking and History: A ranking system tracks the performance of players, allowing users to see how they compare to others. Historical data is stored to allow users to review past quizzes and track improvement over time.

8.4. Technology and Architecture Concepts

The system is built using React and JavaScript to provide a dynamic and interactive user interface. The architecture is designed with the following concepts in mind:

  • React Components: The game’s interface is built using reusable React components, making the system modular and easy to maintain.

  • Wikidata Integration: The game interacts with Wikidata via predefined categories. When a user selects a category, the system fetches questions dynamically, ensuring a rich and diverse quiz experience.

  • State Management: React’s state management system is used to track user selections, game progress, and scores. It ensures a smooth and responsive experience as users navigate through the game.

  • Oracle Deployment: The game will be hosted on Oracle to ensure scalability, flexibility, and easy deployment. Oracle provides a secure and robust infrastructure for hosting both the frontend and backend components.

8.5. Development and Operational Concepts

  • Agile Development: The project is developed using an Agile methodology, specifically in 3-week sprints. This allows for iterative development, rapid feedback, and continuous improvement.

  • Continuous Deployment: The game is deployed through Oracle, with automated build and deployment pipelines to ensure smooth updates and patches.

  • Scalability: As the number of users grows, the system is designed to scale horizontally. Oracle’s cloud infrastructure supports scaling to handle increased traffic and ensure high availability during peak usage times.

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.

ELEMENT OPTIONS DECISION REASON

Architecture

Microservices, frontend & backend

Microservices

We chose the microservices architecture for its scalability, flexibility and decoupling, allowing the game to evolve easily and handle increased loads efficiently.

Language

Java, JavaScript

JavaScript

The initial prototype was written using JavaScript so we decided to keep on with it.

Backend framework

SpringBoot, Express, Node.js

Express, Node.js

Since we chose JavaScript as the language, this options would make integration with the front easier.

Database

MongoDB (NoSQL), PostgreSQL, MySQL

MongoDB

MongoDB was the database used in the prototype of the project so we continued with it. It allows flexible storage of questions and answers, along with horizontal scalability.

Cloud service

Oracle Cloud, Azure Cloud

Oracle cloud

We started using Azure but Oracle offers more flexibility and it’s easier to use so we finally decided to change.

Frontend

React

React

Although we had never worked with it before, it is a powerful framework which provides predefined and reusable components.

Deployment

Docker

Docker

It is a fast option and allows an easy maintaining of the application. Also, it was the option used in the initial prototype.

LLM

Empathy (Mistral, Qwen), Gemini

Mistral

We tried the three options and they all met our needs for the project but we decided to stick with Mistral, which was an option in the initial prototye.

Wikidata

Direct HTTP request, Wikidata Query Service (WDQS), MediaWiki Action API, Wikibase REST API, Dumps

WDQS

We decided to use the Wikidata Query Service, with queries in SPARQL, making data retrieval structured and efficient without overloading our backend.

Component navigation

React-router, Link

React-router

This option provides efficient route and state management, preventing component conflicts and enhancing user experience.

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 is a structured representation of the key quality attributes of our system. The root represents the overall concept of "Quality," which is then divided into different branches representing essential quality attributes derived from our Quality Goals (section 1.2). Each branch further expands into measurable and concrete evaluation scenarios.

Below is an outline of the Quality Tree:

  • Quality

  • Testability

  • Maintain at least 85% code coverage.

  • Implement automated testing for all major functionalities.

  • Usability

  • Ensure an intuitive user interface suitable for all age groups.

  • Conduct usability tests with different user demographics.

  • Portability

  • Deploy the application on various devices with minimal performance impact.

  • Security & Privacy

  • Restrict user data access to authorized individuals.

  • Implement secure authentication mechanisms.

  • Performance

  • Maintain consistent response times regardless of concurrent users.

  • Perform load testing to simulate heavy traffic conditions.

Each of these categories will have detailed scenarios describing expected system behavior under different conditions.

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

Scenario ID

Scenario Description

UQ-01

A user selects an answer, and the system provides feedback within one second.

UQ-02

A user requests a hint, and the AI assistant provides contextual guidance without revealing the answer.

UQ-03

The application maintains stable response times (under 500ms per request) even with 100 concurrent users.

UQ-04

A new user navigates the application for the first time and completes a game without requiring external guidance.

UQ-05

A request to fetch a new question returns a response from the database within 300ms.

10.2.2. Change Scenarios

Scenario ID

Scenario Description

CQ-01

Integration of a new LLM model should not degrade performance beyond a 10% increase in response time.

CQ-02

Adding a new game mode should not require modifications to more than 10% of the existing codebase.

CQ-03

Migrating the database to a new provider should require only configuration changes without altering business logic.

CQ-04

Enhancing security policies should not introduce more than 5% additional latency per request.

By defining these scenarios, we ensure that our system meets stakeholder expectations and maintains high-quality standards throughout its lifecycle.

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

Risk Description Severity What to do?

Jumping though the URL

This can be so dangerous as some users that maybe enter our application as guest arrive to points that are reserved for logIn users. Also we can face situations in which a user can go directly to /game without selecting the mode of playing or even the categories.

High

Authentication methods must be used in order to solve this and restricting each area depending the case, maybe some only for users that are authenticated or different cases depending the window.

LLM Giving the correct answer

Can happen that the LLM if it does not receive the corrent propmt can give the answer directly to the user, and this is not its purpose. It must give clues without saying the correct answer or neither discarting the rest of the options.

Medium

Try to perfect the prompt in order to avoid games that are completly useless as the LLM can say the correct answer.

LLM Time Response

Can make the user wait for a huge time until he/she recieves and answer. And the problem is not only that because our ChatBot must be conversational and in case of make wait in each message it will be a loss of time considerable.

Medium

Testing a lot what the response time is for giving hints and try different models.

Repeated Questions

Can happen that as we save in the database all the different possible questions, that two questions from the same image appears in the consecutive questions, which is not a good approach

Low

Is weird this to happen because in our queries we retrieve like 100 options but maybe implementing something like a cache to avoid the repetition of it unless in the same game, it would be nice.

Credentials With Low Security

As we have our application the logIn/signUp not requires a specific length of the password or normal things related to security that are asked.

Low

Maybe this can be solved by putting some rules when creating new users in order to avoid this things to happen.

Low level README and Doc

It will not happen because we already have a powerfull README and the DOC too but it can be a risk to not add the correct information in the different points because the first thing that is see in the README and then the doc.

Low

Try to work on it during all the deliverables and improve it.

11.2. Technical Debt

At this point we cannot think of one, as it is true that is our first time dealing with these new technologies but besides the initial part of getting into it, we cannot think as some of them that are making as working worse or slower.

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

12.1. Techniques

Term Definition

Authentication

The process of verifying a user’s identity to grant access to different parts of the application.

Authorization

Determines what actions or resources a user has permission to access based on their authentication status.

Caching

A technique used to store frequently accessed data to improve performance and reduce API calls.

Kanban

A project management methodology that visualizes work using boards and columns to track progress efficiently.

Sprint

A three-week development cycle in which specific tasks and features are implemented and tested.

Deployment

The process of making the application live and accessible to users. Initially planned to be done using Azure, finally Oracle was chosen.

Technical Debt

The cost of additional work caused by choosing a quick but suboptimal solution in software development.

12.2. Terminology

Term Definition

Wikidata

A free, collaborative knowledge base that provides structured data, used as the primary source for quiz questions.

RTVE

Radiotelevisión Española, the Spanish public television broadcaster and one of our stakeholders.

Saber y Ganar

A famous Spanish TV show involving answering questions to win prizes.

Business Risk

Potential challenges that could impact the success of the project, such as missed deadlines or low user engagement.

Game Mode

The different ways users can play the quiz, such as timed rounds or standard question-answer sessions.

Clues

Hints provided to help users answer quiz questions, generated either by the LLM or other game mechanics.

Ranking System

A feature that tracks and displays user scores to create competition among players.

Accessibility

Design choices made to ensure the game is usable by as many people as possible, including those with disabilities (e.g., colorblind-friendly UI).

12.3. Technologies

Term Definition

React

A JavaScript library for building user interfaces, used for developing the frontend of the quiz game.

LLM (Large Language Model)

A type of artificial intelligence model, such as ChatGPT, used to generate hints and assist players in the game.

API (Application Programming Interface)

A set of rules and protocols that allow different software applications to communicate with each other, such as fetching data from Wikidata.

OAuth / JWT

Authentication mechanisms used to secure user logins and manage access.

MongoDB

A NoSQL database used for storing data in a flexible, document-based format.