About arc42

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

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

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

Note

This version of the template contains some help and explanations. It is used for familiarization with arc42 and the understanding of the concepts. For documentation of your own system you use better the plain version.

1. Introduction and Goals

Describes the relevant requirements and the driving forces that software architects and development team must consider. These include

  • underlying business goals,

  • essential features,

  • essential functional requirements,

  • quality goals for the architecture and

  • relevant stakeholders and their expectations

1.1. Requirements Overview

Contents

Short description of the functional requirements, driving forces, extract (or abstract) of requirements. Link to (hopefully existing) requirements documents (with version number and information where to find it).

Motivation

From the point of view of the end users a system is created or modified to improve support of a business activity and/or improve the quality.

Form

Short textual description, probably in tabular use-case format. If requirements documents exist this overview should refer to these documents.

Keep these excerpts as short as possible. Balance readability of this document with potential redundancy w.r.t to requirements documents.

Further Information

See Introduction and Goals in the arc42 documentation.

The software development company ChattySw has been hired by RTVE to update an online experimental version of the Saber y Ganar quiz show. The previous version, developed by HappySw, allowed users to answer quiz questions based on displayed images. The updated version, named WIChat, will introduce a new hint system powered by an external Large Language Model (LLM), enabling users to obtain hints about the answers in a conversational way.

1.1.1. Core Features (Required for a Functional Application)

The following features are essential to have a working quiz game, even if not fully polished:

  • A Web frontend to display images, questions, and a hint interaction system.

  • User registration and historical tracking of participation data.

  • Automatic question and image generation based on Wikidata, an external API that serves as the main source for all presented data.

  • A hint system using an LLM accessible via an API.

  • Mechanisms to prevent the LLM from revealing the correct answer directly.

  • Timed questions with a correct answer and distractors, both generated automatically.

  • APIs to provide access to user data and question information, with proper documentation.

  • Basic logging and monitoring to track errors and system performance.

1.1.2. Planned Features (Future Enhancements & Prioritization)

The following features are not necessary for the initial release but will improve the game experience. Features are prioritized based on their impact and feasibility.

Priority 1 – High Impact, Early Expansion

  • Support for multiple question subjects (expands game variety significantly).

  • Internationalization (multi-language support to reach more users).

  • Mobile version (ensures accessibility on different devices).

  • More interactive LLM integrations, such as:

  • A virtual assistant that interacts beyond hints.

  • AI-generated responses that guide players.

Priority 2 – Medium Impact, Recommended for Second Iteration

  • Different game modes, such as:

  • Each wise man with his subject

  • Travel with us

  • The hot question

  • Discovering cities

  • Customizable game settings (time limits, number of questions, topic selection).

  • Group play with statistics and leaderboards.

Priority 3 – Long-Term, Enhances Engagement

  • Live multiplayer mode with competitive play.

  • Additional gamification elements (badges, achievements, in-game rewards).

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

The top quality goals for the architecture include:

Quality Goal

Description

Scalability

The system should support at least 100 simultaneous players with a crash ratio below 1%.

Usability

The interface should be intuitive, engaging, and accessible.

Accuracy

The LLM hints and question generation should minimize incorrect or misleading information.

Performance

The game should have minimal latency in interactions, especially for real-time play.

Security

User data and game integrity must be protected against unauthorized access.

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.

The following stakeholders are involved in the development and operation of the system:

Role/Name Contact Expectations

RTVE Management

RTVE Contact

Ensures the game aligns with business objectives and audience engagement.

End Users (Players)

Game Users

Expect an engaging, fair, and enjoyable quiz experience.

Development Team (ChattySw)

Development Leads

Responsible for building and maintaining the system.

Wikidata Contributors

Open Data Community

Provide the dataset for question generation.

LLM API Provider

AI Service Vendor

Ensures reliable and accurate hint generation.

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.

2.1. Technical Constraints

Constraint

Description

Web-based system

The application must be accessible via web browsers.

LLM Integration

Hints must be generated using an external Large Language Model (LLM) via API.

Wikidata for Questions

All questions and images must be sourced from Wikidata.

Automated Answer Generation

Correct answers and distractors must be generated algorithmically.

Time-limited Questions

Players must answer within a predefined time.

APIs for Data Access

User and question data must be accessible through well-documented APIs.

Prevention of Correct Answer Disclosure

The system must prevent the LLM from directly revealing the correct answer in hints.

2.2. Organizational Constraints

Constraint

Description

RTVE Requirements

The system must align with RTVE’s branding and content guidelines.

Development by ChattySw

Only the ChattySw team is responsible for development and maintenance.

Regular Meetings

A weekly meeting must be held to discuss progress and issues.

Defined Deliverables

The project must meet the following milestone deadlines:

- Documentation Completion

The initial system documentation must be finalized by the first milestone.

- Prototype Development

A working prototype must be ready by the second milestone.

- Minimum Requirement Implementation

The core features must be implemented by the third milestone, though continuous integration will continue beyond this point.

2.3. Conventions and Guidelines

Constraint

Description

Coding Standards

The project must follow industry best practices for maintainable code.

Version Control

All source code must be managed in a repository with clear commit messages.

Monitoring and Observability

The system must provide logging and performance monitoring.

Testing Standards

Unit, integration, and end-to-end tests must be included to ensure software quality.

Documentation Format

All project documentation must adhere to the arc42 standard.

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

C4 Diagram Business context
Figure 1. Overall view of the business context

The business model diagram represents how the player interacts with the system of the WiChat application. The core API will communicate with the external WikiData API using the HTTPS protocol and SPARQL queries to retrieve the information, using independent modules that generate a microservice architecture to decouple the system. The data retrieved by the API will be used to generate the questions that the player must answer. In this case, an image will be retrieved, and the player must select the option that best fits what is shown in the picture. The player can also ask for help, interacting with an LLM Chat, provided by another external API. The LLM will use the information from the WikiData API without direct interaction to provide clues about the image (the corresponding modules are in charge of gathering the information from WikiData API and passing it to the LLM API).

A simple example of the functioning of the system is the following: the player logs in and starts a game. The system retrieves data from the WikiData API and generates the image and the possible answers (for example, an image of the Eiffel Tower, and four cities of Europe, like Madrid, Rome, London and Paris). The player may ask for help to the LLM Chat if he/she is not sure about the answer, and the AI will use the information from the WikiData API to provide clues about the image. The player can then select the correct answer, and the system will inform if it is correct or not. After the game is finished the user will see the game results and can access his statistics and the leaderboards.

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.

C4 Diagram Technical context diagram
Figure 2. Overall view of the technical context

The system will be deployed over a virtual machine in a single Azure server (using Docker) containing all the functionalities separated in different modules:

  • Wichat Application Proxy: When interacting with the server, a Nginx proxy gateway will be tasked with redirecting incoming requests to the Wichat application client, which will also be deployed on the Azure web server.

  • Wichat Application Client: This client will be served to the user and communicates with the API through HTTPS calls and exchanges information through JSON objects. The client (Front-End of the application) will be developed in React (+ JavaScript).

  • Wichat REST API: The Wichat REST API will be run as a .jar file on the server and connect to a database running on a MongoDB docker container.

  • Question generator: The Question Generator will use the external WikiData REST API to retrieve the information to generate the images and questions of the quiz. It will connect to the WikiData REST API through HTTPS calls, passing a Mongo Query Language (MQL) query to retrieve the data that will later be used as the questions of the game. The module is implemented using Node.js and uses Axios for making HTTP requests.

  • LLM AI Chat: This component connects to an external LLM API, Empathy, to provide hints to players. The module retrieves structured data from WikiData via the Question Generator and uses it to formulate meaningful prompts for the LLM. The LLM response is then passed back to the player through the main API.

  • Wichat Application Database: The questions and answers generated by the Question Generator module will be stored in a MongoDB database. It is supposed to be a unique database for the entire system, but containing several different collections for a series of purposes (one for user session data, other for quiz questions, other for statistics and game data…​). The connection layer will use Mongoose.

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.

4.1. Technologies used

  • React is used for the front-end of the application. This framework, at the time of the decision, was highly popular, and its demmand in the market, as well as the familiarity of part of the front-end team, influenced the decision.

  • MongoDB is used, due to the base project already supporting it and the interest of the team to learn how to use it.

  • NodeJs supports the backend, at the time of writing this, due to the base project using it by default, and its relatively low complexity to begin compared to springboot.

  • Git is used as a version control, implemented in github, due to the common use of this web page and the toolset it provides. Focusing on git, this technology is used due to the familiarity all team members share with it.

  • Swagger is a tool used in the API’s design and documentation. It was used due to a constraint of the employers.

  • Commit messages are written following the convention described here to ensure meaningful commit names.

  • Branch names follow a simplification of the strategy described here and it is used to ease the documentation, identification and meaningful naming of development branches.

  • Github Flow is followed as a branch strategy, as the size of the project is expected to be medium and we deemed a hotfix branch and a release branch excessive overhead.

  • Use of semantic versioning (https://semver.org/) for specifying versions meaningfully.

  • The Ui wireframes are designed using Moqups, a tool designed just for that. The decision stems from a recommendation from a work colleage that fit our researched technologies, and its ease of use over Miro led to its use.

4.2. Workflow of the team

The team makes use of an agile framework called kanban to ease the software development process. Therefore, tasks are "hung up" on a kanban board on Github to keep track of which tasks are pending or in progress. The modelled tasks are Github Issues, and are expected to follow the INVEST acronym commonly used on agile frameworks. (mnemonic explanation)

The team’s schedule, apart from a mandatory meeting per week, is up to the team members and the needs of the project. The collaborators do not have a fixed timetable but rather are expected to bear the responsability of their work.

4.3. Team organization and structure

The team, as discussed on the first and second meetings, decided to divide the workload based on frontend and backend, virtually splitting the team in two subteams, each specialized in one of those. However, the teammembers are not expected to act as experts or be irreplaceable, so the subteam composition is to remain flexible. Here is the expected division of the work:

Contributor Role

Miguel Álvarez Hernández

Backend

Marcos Losada García

Backend

María Rodríguez Gómara

Backend

Javier Carrasco Arango

Frontend

Vicente Megido García

Frontend

To avoid losing a team member and the collapse of the project this could entail, architectural and design decisions are documented on this documentation, as well as in the wiki. Furthermore, the team is actively involved in all processes of the system, directly coding or indirectly helping each other via extraofficial comunication on whatsapp.

4.4. Third parties and the responsabilities delegated to them

  • The team delegates the responsabilty of the version control’s remote server to Github, as it is expected to be up and working most of the time.

  • Extraofficial communications are delegated to Whatsapp, as it is the easiest contact method between the team members and all the team personally knowing each other. Otherwise, tools like matrix messaging would be preferred.

  • University of Oviedo provides the installations and the technical assistance for the team’s mandatory meeting, as well as the contact mail domain.

4.5. UI Design - Wireframes

The most up to date Ui designs can be found here.

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.

C4 Diagram (Level 1) Business context diagram
Figure 3. Overall view of the business context

Motivation: The purpose of this section is to provide a high-level view of the system and its primary components. This diagram focuses on how the different elements of the system interact and how the player, application, external services like the WikiData API, and the LLM AI Chat function together to support the game.

Contained Building Blocks:

Name Responsibility

Player

The player interacts with the system, answering questions and obtaining hints through the interface.

WIChat Application

The central application that facilitates player interaction, communication with external services, and question generation.

LLM AI API

Provides hints to the player when requested.

WikiData API

Supplies data and information used to generate questions about images and concepts.

Important Interfaces:

Interface Purpose

Player-Application Interface

Defines the interaction between the player and the application, including how questions are presented and how the player submits answers.

Application-LLM Interface

Manages communication between the application and the LLM AI API to request hints.

Application-WikiData Interface

Manages the interaction between the application and the WikiData API to retrieve information for generating questions.

5.1.1. Player

  • Purpose/Responsibility: The player interacts with the game by answering questions about images and concepts. The player can request hints when needed.

  • Interface(s):

    • Interaction with the WIChat Application through a user interface (UI) that displays questions and accepts answers.

    • Interaction with the LLM AI Chat for hints when requested.

  • (Optional) Quality-/Performance Characteristics: Smooth, responsive UI with minimal delays.

  • (Optional) Fulfilled Requirements: Real-time gameplay experience with clear and engaging UI.

  • (Optional) Open Issues/Problems/Risks: The player should not have access to some internal parts of the application, neither should know how the application is coded.

5.1.2. WIChat Application

  • Purpose/Responsibility: The main system that handles the gameplay, image-based question generation, interaction with external services (WikiData API, LLM AI Chat), and player progression.

  • Interface(s):

    • Communication with the Player through the user interface.

    • Interaction with the WikiData API to retrieve information and generate questions.

    • Communication with the LLM AI Chat to provide hints to the player.

  • (Optional) Quality-/Performance Characteristics:

    • Scalable, with efficient routing of requests to the relevant components.

  • (Optional) Fulfilled Requirements: Real-time interaction and data handling.

  • (Optional) Open Issues/Problems/Risks: Performance under high traffic (large number of players simultaneously).

5.1.3. LLM AI API

  • Purpose/Responsibility: External service that provides AI-generated hints to players based on their interactions within the game.

  • Interface(s):

    • Receives requests from the WIChat Application to provide hints based on player progress.

  • (Optional) Quality-/Performance Characteristics:

    • Fast response time and contextually relevant hints.

  • (Optional) Directory/File Location: External to the system.

  • (Optional) Fulfilled Requirements: High-quality hint generation.

  • (Optional) Open Issues/Problems/Risks: Dependency on external AI service reliability. Since this component consists on an AI-based chat, it is important to maintain the integrity of its responses, limiting the queries that the users may perform so that the goal of the LLM doesn’t get blurred and it doesn’t get influenced by any behaviour that the user tries to introduce. It should only work as a clue generator, and ensuring that this behaviour persists must be a primary focus.

5.1.4. WikiData API

  • Purpose/Responsibility: External service that provides detailed information about images and concepts for generating game-related questions.

  • Interface(s):

    • Receives requests from the WIChat Application to retrieve image-related data.

  • (Optional) Quality-/Performance Characteristics:

    • Relevant, accurate, and up-to-date information.

  • (Optional) Directory/File Location: External to the system.

  • (Optional) Fulfilled Requirements: Sufficient data to generate accurate and diverse questions.

  • (Optional) Open Issues/Problems/Risks: Limited data availability and consistency in the API’s responses.

5.2. Container Diagram (C4 Level 2)

C4 Diagram (Level 2) Container context diagram
Figure 4. Overall view of the technical context

Motivation: The system decomposition has been done to efficiently divide responsibilities, ensure scalability, and facilitate understanding of the system in terms of components and their interactions. The system is broken down into key blocks that interact with each other and with external systems, such as the LLM and the WikiData API.

Contained Building Blocks:

Name Responsibility

WIChat Application Proxy

Manages communication between the client and system services.

Client

User interface that interacts with the application.

WiChat API (API Gateway)

Manages requests between frontend and backend services, routes traffic to the correct backend service.

REST API

API that handles requests and responses between the client and server.

Database

Database for storing user histories, questions, answers, etc.

Question Generator

Automatic question generator based on the WikiData API.

WikiData API

External service providing data for generating questions about images and concepts.

LLM AI API

External service that generates hints for players.

Important Interfaces:

Interface Purpose

WIChat Application Proxy Interface

Defines communication between the client and system services.

REST API Interface

Interface for managing interactions between the client and the database.

WikiData API Interface

Interface for retrieving information about images and questions for the game.

LLM AI API Interface

Interface for generating hints and assisting players based on their interactions.

5.2.1. WIChat Application Proxy

  • Purpose/Responsibility: Acts as the intermediary between the client and other system services. It manages incoming requests from the client and routes them to the appropriate services.

  • Interface(s):

    • Communication with the client to receive requests.

    • Routing of requests to the backend services (e.g., Question Generator, LLM AI Chat).

  • (Optional) Quality-/Performance Characteristics:

    • High availability and low latency in request routing.

  • (Optional) Fulfilled Requirements: The architecture supports application scalability.

  • (Optional) Open Issues/Problems/Risks: No identified risks so far.

5.2.2. Client

  • Purpose/Responsibility: Provides the user interface that allows players to interact with the system, answer questions, and get hints using the LLM.

  • Interface(s):

    • Connection with the REST API to send responses and get questions.

    • Interaction with the LLM to get hints for the game.

  • (Optional) Quality-/Performance Characteristics:

    • Smooth and fast user interface with real-time updates.

  • (Optional) Fulfilled Requirements: Accessible and responsive design for various devices.

  • (Optional) Open Issues/Problems/Risks: No critical risks identified.

5.2.3. WiChat API (API Gateway)

  • Purpose/Responsibility: Manages requests between the frontend (Client) and backend services, routing them to the appropriate backend service.

  • Interface(s):

    • Forwards requests from the Client to the REST API for further processing.

    • Routes AI-related requests to the LLM AI Chat Service.

  • (Optional) Quality-/Performance Characteristics:

    • Efficient request handling and routing, ensuring that each request reaches the correct backend service.

  • (Optional) Directory/File Location: gatewayservice

  • (Optional) Fulfilled Requirements: Efficient request routing.

  • (Optional) Open Issues/Problems/Risks: Potential bottlenecks if request routing becomes too complex.

5.2.4. REST API

  • Purpose/Responsibility: Handles requests and responses between the backend services and the client, through the WiChat API (API Gateway). This container interacts with services like the Question Generator, Database, and LLM AI Chat Service, but it only receives requests routed by the API Gateway.

  • Interface(s):

    • Receives requests from the WiChat API (API Gateway), which routes requests from the client.

    • Endpoint to fetch questions from the Question Generator.

    • Endpoint to record answers and retrieve results from the Database.

  • (Optional) Quality-/Performance Characteristics:

    • Fast response time and security for API calls.

    • The routing logic is delegated to the API Gateway, allowing for a cleaner and more scalable approach.

  • (Optional) Fulfilled Requirements: Meets security and efficiency requirements for processing requests.

  • (Optional) Open Issues/Problems/Risks: scalability to handle large traffic volumes in the future, especially if routing through the API Gateway introduces any bottlenecks.

5.2.5. Database

  • Purpose/Responsibility: Stores persistent system data, including user histories, generated questions, answers, and scores.

  • Interface(s):

    • Communication with the REST API to store and retrieve data (e.g., player answers and scores).

    • Interacts with the Question Generator for managing generated questions.

  • (Optional) Quality-/Performance Characteristics:

    • High availability, query performance, and backup/recovery systems.

    • Backup and recovery systems to prevent data loss.

    • ACID compliance for consistency and durability.

  • (Optional) Fulfilled Requirements: Secure data storage, backup, and recovery.

  • (Optional) Open Issues/Problems/Risks: Ensuring data security, scalability, and ACID compliance is crucial to maintain consistency and performance. The system must also protect user data and comply with privacy regulations.

5.2.6. Question Generator

  • Purpose/Responsibility: Uses the WikiData API to automatically generate questions related to images and concepts.

  • Interface(s):

    • Connection with the WikiData API to retrieve information and generate questions.

  • (Optional) Quality-/Performance Characteristics:

    • Accuracy and relevance of the generated questions based on the WikiData knowledge base.

  • (Optional) Directory/File Location: questionservice/src/services/question_generator

  • (Optional) Fulfilled Requirements: Efficient and accurate question generation.

  • (Optional) Open Issues/Problems/Risks: No identified risks.

5.3. Component Diagram (C4 Level 3)

C4 Diagram (Level 3) Component diagram
Figure 5. Overall view of the component context

Motivation: The Component Diagram (C4 Level 3) provides a detailed breakdown of the internal components within the WIChat Application, focusing specifically on the division of the REST API into five modules for better organization and management of the system’s functionalities.

Contained Components:

Component Responsibility

AuthService

Manages user authentication and session management, ensuring secure access to the system.

GameService

Handles gameplay, including starting a game, submitting answers, and tracking player progress.

QuestionService

Manages the generation and retrieval of questions from the WikiData API.

LLMService

Interacts with the LLM API to fetch hints for players.

UserService

Manages user registration, profiles, and stores relevant data for the leaderboard.

Modules Overview:

5.3.1. AuthService

  • Purpose/Responsibility: AuthService handles the authentication and session management for users. It ensures that only authenticated users can access the system.

  • Interface(s):

    • API endpoints for login, registration, and session management.

    • Interacts with the User Database to store and verify user credentials.

  • Quality-/Performance Characteristics:

    • Secures user credentials with encryption and token management.

    • Ensures protection against unauthorized access by enforcing strict authentication mechanisms.

  • Directory/File Location: users/authservice

  • Fulfilled Requirements: Secure user login, registration, and session management.

5.3.2. GameService

  • Purpose/Responsibility: GameService handles all game-related activities such as starting a new game, submitting answers, and tracking progress.

  • Interface(s):

    • API endpoints for starting the game, submitting answers, and tracking player progress.

    • Interacts with the Game Database to store player data and responses.

  • Quality-/Performance Characteristics:

    • Low-latency, high-performance state management to ensure smooth game progress.

    • Efficient handling of player responses and game state updates.

  • Directory/File Location: gameservice

  • Fulfilled Requirements: Game flow management, including game initiation, answer submission, and progress tracking.

5.3.3. QuestionService

Motivation: The Component Diagram (C4 Level 3) provides a detailed breakdown of the internal components within the WIChat Application, focusing specifically on the division of the REST API into five modules for better organization and management of the system’s functionalities. Additionally, it includes background services such as question generation to support game content dynamically.

Contained Components:

Component Responsibility

AuthService

Manages user authentication and session management, ensuring secure access to the system.

GameService

Handles gameplay, including starting a game, submitting answers, and tracking player progress.

QuestionService

Composed of two subcomponents: QuestionStorage (for exposing question-related APIs) and QuestionGenerator (for fetching and updating question data from WikiData).

LLMService

Interacts with the LLM API to fetch hints for players.

UserService

Manages user registration, profiles, and stores relevant data for the leaderboard.

Modules Overview:

5.3.4. AuthService

  • Purpose/Responsibility: AuthService handles the authentication and session management for users. It ensures that only authenticated users can access the system.

  • Interface(s):

    • API endpoints for login, registration, and session management.

    • Interacts with the User Database to store and verify user credentials.

  • Quality-/Performance Characteristics:

    • Secures user credentials with encryption and token management.

    • Ensures protection against unauthorized access by enforcing strict authentication mechanisms.

  • Directory/File Location: users/authservice

  • Fulfilled Requirements: Secure user login, registration, and session management.

5.3.5. GameService

  • Purpose/Responsibility: GameService handles all game-related activities such as starting a new game, submitting answers, and tracking progress.

  • Interface(s):

    • API endpoints for starting the game, submitting answers, and tracking player progress.

    • Interacts with the Game Database to store player data and responses.

  • Quality-/Performance Characteristics:

    • Low-latency, high-performance state management to ensure smooth game progress.

    • Efficient handling of player responses and game state updates.

  • Directory/File Location: gameservice

  • Fulfilled Requirements: Game flow management, including game initiation, answer submission, and progress tracking.

5.3.6. QuestionService

  • Purpose/Responsibility: QuestionService is divided into two logical components: QuestionStorage exposes APIs for retrieving questions, and QuestionGenerator (or questionworker) runs in the background to fetch and update question data from WikiData.

  • Interface(s):

    • QuestionStorage: API endpoints for delivering questions to the frontend.

    • QuestionGenerator: Periodic interaction with the WikiData API and writes updates to the Question Database.

  • Quality-/Performance Characteristics:

    • Ensures players receive contextually relevant and up-to-date questions.

    • Maintains a fresh and diverse question set via automated periodic updates.

  • Directory/File Location: questionservice/

  • Fulfilled Requirements: Reliable question retrieval and automated content updating from WikiData.

5.3.7. LLMService

  • Purpose/Responsibility: LLMService is responsible for communicating with the LLM API to retrieve hints for players during gameplay.

  • Interface(s):

    • API endpoint for sending a prompt to the LLM API and receiving hints.

    • Interacts with the LLM API for natural language processing and context-based hints.

  • Quality-/Performance Characteristics:

    • Efficient interaction with external LLM services to fetch hints in real-time.

    • Ensures hints are contextually accurate and aid the player appropriately.

  • Directory/File Location: llmservice

  • Fulfilled Requirements: Provides relevant hints to players based on their game progress and context.

5.3.8. UserService

  • Purpose/Responsibility: UserService manages user registration, profile management, and stores data necessary for the leaderboard.

  • Interface(s):

    • API endpoints for user registration, updating profiles, and interacting with the leaderboard.

    • Communicates with the User Database to store and retrieve user data, including authentication details and game scores.

  • Quality-/Performance Characteristics:

    • Efficient user data management with scalable storage and retrieval mechanisms.

    • Ensures user data privacy and integrity.

  • Directory/File Location: users/userservice

  • Fulfilled Requirements: User registration, profile management, and leaderboard functionality.

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.

In this section, some sequence diagrams that represent the runtime view of the system are presented. The sequence diagrams are used to show the interactions between the building blocks of the system in different scenarios, generating a workflow that helps to imagine how the ideal interaction of a regular user with the application should be.

6.1. Registration and Login

The following sequence diagrams represent the process of registration and login in the system. The diagrams show the interactions between the user, the main API of the application, and the database, representing the steps that are followed in each scenario.

Sequential diagram of the process of registration
Figure 6. Registration Sequence Diagram
Sequential diagram representing the Log In process
Figure 7. Login Sequence Diagram

6.2. Game lifecycle

The following sequence diagram represents the lifecycle of a game in the system. The diagram shows the interactions between the user, the main API of the application, the LLM API that provides the chat to ask for hints, and the database. The different steps that can be followed will be represented.

Sequential diagram representing the interaction in a game session
Figure 8. Game’s Lifecycle Sequence Diagram

6.3. Question generation process

The following sequence diagram represents the process of generating questions in the system. The diagram shows the interactions between the Question Generator, the WikiData API that provides the answers to the questions, and the database. The information exchange process will be represented.

Sequential diagram representing the question generation process
Figure 9. Question Generation Sequence Diagram

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.

C4 Diagram (Level 1) Deployment view diagram
Figure 10. Overview of the deployment infraestructure

7.1. Infrastructure Level 1

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

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

  • important justifications or motivations for this deployment structure

  • quality and/or performance features of this infrastructure

  • mapping of software artifacts to elements of this infrastructure

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

Motivation

The above diagram illustrates the high-level deployment architecture of the WIChat application. All components, including the web client (UI) and backend services, are containerized using Docker and deployed on a cloud-based Ubuntu VM (Azure). Although the web client executes in the user’s web browser, it is served as a container from the application server. When a user connects, the browser downloads and runs the web application, eliminating the need for a distinct "Client Node."

Quality and/or Performance Features

The main advantages of this architecture are:

  • Modularity: All components are deployed as independent containers that can be updated and scaled separately.

  • Interchangeability: By the same reason as why it is modular, as long as the common API is mantained, the separation of the architecture will allow the replacement and upgrade of implementations without affecting the rest of the system.

  • Portability: Since Docker containers are platform-agnostic, the application can be easily deployed across different environments (e.g., local development, cloud production) without modification.

  • Scalability: Having a Gateway Service ensures the system can handle increased traffic by distributing requests across multiple backend instances, enabling horizontal scaling, and integrating with cloud auto-scaling tools.

Mapping of Building Blocks to Infrastructure
Building Block Infrastructure Component

Client / Frontend

Contained in the webapp subfolder. Docker container hosted on Azure. Serves the user interface and communicates with the backend via the gateway service.

Gateway Service

Contained in the gatewayservice subfolder. Docker container hosted on a cloud platform. Acts as a single entry point for all incoming requests, routing them to the appropriate services.

LLM Service

Contained in the llmservice subfolder. Configuration and API for the external service hosted by the LLM provider. Accessed from the backend to generate conversational hints.

Game Service

Contained in the gameservice subfolder. Accessed from the backend to store all the relevant information after a game is finished.

Question Generator

A separate component that runs during all the life application. Queries Wikidata using MQL to generate questions and answers, which are then stored in the MongoDB database.

Authentication Service

Contained in the authservice subfolder. Accessed from the backend to store the user information.

User Service

Contained in the userservice subfolder. Accessed from the backend to store the user information into the database.

MongoDB Database

Containerized instance.

Grafana

Containerized monitoring dashboard hosted alongside backend services.

Prometheus

Containerized metrics collection and alerting tool.

7.2. Infrastructure Level 2

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

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

7.2.1. Client / Frontend

The frontend is a single-page application (SPA) that runs in the user’s web browser. It is built using React and communicates with the backend via the API. The frontend is containerized using Docker and deployed on a cloud platform together with the rest of the components of the application. Static assets (e.g., images, CSS, JavaScript) are served via a CDN to reduce latency and improve load times.

7.2.2. APIs / Backend

The backend is a set of RESTful APIs that provide game logic, user management, and question generation services. It is built using Node.js and Express, and communicates with the MongoDB database. The backend is containerized using Docker and deployed on a cloud platform. The backend is stateless and horizontally scalable, allowing it to handle increased traffic by spinning up additional instances.

7.2.3. Proxy (NGINX)

NGINX acts as a reverse proxy and is used primarily to enable HTTPS by handling SSL/TLS termination. It is deployed as a Docker container alongside other services within the infrastructure.

7.3. Conclusion

The Deployment View provides a detailed overview of how the WiChat application will be deployed across different environments and infrastructure components. It ensures that the system meets the quality goal of scalability while supporting efficient development and deployment processes.

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

A first version of the domain model of the application, representing all the entities that interact with the application and their relations, is shown in the following diagram:

Domain Model
Figure 11. Domain Model
Entity Description

User

Represents a registered player with a unique username and password.

Score

Stores gameplay results, including game mode, accuracy, and performance.

Question

Contains the quiz question, possible answers, correct answer, and image of the question.

8.2. Design Patterns and Architectural Styles

The application will be developed following a microservices Architecture. It will have the following microservices:

  • Auth Service: It will manage the user login and the creation of the user token.

  • User Service: It will manage the signup of new users into the system.

  • Question Service: It will manage the generation of questions of different topics that the user will answer.

  • Game Service: It will store the game information on the database once the game has finished.

  • LLM Service: It will manage the interaction with the AI and it will generate the hints for the user.

  • Gateway Service: It will communicate with the rest of microservices to send the information to the frontend.

8.3. Persistence Layer

The application will rely its data persistence dependencies on a MongoDB database that will manage the data of the application related to the game sessions (questions, answers, game configurations) or related to the user (user session, user statistics…​).

In the future we will change the MongoDB that stores the users to a sqlite database, because with a relational database the user scheme will be more well defined. And several MongoDB instances will be used in the future to avoid the fall of one to affect all microservices.

MongoDB is a NoSQL database that stores data in flexible, JSON-like documents, meaning fields can vary from document to document and data structure can be changed over time. This flexibility will help to manage the data of the application, as the structure of the data may change over time as the application evolves. It is not a definite decission, but it is a good starting point to consider.

8.4. Ensuring a wealthy user experience

8.4.1. User Interface

The development team have designed the application catering to the final user, with a clean and intuitive design that will make the user experience as pleasant as possible. They have developed the application using a responsive design, so it can be used in different devices, like smartphones, tablets, or desktop computers, enhancing usability, accesibility and adaptability at the maximum possible level. For this reason, the internazionalization of the application was a key point to consider, as the application is intended to be used by any kind of users of a wide variety of ages and genders and from different countries and cultures. Right now the application is available in English and Spanish.

8.4.2. Session handling and Security

The application has incorporated a basic session handling mechanism to manage the user sessions and to provide a secure environment for the users. The session handling mechanism is be based on the use of JSON Web Tokens (JWT) to authenticate the users and to manage the user sessions.

8.4.3. Error handling

The application will include a robust error handling mechanism to manage the errors that may occur during the execution of the application. The error handling mechanism will be based on the use of custom error messages and error codes to provide meaningful information to the users and to help the developers to identify and fix the errors. Error messages will be logged to help the developers to identify and fix the errors. It will be important to have a clear and consistent error handling mechanism to ensure that the application is reliable and user-friendly, and that the user does receive only the feedback that is expected to receive (no technical message should be displayed to the final user).

8.4.4. Logging

The application will have a logging system to monitor the activity of the application and to help the developers to identify and fix the errors that may occur during the execution of the application. The logging system will be based on the use of log files to store the log messages and to provide a history of the activity of the application. The log messages will be stored in a structured format to help the developers to analyze the log messages and to identify the root cause of the errors.

8.4.5. Testing

The application is tested using a combination of unit tests, end-to-end tests, load test and usability tests.

  • Unit tests are used to test individual components of the application, mainly based on testing backend functionality to ensure that the internal part of the applications works as expected. Since the application is Dockerized in containers, unit tests can be executed within a container or in a separate testing container that has access to the application’s code and dependencies, ensuring that the tests run in an environment identical to production.

  • End-to-end tests are used to test the application as a whole, simulating the user interaction with the application. They are be performed using containers running the full application stack. This helps to ensure that the application works as expected from the user’s perspective.

  • Load tests are used to test the performance of the application using Gattling.

  • Usability tests are used to test with real users that the application works as expected.

8.5. Deployment

The application is deployed using Docker containers. Docker is a platform that allows developers to develop, ship, and run applications in containers. Containers are lightweight, standalone, and executable packages of software that include everything needed to run an application: code, runtime, system tools, system libraries, and settings. This ensures that the application runs consistently across different environments and that the deployment process remains smooth.

To enable secure HTTPS connections, a reverse proxy such as Nginx is used. Nginx handles SSL termination and routes incoming HTTPS traffic to the appropriate Docker containers. This setup ensures secure communication between clients and the application and simplifies the management of certificates and routing.

9. Architecture Decisions

9.1. Main webapp technology

Date Recorded: 10/02/2025

Scope: frontend, webapp

Description: The frontend team has opted for a modern framework that offers a combination of performance, flexibility, and developer experience. One of the team members has prior experience with this technology, making it a viable choice for building an intuitive user interface.

Decision taken: The team has decided to use React or a React framework due to the lack of expertise in maintaining a custom stylesheet.

9.2. Main backend technology

Date Recorded: 10/02/2025

Scope: backend, API

Description: The backend team is currently evaluating whether to use a monolithic Spring Boot-based approach or maintain a Node.js microservices system. One of the main reasons for considering Spring Boot is the team’s lack of experience with Node.js. Additionally, last year’s project was implemented using Spring Boot, which could facilitate development. If needed, Spring Boot provides flexibility for a future migration to microservices.

Decision taken: The team has decide to use Node.js microservices system.

9.3. Use of MongoDB

Date Recorded: 10/02/2025

Scope: database

Description: Unlike the previous year, where MongoDB was replaced by PostgreSQL, this year the team has decided to use MongoDB as the primary database system. The decision aligns with the need to store unstructured question-based data efficiently and leverage NoSQL advantages for scalability and flexibility.

Decision taken: The team has agreed to use MongoDB as the database for this project.

9.4. Architecture of the question generator process

Date Recorded: 17/02/2025

Scope: backend, question generator

Description: The question generator is a key component of the system that runs continuously. It is executed at background periodically to generate new questions. The life of the question generation is the same as the application one, as it is running concurrently. The question service is divided in question-storage to retrieve the queries from the database, question-generator who has the logic to generate questions and the question-worker which is the application running concurrently that actually generates questions.

Decision taken: The team has decided to implement the question generator as a separate concurrent application.

9.5. Connection to the database with the question generator

Date Recorded: 17/02/2025

Scope: backend, question generator, database

Description: When the questions are generated at background by the question-worker they are stored in the database "questiondb". Then when someone is playing one of ours games, the questions are retrieved from the database. Furthermore, the questions have a specific life duration, this means, that when the time specified from its creation passes, the question are eliminated from the database, the purpose of this is to avoid players to get repeated questions continuously

Decision taken: The team has decided to specify a life duration for the questions

9.6. Integration of an LLM for hints

Date Recorded: 10/02/2025

Scope: backend, AI integration

Description: The game will integrate an AI model to provide hints to players. The chosen model must be capable of interpreting image-based questions and generating meaningful hints.

Decision taken: The team has decided to integrate the Empathy AI model for generating hints in the game.

9.7. Game modes

Date Recorded: 3/03/2025

Scope: backend, frontend

Description: Discusion on wich game modes the application will have.

Decision taken: The team has decided to implement: normal game mode, expert domain, time attack and endless marathon.

9.8. Creating Game Service

Date Recorded: 14/03/2025

Scope: backend

Description: Discusion on where to implement the game functionallity.

Decision taken: The gameservice will be a new module in the future, the one who will be in charge of tracking scores of players in different gamemodes.

9.9. Generate questions

Date Recorded: 14/03/2025

Scope: backend

Description: Discusion how many questions the backend will retrieved.

Decision taken: Decided that to ease the system’s performance, the questions will be retrieved by id in batches of 5.

9.10. Generate questions

Date Recorded: 28/03/2025

Scope: frontend

Description: Discusion of the route strategy of the frontend and error page.

Decision taken: Decided to create an Error page that by default is the endpoint where the user gets redirected if he/she tries to access a site in the application that is not available and decided to keep the route strategy that we held at first, treating all the different game modes as one in terms of routing.

9.11. Use of JWT tokens

Date Recorded: 4/04/2025

Scope: backend, game service, auth service

Description: When the user logs into the application a token will be generated. We will use this token to make sure that the user is log in when we save a score after a game or when we access the user statistics.

Decision taken: The team has decided to integrate the JWT token functionallity to the game service.

9.12. Implementation of https

Date Recorded: 4/04/2025

Scope: backend, gateway service

Description: The application will have https. It will be implemnted using NGINX that acts as a reverse proxy and is used primarily to eneable HTTPS.

Decision taken: The team has decided to implement the functionallity

9.13. Score when using hints

Date Recorded: 28/04/2025

Scope: backend, frontend

Description: Discuss if we should penalize the user when he/she uses the hints provided by the ai.

Decision taken: Decide not to penalize if asking to the ia via chat as using the time left for calculating the score already penalizes the user stalling.

Contents

Important, expensive, large scale or risky architecture decisions including rationales. With "decisions" we mean selecting one alternative based on given criteria.

Please use your judgement to decide whether an architectural decision should be documented here in this central section or whether you better document it locally (e.g. within the white box template of one building block).

Avoid redundancy. Refer to section 4, where you already captured the most important decisions of your architecture.

Motivation

Stakeholders of your system should be able to comprehend and retrace your decisions.

Form

Various options:

  • ADR (Documenting Architecture Decisions) for every important decision

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

  • more detailed in form of separate sections per decision

Further Information

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

10. Quality Requirements

Content

This section contains all quality requirements as quality tree with scenarios. The most important ones have already been described in section 1.2. (quality goals)

Here you can also capture quality requirements with lesser priority, which will not create high risks when they are not fully achieved.

Motivation

Since quality requirements will have a lot of influence on architectural decisions you should know for every stakeholder what is really important to them, concrete and measurable.

Further Information

See Quality Requirements in the arc42 documentation.

10.1. Quality Tree

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.

Quality Category

Quality

Description

Performance

Responsiveness

The system is expected to respond quickly to user inputs

Concurrency

Multiple users must have service at the same time

Security

Individuality

User’s actions must not interfere with another user’s experience. For example, pressing a button in one session should not affect any other user’s game.

Robustness

The user must not see anything he’s not expected to.

User experience

Continuity

A player must be able to continue playing without issue for as long as he wishes.

Intuitiveness

The system must be easy to understand and use

Freshness

The questions on the sytem musn’t become predictable nor be the same all the time.

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.

  • Responsiveness → Every input from the frontend must have an appropiate response before a second has passed, else a loading page must be shown.

  • Concurrency → One hundred users at least must be supported simultaneously

  • Individuality → A user selecting the fourth option must not generate any option in another one’s game. Each game is a separate entity.

  • Robustness → A bad input from a user must not neither crash nor break the system.

  • Continuity → A user may play 20 games straight without pause.

  • Intuitiveness → The ui must be clean to enable non tech-savvy users to enjoy the game within 15 minutes from picking up the game.

  • Freshness → New questions must be inserted into the db to avoid any repetition of questions in a single game. Questions are to be updated every 30 minutes

10.3. Load testing results

Load test results were made on the deployed application, making use of the gatling tool. Load test results are stored on docs/loadtesting.

As you can check, on last version at the time, v1.2.0, the tool showed we passed the concurrency requirement by quite a lot: 485 users concurrently will make only a few users experience some latency, a total of 14% of the total requests, but no fairlures. >500 users does arise some errors, as we tested on 536 users and 5 errors were recorded.

The top latency responses where concentrated on saving the game, but more interestingly, the second behind it often won at the mean latency and were either requests to the leaderboard (api/leaderboard) or to the user’s statistics (api/scoresByUser).

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 name Description Probability Severity Countermeasures

Wikidata downtime

The API from where the system obtains the data and generates questions from may be unavailable at any point, rendering us unavailable to generate more questions.

Low

Low

As long as we generate large groups of questions without affecting performance, the system should not run out of questions.

LLM downtime

The API of the large language model may be unavailable at any point, rendering us unavailable to provide the ai chat.

Low

Medium

None has been decided yet.

Deployment server downtime

The deployment server may be unavailable at any point, due to our lack of server management skills. This would render us unavailable to test the application on deployment.

Medium

Medium

Mitigated by the prospect of automatic deployment using docker.

Poor documentation

Even following the clear steps layed out for us, we are inexperienced in the role of a software architect, as well as lack the experience in open source projects of a senior programmer, the project’s documentation may be lacking compared.

Medium

Low

Either trial and error or external help of some seasoned developer

MongoDb

The use of this database technology is still to be decided on, but the current placeholder has the risk of losing data consistency. Due to the eventual consistency property of some noSql systems, we may encounter situations where data becomes corrupted, more likely due to our inexperience.

Medium

Low at development, high at deployment

For now, learn about the technology and practice with it.

11.2. Technical debt

Here is listed the known negative impact of decisions taken by the team. This section is expected to increase every time one is identified.

  • The use of react, due to its many dependencies, has an extra overhead upon deployment that will slow down deployments in quick succession. For this reason, it is discouraged to make releases without completely making sure everything works and encouraged to make use of configuration files that may be modifiable on runtime.

12. Glossary

Contents

The most important domain and technical terms that your stakeholders use when discussing the system.

You can also see the glossary as source for translations if you work in multi-language teams.

Motivation

You should clearly define your terms, so that all stakeholders

  • have an identical understanding of these terms

  • do not use synonyms and homonyms

Form

A table with columns <Term> and <Definition>.

Potentially more columns in case you need translations.

Further Information

See Glossary in the arc42 documentation.

Term Definition

WIChat

The updated version of the Saber y Ganar quiz show, incorporating a new hint system powered by an external Large Language Model (LLM).

LLM (Large Language Model)

An advanced AI model used to generate hints for quiz questions in a conversational manner.

Wikidata

An external API that serves as the main source for all presented data, including questions and images.

RTVE

The organization that has hired ChattySw to update the quiz show application.

ChattySw

The software development company responsible for updating the quiz show application.

HappySw

The company that developed the previous version of the quiz show application.

Web-based system

An application that must be accessible via web browsers.

APIs for Data Access

APIs that provide access to user and question data, with proper documentation.

Prevention of Correct Answer Disclosure

Mechanisms to prevent the LLM from directly revealing the correct answer in hints.

Coding Standards

Industry best practices for maintainable code.

Version Control

Managing all source code in a repository with clear commit messages.

HTTP Protocol

A protocol used for transmitting hypertext requests and information on the internet.

MongoDB

A NoSQL database that stores data in flexible, JSON-like documents. Chosen for its ability to efficiently store unstructured question-based data and its scalability.

MongoDB Query Language (MQL)

A query language used to interact with MongoDB databases.

React

A JavaScript library for building user interfaces, particularly single-page applications.

REST API

An API that conforms to the constraints of REST architectural style and allows for interaction with RESTful web services.

Docker

A platform used to develop, ship, and run applications inside containers.

NodeJs

A JavaScript runtime built on Chrome’s V8 JavaScript engine, used for building the backend of the application.

Git

A distributed version control system used for tracking changes in source code during software development.

Swagger

A tool used for designing and documenting APIs.

Kanban

An agile framework used to manage and improve work across human systems.

INVEST Acronym

A mnemonic for writing well-formed user stories in agile development: Independent, Negotiable, Valuable, Estimable, Small, Testable.

Semantic Versioning

A versioning scheme for software that uses a three-part version number: major, minor, and patch.

Github Flow

A branch strategy for managing changes in a Git repository, emphasizing simplicity and collaboration.

Building Block View

A hierarchical collection of black boxes and white boxes that describe the system’s structure.

White Box

A detailed description of a system or component, including its internal structure and interactions.

Black Box

A description of a system or component that focuses on its external behavior and interfaces, without detailing its internal structure.

WIChat Application Proxy

Manages communication between the client and system services.

REST API Interface

Interface for managing interactions between the client and the database.

Database

Stores persistent system data, including user histories, generated questions, answers, and scores.

Sequence Diagram

A type of diagram that shows how objects interact in a particular scenario of a use case.

Registration Sequence Diagram

A sequence diagram that represents the process of user registration in the system.

Login Sequence Diagram

A sequence diagram that represents the process of user login in the system.

Game’s Lifecycle Sequence Diagram

A sequence diagram that represents the lifecycle of a game session in the system.

Question Generation Sequence Diagram

A sequence diagram that represents the process of generating questions in the system.inition-2>

Domain Model

A conceptual model that represents the entities and their relationships within the application domain.

Model-View-Controller (MVC)

An architectural pattern that separates an application into three main components: Model, View, and Controller.

Singleton Pattern

A design pattern that ensures a class has only one instance and provides a global point of access to it.

Factory Pattern

A design pattern used to create objects without specifying the exact class of object that will be created.

Observer Pattern

A design pattern where an object maintains a list of dependents and notifies them of any state changes.

Strategy Pattern

A design pattern that defines a family of algorithms, encapsulates each one, and makes them interchangeable.

JSON Web Tokens (JWT)

A compact, URL-safe means of representing claims to be transferred between two parties, used for authentication and session management.

Unit Tests

Tests that verify the functionality of individual components of the application.

Integration Tests

Tests that verify the interaction between different components of the application.

End-to-End Tests

Tests that simulate user interaction with the application to verify it works as a whole.

Deployment

The process of distributing and installing the application in a production environment, often using Docker containers.

Empathy AI Model

An AI model integrated into the game to provide hints to players. Capable of interpreting image-based questions and generating meaningful hints.

Frontend

The part of the application that interacts with the user, typically involving the user interface and user experience.

Backend

The part of the application that handles data processing, business logic, and interactions with databases and external services.

Microservices

An architectural style that structures an application as a collection of loosely coupled services. Each service is independently deployable and scalable.

Monolithic Architecture

An architectural style where the entire application is built as a single, unified unit. Easier to develop initially but can become difficult to manage as the application grows.

13. Testing Strategy and results

Contents

This section describes the project’s testing approach and results, and how quality requirements are verified through testing.

Motivation

Testing ensures the system meets its functional and non-functional (quality) requirements, increases maintainability, and reduces risks.

Form

Describe test strategies for different levels (unit, integration, E2E, etc.), tools used, and how testing supports quality attributes like performance, robustness, and usability.

Type of Test Description

Unit Testing

Each module (mainly utility and core logic functions) is covered by unit tests using Jest. Unit tests ensure that individual components behave as expected in isolation. Code coverage is enforced via sonarQube to remain above 80%, and code duplication below 3%. Mocking is used for external dependencies.

End-to-End Testing

E2E tests are implemented using a BDD approach with .feature files and step definitions (.steps.js), following the Gherkin syntax. This allows tests to be written in a human-readable form closely aligned with user stories and acceptance criteria.

Tests are executed using Jest as the runner, configured via jest_config.js. The test_environment_setup script ensures that all required services (e.g., gatewayservice, gameservice, questionservice…​) are initialized and cleaned before and after test runs.

Our E2E workflows include:

- Signing up and logging in correctly

- Starting a game and completing a full session

- Interacting with leaderboards and user statistics

Tests are automatically run in every new release via a github action, and are kept up to date with each feature release to ensure no regressions. Browser-level interactions are simulated through a headless environment or Puppeteer/Playwright depending on the test scenario.

Load Testing

As described in the load testing results section, at section 10 quality requirements (as they direcly prove or disprove our quality requirements, that is the best location for them following official arc42 documentation), load testing is conducted using Gatling and focused on critical endpoints: login, game creation, game results saving, and user statistics. Results confirm that the application supports up to 485 concurrent users with only minor latency. Load test scripts and results are stored in docs/loadtesting.

Real User Testing

Real user feedback was encouraged and requested at some points, recruiting a set of testers with different degrees of software engineering knowledge. All of them were asked to submit their findings, data that was collected and summarized here. Almost all of the submissions by the users were solved upon the new release of v2.0.0.