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.

1. Introduction and Goals

1.1. Requirements Overview

The goal of this project is to enhance the online "Saber y Ganar" quiz show application, developed last year by HappySw, with new features that incorporate large language models (LLMs) and Wikidata for a more interactive and engaging experience, as well as a multiplayer mode where the host code of the session allows mulitple players to share the same quiz game in real time with a session leaderboard.

The key functional requirements of the system are:

  • A Web frontend that presents pictures with questions for the users to answer.

  • Users must be able to register, login, and view historical data related to their game performance (e.g., number of games, correct answers, time taken).

  • The system should automatically generate questions and answers using Wikidata.

  • Hints for the questions can be obtained through interaction with an external LLM via an API.

  • The LLM should mitigate the generation of incorrect answers or hallucinations when providing hints.

  • Each question will have a correct answer and multiple distractors, all generated automatically.

  • The application must be deployable on the web and allow users to access their information via a documented API.

1.2. Quality Goals

The quality goals for the architecture are as follows:

Quality Goal Description

Scalability

The system must efficiently handle a high number of concurrent users without performance degradation, ensuring a seamless experience even under peak loads.

Reliability

The system must operate consistently under expected conditions, maintaining stability and minimizing downtime or unexpected failures.

Usability

The application must be intuitive, easy to learn, and user-friendly, enabling players to navigate, answer questions, and request hints effortlessly.

Performance

The system should deliver fast and responsive interactions, ensuring minimal delays when generating questions, processing answers, or providing hints.

Security

User data must be securely stored and accessible only to authorized users. The system must protect against unauthorized access, data breaches, and malicious activities.

These quality goals will drive architectural decisions, particularly concerning how data is processed, stored, and presented to the user, as well as how external integrations (e.g., LLM API and Wikidata) are handled.

See section 10 (Quality Requirements) for a complete overview of quality scenarios.

1.3. Stakeholders

Role/Name Contact Expectations

End Users

Users of the game

Enjoyable and engaging experience, with an easy-to-use interface and fun, dynamic gameplay.

RTVE

RTVE management

High-quality user experience, with an emphasis on scalability, performance, and security.

Development Team

ChattySw team

A robust, well-documented, and maintainable system. Clear requirements for integration with LLM and Wikidata, as well as a user-friendly interface.

2. Architecture Constraints

2.1. Technical Constraints

Constraint Justification

Web-Based System

The system must be a web application, accessible via a browser, ensuring broad accessibility and ease of deployment.

Frontend Technologies

The frontend must be developed using modern web technologies (e.g., React, Vue, or Angular) to ensure responsiveness and maintainability.

Backend Framework

The backend should use a scalable platform such as Node.js, Django, or Spring Boot to support API interactions and user management.

Database

A relational or NoSQL database (e.g., PostgreSQL, MongoDB) must be used to store user data, game progress, and question history efficiently.

Cloud Deployment

The application must be deployed on a cloud-based infrastructure (e.g., AWS, Azure, Google Cloud or Oracle) to ensure availability and scalability.

External API Integration

The system must integrate with Wikidata and an LLM API for question and hint generation. API rate limits and response times should be considered.

Performance Constraints

The application must provide real-time interaction with the LLM for hints and ensure fast response times (<1s for hints, <3s for question generation).

2.2. Organizational & Political Constraints

Constraint Justification

Company Policies

ChattySw must adhere to company-wide software development standards, including CI/CD pipelines and agile methodologies.

Collaboration with RTVE

The project must meet RTVE’s requirements and branding guidelines, ensuring consistency with existing products.

Incremental Development

The team of seven developers must follow an iterative development approach with regular deliverables.

Security and Privacy Compliance

The system must comply with GDPR regulations, ensuring user data protection and privacy.

2.3. Conventions & Guidelines

Constraint Justification

Version Control

Git and a well-defined branching strategy (e.g., GitFlow) must be used for source code management.

Coding Standards

The team must adhere to best coding practices, including style guides.

Testing Requirements

The project must include unit tests, integration tests, end-to-end tests and load tests to ensure software reliability.

Documentation Standards

All architecture decisions and API endpoints must be documented using tools like OpenAPI and Markdown.

3. Context and Scope

3.1. Business Context

The system interacts with several external entities:

  • User: interacts with the system through a web interface.

  • Wikidata: supplies data for dynamically generated quiz questions.

  • LLM Service: external LLM API used for providing hints related to quiz questions.

  • Database: the system interacts with a database storing data related to users, games and questions.

Quiz Game System - Business Context Table

Communication Partner Inputs to System Outputs from System

Player (User)

Login credentials, answer selection, hint requests, general interaction with UI

Questions, feedback, hints, scores

WikiData API

Query for quiz questions

Response with data and images

LLM Service

User questions

AI-generated hints

Database

Game data

Persistent data (user info, game states, scores…​)

Business Context Diagram

Diagram

3.2. Technical Context

The system is linked to several technical interfaces:

  • Frontend-Backend Communication: The client uses a React-based UI to communicate with the Node.js backend through RESTful API calls.

  • Backend-Database Communication: The backend of the system interacts with a database through MongoDB using Mongoose ODM.

  • External APIs: Some external APIs are used for taking advantage of services such as data retrieval (WikiData) and hint generation (LLM).

  • Security Considerations: User passwords are hashed using Bcrypt, and authentication is managed through a Gateway service and a backend authorization service.

  • Gateway: Forwards requests between different services, mainly connecting the frontend with the backend.

  • Game Service: Generates questions from WikiData and stores them in a database, ensuring access to questions is fast and reliable when playing. It is also in charge of retrieving batches of questions for the game to the frontend application and storing the game results associated to a logged in user.

  • Wihoot Service: A Node.js-based microservice using Express and Socket.io that manages multiplayer quiz sessions, including session creation, player joining, answer submission, and real-time chat via WebSocket.

Quiz Game System - Technical Context Table

Component Technology Communication Method Protocol Format

Frontend

React

REST API Calls

HTTP

JSON

Backend

Node.js + Express

REST API Calls

HTTP

JSON

Database

Mongoose (MongoDB)

Queries

TCP/IP

JSON

WikiData (via GameService)

External API

REST API, SPARQL queries

HTTPS

JSON

AI (via LLMService)

External API

REST API Calls

HTTPS

JSON

User CRUD Service

Express.js

REST API Calls

HTTP

JSON

User Authentication Service

Express.js + Bcrypt

REST API Calls

HTTP

JSON

Wihoot Service

Node.js + Express + Socket.IO

HTTP, WebSocket

HTTP, WebSocket

JSON

Security (Bcrypt)

Password Hashing

Internal Authentication

N/A

N/A

Mapping I/O to Channels

Diagram

4. Solution Strategy

In this section of the documentation we are covering the fundamental decisions and solution strategies of our project architecture. These decisions were made with a strong focus on addressing the constraints defined in Section 2: Architecture Constraints.

4.1. Technology decisions

Technology Context Why?

JavaScript

Main language used in the project

Due to our familiarity with developing web projects using JavaScript and its easy learning curve. Moreover, it is one of the most popular languages in web development today.

Node.js

Environment for the project development

Allows the execution of JavaScript at runtime and is multiplatform. It is highly compatible with our main development language and is open source.

React

Frontend development of our web application

Widely used in the web app industry, React facilitates efficient view development with techniques familiar to our team. Its learning curve is also relatively gentle for beginners.

Express

Backend/core of our web application, managing client requests

Express is straightforward to understand and leverages familiar concepts like functional programming, delegate functions, and a request/response HTTP controller structure.

Empathy API

LLM service to provide the chatbot experience. Currently under evaluation with consideration for alternatives (e.g., Empathy).

Empathy.co is a privacy-first search and discovery platform designed for eCommerce. With AI-driven search capabilities, intuitive interfaces, and a focus on trust, Empathy.co helps brands enhance customer engagement while respecting privacy. The platform supports seamless integrations, real-time insights, and customizable search solutions, empowering retailers to build meaningful shopping journeys. The demo project showcased good response times and appropriate latency, with unlimited API calls.

WikiData API

Provides information required for answering client questions during game interactions

Its easy-to-use API and the SPARQL query language enable the development team to handle diverse information requests efficiently. Additionally, its use is a project constraint.

Bcrypt

Module for encrypting sensitive application data

Offers robust hash encryption with the ability to increase the salt parameter for improved security. Its interface meets our requirements for user-related services.

Pino

Module for providing a logging system

Chosen over alternatives (Winston, Log4j-node, etc.) for its fast, straightforward logging and native JSON support, which simplifies readability and parsing.

Docker

Automates deployment using containerized services

Docker is currently the industry standard for containerized deployments, offering excellent performance and ease of management.

Oracle Cloud Infrastructure (OCI)

Hosts the application in the production stage

Selected due to our ability to obtain a free, sufficiently powerful server instance from Oracle’s infrastructure.

Gatling

Load testing tool for performance evaluation

Chosen for its ability to simulate multiple users and analyze application performance under load. It provides detailed reports and metrics, helping identify bottlenecks and optimize the system.

Puppetter

E2E testing library to control high-level operations in browsers

It is designed specifically for Node.js and our application is fully implemented in Node.js ecosystem. Moreover. Puppetter directly within the Node.js runtime, requiring no additional drivers or external processes, which simplifies setup and deployment in our application.

Socket.io

Library that allows using WebSockets to communicate clients and server bidirectionally and event-based

Its simple syntax and efficient event handling based on polling made it a suitable choice for the Wihoot implementation

4.2. Architectural design decisions

The project architecture is divided in different modules and their functionalities are delimited following a Layered pattern. Therefore, taking that in mind we can classify the project as follows.

  1. Frontend

    • Webapp
      Module that manages the pages shown to the client and communicates with the Gateway module via requests.

  2. Controller

    • Gateway Service
      Endpoint of the web application that communicates the frontend with the business logic.

  3. Service

    • User CRUD Service
      Module that carries the CRUD operations with users with the DB, including deleting, registering and updating user-related data.

    • User Authentication Service
      Module in charge of user details validation and registering. It also manages operations related to two-factor authentication.

    • User Group Service
      Module that carries the CRUD operations related to user groups.

    • Game Service
      Module that carries the game logic of the application quizzes, interacts with the LLMService and with the WikiData interface.

    • LLM Service
      Module that acts as an interface to communicate with the LLM provider API in a decoupled way. Allowing the application to consider future changes in the API provider with the same functionality.

    • Wihoot Service
      Module in charge of all the functionalities related to the multiplayer functionality of the application. It manages the game sessions and the WebSocket connections between the clients and the server.

  4. Persistence

    • MongoDB
      Module of persistence that stores the user’s information in JSON format.

Diagram

4.3. Design patterns applied

In our solution we are applying some design patterns to be aware of future changes of features in the code. Therefore, we can highlight the following patterns:

  • Façade (Unifier Interface)
    As our project will use a gateway arquitecture, we are abstracting some intern endpoints using a forwarding functionality in our gateway service.

  • Observer Wihoot service multiplayer game is based in an event polling of the WebSockets joined to the same game session code. The logic of this is handled by the socket.io module.

  • Strategy The LLM service implements the strategy pattern to easily change between LLM models and implementations, allowing us to switch between different LLM providers without modifying the core logic of the application. This is particularly useful for future-proofing the application and adapting to changes in the LLM landscape.

4.4. Decisions trade-offs

Decision Alternatives Features rejected in the decision

JavaScript

Java and C#

By using JavaScript as the main language, we reject features such as pure OOP, which Java and C# provide. The development team is well-versed in these paradigms and feels more confident using them. Moreover, using a dynamically typed language instead of a statically typed one increases the risk of runtime errors and validation issues.

Node.js

Spring Boot and .NET

As a consequence of choosing JavaScript as the main language, we also dismiss Spring Boot as a web development framework, despite having some experience with it. Additionally, we opt against .NET technologies, which are widely used in the industry and have comprehensive, unified documentation provided by Microsoft.

React

Thymeleaf and JSP

By using React, we reject HTML template engines such as Thymeleaf and JSP (which are more common in Java environments), despite having some familiarity with them.

Express

Spring Boot or JEE

By choosing Express, we dismiss the use of Spring Boot or JEE libraries for implementing web event controllers, along with their annotation-based approach, which simplifies application logic and functionality distribution.

Empathy API

Grok LLM, Gemini LLM, and Deepseek LLM

By using this API, we take the opportunity to participate in the Empathy challenge. Additionally, rejecting Google’s Gemini LLM and Deepseek LLM may reduce chatbot performance, as these models are evolving faster than Empathy’s.

WikiData API

None

This was a project constraint.

Bcrypt

Crypto (Built-in Node.js)

The built-in Node.js Crypto module reduces external dependencies. However, it provides a more generic and basic interface, which may simplify implementation.

Pino

Winston

By rejecting Winston, we lose its flexibility in supporting multiple log formats and advanced configuration options.

Docker

Podman and Kubernetes

By using Docker instead of Podman, we reject Podman’s decentralized daemon architecture, which enhances deployment security. Additionally, Podman consumes fewer resources by running each container as an independent process. Furthermore, by choosing Docker, we dismiss Kubernetes' superior performance in deploying high-availability and scalable applications.

Oracle Cloud Infrastructure

Microsoft Azure, Amazon Web Services (AWS)

By choosing Oracle Cloud Infrastructure as our deployment platform, we opt against Azure, which provides student licenses but may have higher costs for long-term use. Additionally, we reject AWS, which offers better scalability and a more flexible pricing.

Gatling

Apache Jmeter and Locust.io (among others)

By using Gatling, we reject Apache Jmeter and Locust.io, which where also presented load testing tools. Gatling is known for its high performance and scalability, making it suitable for simulating large user loads. It provides detailed reports and metrics, helping identify bottlenecks and optimize the system.

Puppetter

Selenium

Selenium is a well-established tool that supports a wide range of browsers and is ideal for cross-browser testing. Its large community and extensive documentation make it a reliable choice for many automation needs. However, Puppeteer was chosen for this project due to its faster performance, easier setup, and seamless integration with modern JavaScript frameworks.

4.5. Decisions on how to achieve the key quality goals

Quality Goal Strategy

Scalability

Using Gherkin with tools to test the performance and behaviour of the application in users load scenarios. The tool used to test the user load is yet to be confirmed, but we chose Gatling.

Reliability

The development team will apply a TDD (Test-Driven Development) to ensure that the business model behaves correctly. Besides, with an automatized Continuous Deployment strategy, the development team can deploy the project often and explore the application behaviour, considering that the logger system implemented will catch each bug occurred during the execution.

Usability

Our development will follow good desing practices taking into account user experience to make the application easy to use and as inclusive as possible, following web standards.

Performance

Using different modules specialized in monitoring the application, as Prometheus and Grafana. Besides, to identify possible bottlenecks in our application we are using Node profiling tools such as node --prof.

Security

Our application is using encrypting modules in the registry of new users and their authentification. Moreover, we have centralized the access to the application backend in a gateway service, hiding the endpoints of the application to the ones we decided.

4.6. Organizational decisions

To ensure an efficient and structured development process, we have established the following organizational strategies:

  • Version Control and Collaboration

We have adopted a Trunk-Based Development approach using Git, where each branch is dedicated to completing a specific issue. Merging changes into the main (trunk) branch requires a pull request that must be reviewed and approved by at least one other team member. This ensures code quality, reduces integration issues, and reinforces team collaboration, preventing over-specialization.

Additionally, issues could be handled by multiple team members, using the GitHub Discussions section, promoting team problem-solving and reducing bottlenecks. Moreover, during team meetings we must review each developer issues progress to identify potential difficulties and provide support, whether by offering new perspectives, detecting bugs, or adding new unit tests cases.

  • Project Management and Workflow

We use GitHub as our primary version control tool, and also using its integrated Kanban board to track progress (Projects section in GitHub). Issues are categorized and can transition through the following states:

  1. No Status

  2. TODO

  3. In Progress

  4. Testing

  5. Done

  • Continuous Deployment and Stability Checks

Once the application reaches a deployment stable functionality, we will implement a Continuous Deployment methodology. This involves deploying the application at least once per week, to verify stability in a production-like environment. This proactive approach helps detect and resolve deployment-specific bugs early, preventing major issues from being discovered too late in the process.

4.7. Implementation decisions

  • How are solved the LLM hallucinations?

We have implemented a filter function that process LLM responses to exclude any of the possible quiz answers. If a forbidden word is detected, the system retries the request a limited number of times, and if the response of the LLM is wrong then it shows an error message: "There was an error while returning your answer, please try again." To avoid any prompt engineering attempt to obtain the answer.

Known Limitations:

  1. Exact Matching: The filtering mechanism only detects exact matches of possible answers, potentially missing paraphrased answers.

  2. Retry Limit: Fixed at a finite number of retries, which may not suffice for complex cases.

  • How are questions fetched/retrieved in our application?

    • Adding Quiz Categories

We have defined an endpoint POST /quiz that accepts JSON format with different body parameters as category, wikidataQuery, wikidataCode, …​ Once the request is done automatically performs multiple requests to WikiData and stores questions for later retrieve in the quiz.

  • Retrieving Questions

We have defined an endpoint GET /game/{subject}/{numberOfQuestions}/{numberOfOptions} to retrieve the questions stored in the database regarding the subject of the quiz.

Known Limitations:

  1. Assumes valid images paths and sufficient questions/answers to retrieve or fails.

  • How is our multiplayer functionality designed?

The multiplayer functionality of the quiz game is designed to enable real-time, shared quiz sessions where multiple players can join, compete, and interact under the coordination of a host. It leverages a combination of Express.js for session management, MongoDB for persistent storage, and Socket.IO for real-time communication, as implemented in the Wihoot microservice.

Known Limitations:

  1. You have to be registered to create the game session and to join to the game session code

Sequence diagram of the behaviour:

Diagram
Diagram

5. Building Block View

5.1. Whitebox Overall System (C4 Level 1)

5.1.1. Overview Diagram

Business context diagram

Diagram

5.1.2. Motivation

The Whitebox Overall System diagram provides a high-level representation of the primary components and their interactions within the application, alongside the external systems it integrates with. This diagram is crucial for understanding the foundational architecture of the platform, showcasing the flow of data, system responsibilities, and external dependencies. It emphasizes the relationships between the various building blocks, such as the interaction between the user and the system, and how dynamic content is sourced via external APIs.

This diagram is pivotal in illustrating system interaction patterns, including user engagement with the platform and the external API interfaces used for content generation.

5.1.3. Contained Building Blocks

The key building blocks forming the overall system architecture include:

  • User: Represents the end-user of the platform, who may authenticate in order to access the game functionality. Guest users can interact with the system and participate in gameplay. However, they will have limited access such as no multiplayer mode, saving the games…​

  • Wichat EN2B Application: The core application responsible for managing game mechanics, including the generation of questions and content. It encapsulates the application’s game logic and drives the user experience. Detailed breakdowns of its internal components are explored further in later sections.

  • WikiData API: A third-party API providing structured knowledge, essential for the dynamic generation of trivia questions and content. The system queries the WikiData API for real-time data, which is used to populate game questions.

  • LLM API: Another third-party API used for providing hints in response to user queries. It leverages large language models (such as GPT-based systems) to dynamically generate contextual content for enhancing user interactions. Communication with the LLM occurs in a conversational manner, where each request includes the entire conversation history (i.e., a list of all previous messages) to ensure context and continuity across interactions.

5.1.4. Important Interfaces

The Important Interfaces section defines the key interactions between system components and explains the methods through which the business requirements are met.

  • User to System Interaction: Users engage with the system via a web client interface, which provides a rich UI experience with interactive elements such as forms, buttons, and dynamic feedback mechanisms. This client ensures a seamless user experience throughout the gameplay.

  • System to WikiData API Interaction: The Wichat EN2B application interfaces with the WikiData API using a Game service. This service is in charge of the management of all the game related modules, such as the question generation and retrieval, the game state, the statistics, etc.

  • System to LLM API Interaction: The Wichat EN2B application requests to the LLM Service the communication with the corresponding LLM, and this service is in charge of the propper connection witht the LLM.

  • Internal Services Communication: Internal services within the Wichat EN2B application communicate over RESTful APIs. For example, the Gateway Service routes incoming requests to the appropriate internal services, while the Game Service ensures game state management and flow control.

5.2. Container Diagram (C4 Level 2)

5.2.1. Container Diagram

Diagram

5.2.2. Motivation

The Container Diagram offers a more granular view of the Wichat EN2B application’s architecture, illustrating how the application is organized into discrete containers (services) and the relationships between them. This diagram is instrumental in detailing the internal structure of the system and clarifying how the platform’s various components work together to deliver its functionality.

It serves as an essential tool for understanding how user interactions are processed, how game logic is managed, and how both external and internal data sources are leveraged for seamless gameplay.

5.2.3. Contained Building Blocks

The following containers represent the primary services within the Wichat EN2B application, each with distinct responsibilities:

  • Web Application: The front-end interface between the user and the system. This container is responsible for rendering the user interface (UI) and handling user interactions. Developed using NextJS (a React framework), the Web Application ensures a responsive and dynamic experience. It communicates with internal services via API calls.

  • Gateway Service: Serves as the entry point for external API requests. This container is responsible for routing incoming requests to the correct internal services, ensuring that requests are handled efficiently and securely.

  • Game Service: This service manages the core game logic, including the flow of the game, the presentation of questions, tracking of user progress, and determining the game’s end. It also handles the game state, such as the user’s score and question set. It is responsible for generating and retrieving questions, together with retrieving the user statistics.

  • LLM Service: This container interfaces with a Large Language Model (LLM) to provide hints, explanations, and additional content to assist the user during the game. It ensures that users receive context-sensitive content, enhancing the overall gaming experience by offering real-time dynamic information. Communication with the LLM API is conducted conversationally by passing the entire message history in each request to maintain context and coherence.

  • Wihoot Service: This container manages the multiplayer game logic by letting users host or join a session to play the same quiz with other users. It was developped using sockets.

  • MongoDB Database: The database responsible for storing persistent system data, including user profiles, game states, and scores. MongoDB is used for its flexibility in handling semi-structured data and its scalability.

  • User CRUD Service: A container dedicated to managing user-specific API requests. It handles retrieval of user-related data, and management of user information such as creating, updating and deleting users.

  • User Authentication Service: Handles the authentification part of the application. This service is in charge of logging a user in, registering a new one and validanting information.

  • User Group Service: This container contains all the behaviour regarding groups such as group management (CRUD operations), joining and leaving a group.

5.2.4. Data Flow

Data flows between containers in a manner that ensures efficient communication and process execution. For example:

  • When a user logs in via the Web Application, the system authenticates the request using the User Service. Guest users are also allowed to play the existing quizzes.

  • After successful redirection, the user interacts with the Game Service.

  • The LLM Service is called when the user requests a hint.

This modular design enhances scalability, maintainability, and fault isolation, ensuring that each component is specialized in its task while working seamlessly as part of the larger system.

5.3. Component Diagram (C4 Level 3)

5.3.1. Component Diagram

Diagram

5.3.2. Motivation

The Component Diagram (C4 Level 3) provides a detailed view of the internal structure of each service, focusing on the specific routers, logic components, and models. This level of detail is essential for developers working on individual services, as it clarifies the responsibilities of each component and their relationships.

5.3.3. Contained Building Blocks

  • Gateway Service:

    • Gateway Router: Routes incoming HTTP requests to the appropriate internal services.

    • Request Dispatcher: Handles the logic for delegating requests to the correct service, ensuring communication between components.

    • Monitoring: Ensures the health and performance of the Gateway Service by tracking metrics such as request rates, response times, and error rates. This component provides insights into the system’s operational status and helps identify potential issues.

  • Game Service:

    • Middleware: Ensures only authenticated users can access to these points.

    • Game Information Router: Saves the game information and the game state.

    • Quiz Router: Is in charge of fetching questions from WikiData given the type and amount.

    • Retriever Router: Returns questions from our database given the requested parameters. It also validates the user’s answers and sends the right answer to the LLM.

    • Statistics Router: Returns the current user game statistics for a given subject or for the whole application. It also returns the leaderboard of the application, including the current user.

  • Auth Service:

    • Auth Service Router: Manages authentication-related endpoints (login, register, validate). It uses the User CRUD router internally.

  • User Service:

    • User CRUD Router: Handles user management endpoints (create, update, delete users).

    • User Model: Represents the user data structure and interacts with the database.

  • Group Service:

    • Group Router: Handles the group management endpoints (CRUD, join, leave).

    • Group Model: Represents the group data sctructure and interacts with the database.

    • This service also uses the middleware to ensure only logged users can join or create groups.

  • LLM Service:

    • LLM Router: Handles requests for hints.

    • LLM Logic: Communicates with the external LLM API to generate responses.

  • Wihoot Service:

    • Wihoot Router: Manages multiplayer games' endpoints.

    • Wihoot Model: The structure of the multiplayer data and interacts with the database.

  • External APIs:

    • WikiData API: Provides structured data for generating questions.

    • LLM API: Offers dynamic content generation, such as hints and contextual information, based on user interactions.

5.3.4. External Communication

  • External API Integration: The WikiData API is a critical external system that provides the data needed to generate game questions. The Wichat EN2B application sends HTTP requests to this API, utilizing SPARQL queries to retrieve relevant content based on predefined game rules.

  • LLM Communication: The LLM Service facilitates interaction with external language models. It generates contextual hints, descriptions, and other textual content dynamically, based on the user’s queries or the state of the game, to guide users through the experience. Communication with the LLM is conversational, where the system passes the entire list of prior messages for each new request to maintain consistency and relevance in responses.

5.3.5. Data Flow

Each router contains one or several endpoints for its respective service. These router components interact with models or external APIs to fulfill the requests, ensuring a clear separation of concerns and maintainability.

For example:

  • The Gateway routes a user request to the Game Service for game-related actions.

  • The Middleware would check if the user is authenticated previously to any operation if required.

  • The Game Service uses the Game Retriever Router and retrieves questions from the Database

  • The LLM Service communicates with the LLM throught the LLM API to generate hints or contextual responses for the user.

This modular design enhances scalability, maintainability, and fault isolation, ensuring that each component is specialized in its task while working seamlessly as part of the larger system.

6. Runtime View

This section focuses on describing the behaviour and interactions of the system’s building blocks in form of scenarios.

6.1. User registration

Users must create an account if they do not have one. The behaviour of the application is:

Register diagram

The errorless behaviour will be:

  1. The new user types the required information to create an account.

  2. Then, this information is verified (in the frontend in order not to overload the server with unnecessary requests). If the user manages to bypass this validation, the backend also verifies the data so that invalid data cannot reach the database.

  3. After that, the password is encrypted and a new user with the username, the encrypted password, its role and date of creation is made.

  4. This new user is then saved into the database.

  5. And sent back as the response.

6.2. User login

Users must have an account to use the application. The following sequence diagram shows how the application behaves when logging in.

Login diagram

This is the behaviour of the flawless execution of the login:

  1. The user types an username and a password.

  2. After that, the credentials are checked and validated, and asks the database to find the user for the given username.

  3. The database returns the user.

  4. The Authentication Router verifies that the encrypted password given by the user and the encrypted password stored in the database match. If this happens, a JWT Token that expires in 1 hour is generated and sent.

  5. User logs in.

6.3. Game example

Here is the sequence diagram when playing the game.

Game diagram

  1. The user plays a game.

  2. The application retrieves questions for that game from the database.

  3. Then, the questions are shown to the user one by one.

  4. When the game finishes, the app then saves all the information needed about the game to the desired format.

  5. The game is then saved in the database.

In the case user asks for hints:

  1. The player types a question for the LLM.

  2. The application collects the prompt and sends it to the LLM.

  3. The LLM makes the answer and returns it.

  4. The chat recieves it and shows the generated answer to the user.

6.4. Exceptions and Errors Scenarios

Possible errors regarding:

  • Registering:

    • Invalid credentials (empty / blank).

    • Passwords do not match.

    • Username and passwords doo not meet the minimum numer of characters.

    • Using credentials from an already existing user: usernames must be different.

    • Database exception: connection lost, data loss.

  • Login:

    • Empty or blank credentials.

    • Username does not exist.

    • Wrong password.

    • Database exception: connection lost, data loss.

  • Game:

    • Wikidata error.

    • Database exception: connection lost, data loss.

    • LLM not answering to the user’s prompt.

    • LLM hallucinations

7. Deployment View

7.1. Infrastructure Level 1

The application will be deployed on an oracle server, using docker to run the different modules of the application. The application will use the wikidata API to get the different questions and answers of the game and an LLM API to do calls to the llm so that the user can interact with it and, for example ask for hints.

All of this will be deployed in an oracle server running ubuntu with the help of docker.

UML diagram 1

Motivation

The motivation behind the design of this application is to create a scalable, flexible, and secure system that can efficiently integrate with external APIs (such as Wikidata), while providing seamless user interactions through a web application. The core of the system revolves around managing various API calls, handling data storage, and ensuring a robust system that can keep up with the user demands.

To achieve this, we utilize a containerized microservices architecture, where each service (such as the Game Service, User Management, and API Gateway) is isolated in its own container. This separation allows for efficient scaling, improved fault tolerance, and the ability to update individual services independently. Additionally, the use of MongoDB ensures flexible, high-performance storage, while the API Gateway acts as a single entry point for all external and internal communication, providing load balancing, routing, and security functionalities.

The overall design enables the application to handle varying levels of demand, from individual user interactions to large-scale data processing, all while maintaining a high degree of security and performance. This approach not only supports future growth but also ensures that the system is easy to maintain and evolve over time.

7.2. Infrastructure Level 2

7.2.1. Oracle ServerApplication

UML diagram 2

Quality and/or Performance Features

Our system consists of several key containers that work together to ensure a smooth and scalable user experience. Below are the core features and quality attributes that define the system’s architecture:

Key Features

Web Application: The web app serves as the user interface where users interact with the system. It connects to the Gateway Service to make API calls and process user actions.

  • Endpoints

    GET /adduser - Shows the registration form
POST /adduser - Sends the sign up information to the gateway service
GET /login - Shows the login form
POST /login - Sends the login information to the gateway service
GET / - Shows homepage with categories, stats and leaderboard.
GET /quiz/category/:id - Shows quizzes for a category and starts gameplay.
GET /quiz/custom - Shows the custom quiz form to customize it.
GET /guest/home - The home page for guests which does not have full functionality.
GET /guest/quiz/category/:id - Shows quizzes for a category and starts gameplay.

Gateway Service: The central point for routing all incoming requests. It ensures security, authentication, and routing to the appropriate service, whether it’s the LLM Service, User-related services, or the Game Service.

  • Endpoints:

    • Authentification Management Endpoints

      POST /login - Authenticates a user and returns a token.
POST /adduser - Registers a new user in the system.
POST /setup2fa - Sets up two-factor authentication for a user.
POST /verify2fa - Verifies a two-factor authentication code.
GET /check2fa - Checks if two-factor authentication is enabled for a user.
GET /token/username - Retrieves the username associated with a provided token.

    • User Management Endpoints

      POST /users - Creates a new user.
GET /users - Retrieves a list of users.
GET /users/:username - Retrieves user details by username.
PATCH /users - Updates user information.
DELETE /users - Deletes a user.
POST /users/by-ids - Retrieves users by a list of IDs.
GET /users/id/:id - Retrieves user details by user ID.
PATCH /users/:username - Updates the username for a specific user.
POST /user/profile/picture - Uploads a user's profile picture.
GET /user/profile/picture/:id - Retrieves a user's profile picture by ID.

    • Group Management Endpoints

      GET /groups - Retrieves a list of groups.
GET /groups/joined - Retrieves group the user has joined.
GET /groups/:name - Retrieves details of a specific group by name.
POST /groups - Creates a new group.
PATCH /groups - Updates group information.
DELETE /groups - Deletes a group.
POST /groups/join - Allows a user to join a group.
POST /groups/leave - Allows a user to leave a group.

    • LLM Service Endpoints

      POST /askllm - Sends a question to the LLM service and returns a response.

    • Game Service Endpoints

      GET /quiz/allTopics - Retrieves all available quiz topics.
GET /quiz - Retrieves quizzes or quiz-related information.
GET /quiz/:topic - Retrieves quizzes for a specific topic.
POST /quiz - Creates or submits a quiz.
GET /game/:subject/:totalQuestions/:numberOptions - Retrieves questions for a game based on subject, total questions, and number of options.
POST /game - Creates or processes a game session.
POST /question/validate - Validates a question response.
GET /question/internal/:id - Retrieves internal question details by ID (restricted to LLM service origin).
GET /question/amount/:code - Retrieves the number of questions associated with a specific code.

    • Statistics and Leaderboard Endpoints

      GET /statistics/recent-quizzes - Retrieves recent quizzes with pagination support.
GET /statistics/subject/:subject - Retrieves statistics for a specific subject.
GET /statistics/global - Retrieves global statistics across all subjects or quizzes.
GET /leaderboard - Retrieves the global leaderboard.
POST /leaderboard/group - Retrieves the leaderboard for a specific group.

    • Image Proxy Endpoint

      GET /images/:image - Proxies image requests, routing to the user service for profile pictures or the game service for other images.

    • Health and Metrics Endpoints

      GET /health - Checks the health status of the gateway service.
GET /health-metrics - Provides Prometheus-compatible health metrics for the gateway service.

    • API Documentation

      GET /api-doc - Serves the OpenAPI documentation for the API (if openapi.yaml is present).

LLM Service: A container dedicated to handling calls to the LLM API for processing user queries.

  • Endpoints

    POST /askllm - Provides a hint to the player

User CRUD Service: Handles the CRUD operations for user data, interacting with the MongoDB database for persistent storage.

  • Endpoints

    POST /users - Creates a user with hashed password (bcrypt).
GET /users - Rerieves all users
GET /users/:username - Retrieves a specific user
POST /users/by-ids - Retrieves users by a list of IDs.
GET /users/id/:id - Retrieves user details by user ID.
PATCH /users/:username - Updates the username for a specific user.
POST /user/profile/picture - Uploads a user's profile picture.
GET /user/profile/picture/:id - Retrieves a user's profile picture by ID.

User Authentication Service: Responsible for managing user authentication, ensuring that secure access to the application is maintained.

  • Endpoints

    POST /login - Validates credentials and returns a JWT
POST /register - Registers user via User Service and returns a JWT
GET /token/username - Gets the user details using the token
POST /validatePassword - Validates the password
POST /setup2fa - Sets up the 2fa for the user
POST /verify2fa - Verifies the 2fa
GET /check2fa - Checks if the user has 2fa enabled

User Group Service: Responsible for managing group data, interacting with the database for persistent storage.

  • Endpoints

    GET /groups - Retrieves all groups.
GET /groups/joined - Gets the group the authenticated user belongs to.
GET /groups/:name - Retrieves a group by its name.
POST /groups - Creates a new group with the provided name.
PATCH /groups - Updates the name of the authenticated user's group.
DELETE /groups - Deletes the authenticated user's group.
POST /groups/join - Joins the authenticated user to a group by name.
POST /groups/leave - Removes the authenticated user from their group.
GET /groups/topGroups - Retrieves the top 10 groups by score.

Game Service: Manages the game-related API calls, processing user inputs and interacting with external services like the Wikidata API to answer game-related questions.

  • Endpoints

    GET /quiz - Retrieves all quizzes.
GET /quiz/allTopics - Lists all unique quiz categories.
GET /quiz/:topic - Retrieves quizzes for a specific topic.
POST /quiz - Creates a new quiz with provided data and saves questions.
POST /game - Saves game data for the authenticated user.
GET /game/:subject/:numQuestions?/:numOptions? - Retrieves random questions for a game by subject.
POST /question/validate - Validates a user's answer to a question.
GET /question/internal/:id - Retrieves the correct answer for a question by ID.
GET /question/amount/:code - Counts questions for a specific subject.
GET /statistics/subject/:subject - Retrieves game statistics for a subject for the authenticated user.
GET /statistics/global - Retrieves global game statistics for the authenticated user.
GET /statistics/recent-quizzes - Retrieves recent quizzes for the authenticated user.
GET /leaderboard - Retrieves the top 10 players and the authenticated user's rank.
POST /leaderboard/group - Retrieves leaderboard for a specific group of players.
POST /leaderboard/calculateGroupScores - Calculates total scores for provided groups.

Wihoot Service: Manages the multiplayer-related API calls, processing multiple user inputs and synchronizing them.

  • Endpoints:

    POST /create - Creates a new shared quiz
GET /internal/quizdata/:code - Finds a shared quiz given the code
POST /:code/join - Joins a user to the given session
GET /:code/start - Starts the session. This is only available for the host
GET /:code/next - Moves to the next quiz question
POST /:code/answer - Submits an answer for a question
GET /:code/status - Gets the session status and the players
GET /:code/end - Finishes the session. This is only available for the host
DELETE /:code/player/:playerId - Removes a user from the session

MongoDB Database: Stores user data, including authentication, CRUD and group-related data, as well as game data, and ensures data integrity and persistence.

By organizing the system into these clear, well-defined containers, we ensure that each component can evolve independently, maintain security, and scale as required while providing a robust user experience.

8. Cross-cutting Concepts

8.1. 1. Domain and Integration Concepts

The WIChat system relies on the seamless integration of multiple external sources to generate dynamic content:

8.1.1. Integration with External Sources

WIChat leverages external data from Wikidata and a Large Language Model (LLM) for automatically generating questions, hints, and related images. This integration follows RESTful API principles with JSON as the primary data exchange format. Key considerations include:

  • API Gateway and Mediator Pattern: An API gateway is implemented to manage and route requests to external services. A mediator layer decouples the integration logic from core business functionalities.

  • Asynchronous Processing: To improve performance and responsiveness, calls to external services are handled asynchronously. This includes the use of message queues to decouple request processing and ensure smooth operation during peak loads.

  • Error Handling and Retry Logic: Robust error handling mechanisms are in place to manage API failures or slow responses. Automated retries, circuit breakers, and fallback strategies are applied to minimize disruption.

  • Data Validation: Incoming data from external sources is rigorously validated to prevent issues like data inconsistency or LLM hallucinations, ensuring that only high-quality information is used in the application.

8.1.2. Integration Patterns

The architecture employs several integration patterns to maintain loose coupling and facilitate scalability:

  • Adapter Pattern: Custom adapters transform external data into the internal domain model, allowing for easy substitution of external providers.

  • Event-driven Architecture: Events triggered by external data changes or updates allow the system to react in real time, further enhancing responsiveness.

  • Quality Assurance: Implementing automated testing and validation processes ensures that generated content meets predefined standards before being published.

8.2. 2. Content Generation Management

Given that images, hints, and questions are generated dynamically, it is crucial to maintain content quality and consistency:

8.2.1. Business Rules and Validation

  • Quality Assurance: Business rules are established to filter and validate automatically generated content. Confidence thresholds are defined to determine acceptable levels of uncertainty in LLM responses.

  • Fallback Strategies: In cases where the content does not meet quality standards, predefined fallback strategies are triggered. These may include generating content from alternative data sources or providing default hints.

  • Caching Mechanisms: Frequently requested or computed data is cached to reduce latency and minimize redundant calls to external APIs.

  • Logging and Monitoring: Detailed logs capture content generation events and errors, enabling continuous monitoring and rapid debugging of issues.

8.3. 3. Security and Access Control

Ensuring the security of user data and the integrity of system operations is paramount:

8.3.1. Authentication and Authorization

  • Robust Authentication: Secure user authentication methods (multi-factor authentication) are employed to verify user identity.

  • Fine-grained Authorization: Role-based access control (RBAC) mechanisms ensure that users only have access to permitted functionalities and data.

  • Session Management: Secure session handling is enforced, including session timeout and token revocation policies.

8.3.2. Data Protection and Privacy

  • Encryption: All sensitive data, both in transit and at rest, is protected using industry-standard encryption protocols (e.g., TLS, AES).

  • Compliance: The system adheres to relevant data protection regulations and standards, ensuring user privacy and legal compliance.

8.4. 4. Scalability and Performance

The architectural design of WIChat ensures that the system can handle fluctuating loads and maintain high performance:

8.4.1. Scalability Strategies

  • Horizontal and Vertical Scaling: The system is designed to support both horizontal scaling (adding more servers) and vertical scaling (enhancing server capacity) as needed.

  • Caching and Asynchronous Processing: Use of caching (e.g., in-memory caches, CDN) and asynchronous processing helps minimize latency and improve throughput during high demand periods.

8.4.2. Performance Optimization

  • Resource Monitoring: Continuous monitoring of system metrics (CPU, memory, network usage) ensures that performance remains within acceptable thresholds.

  • Optimized Data Access: Database queries and data storage mechanisms are optimized to support rapid data retrieval and updates.

8.5. 5. Consistency in User Experience (UX)

A unified user experience is essential for user satisfaction and system usability:

8.5.1. UI/UX Guidelines

  • Design Consistency: Adherence to a comprehensive style guide ensures that all user interfaces are consistent in terms of colors, typography, and layout.

  • Responsive Design: The application is designed to function seamlessly across various devices, including desktops, tablets, and smartphones.

  • User-Centered Design: Interfaces are crafted based on user feedback and usability testing, ensuring intuitive navigation and interaction.

  • Real-Time Feedback: Mechanisms for providing immediate feedback (e.g., progress indicators, confirmation messages) enhance the overall user experience.

8.5.2. Continuous UX Improvement

  • Analytics and User Testing: Ongoing collection of user interaction data and periodic usability tests help refine the user experience.

  • Iterative Design: The design process is iterative, incorporating regular updates based on evolving user needs and technological advancements.

9. Architecture Decisions

For the sake of extensibility, the architechural decisions will be documented in the discussion linked.

10. Quality Requirements

This section documents all quality requirements for the system by using a quality tree and concrete scenarios. It builds upon the quality goals defined in section 1.2 and expands them.

The information provided here aligns with stakeholder expectations and allows for a measurable assessment of whether the system meets the defined quality criteria.

10.1. Quality Tree

The quality tree organizes the relevant quality attributes of the system starting from the root node "Quality/Usefulness" and is divided into the following primary categories:

Quality Attribute Description

Scalability (Priority: High)

The system must handle a large number of concurrent users without noticeable performance degradation.

Reliability (Priority: High)

The system must be resilient to failures—particularly in communication with the hints generation API—to ensure an uninterrupted user experience.

Usability (Priority: High)

The application should have an intuitive, user-friendly interface, enabling users to register, understand, and engage with the system quickly.

Performance (Priority: Medium)

The system must deliver rapid responses—especially when generating questions and hints—to maintain a smooth and efficient user experience.

Security (Priority: High)

The system must safeguard user data through robust encryption and strict access control measures.

This structure can be visualized with a mind map or hierarchical diagram. For example, the following PlantUML diagram illustrates an example quality tree:

Diagram

10.2. Quality Scenarios

For each quality attribute in the tree, specific scenarios have been defined to articulate the expected system behavior under certain conditions. These scenarios include both usage scenarios (demonstrating normal operational performance) and change scenarios (illustrating the system’s response to modifications or unexpected events).

Quality Attribute Scenario Priority

Scalability

Load Scenario: When 10,000 users are concurrently active, the system must maintain a response time below 2 seconds for critical operations such as login and loading the game interface.

High

Reliability

API Failure Scenario: If the external hints generation API fails, the system must activate a backup mechanism (e.g., preloaded hints or informative messages) and log the incident, ensuring the game continues uninterrupted.

High

Usability

User Onboarding Scenario: A new user should be able to register, comprehend the application’s functionalities, and begin playing within 3 minutes, requiring fewer than 3 interactions (clicks) to access the main features.

High

Performance

Response Time Scenario: Upon requesting a hint or answering a question, the system must process and deliver the information within 1 second, ensuring a seamless user experience.

Medium

Security

Unauthorized Access Scenario: In the event of an unauthorized access attempt, the system must deny access, log the incident, and ensure that all user data remains protected through encryption and robust authentication.

High

Additionally, change scenarios—such as incorporating new functionalities or adapting to fluctuations in user demand—are considered. These scenarios will help evaluate the system’s capacity to evolve without compromising its key quality attributes.

The review and validation of these scenarios with stakeholders ensure that the quality requirements are aligned with the overall project objectives and provide clear guidance for architectural decisions throughout the system’s lifecycle.

11. Risks and Technical Debts

11.1. Identified Risks and Technical Debts

Below is a prioritized list of technical risks and debts identified in the current system architecture:

  1. Dependency on External APIs

    • Risk: The system relies heavily on external services (e.g., Wikidata API) for core functionality. Any downtime, rate-limiting, or changes to the API could disrupt the application.

  2. Slow Question Retrieval

    • Risk: If not developed correctly, the application’s speed can be severely impacted by the retrieval of questions, therefore impacting the user experience.

    • Mitigation:

      • Develop a kind of cache or similar system for the questions, so the user doesn’t have to wait for all of them to load.

  3. Reliance on Oracle Server

    • Risk: The team will deploy the application on an Oracle server, which was created using a free account. Although chances of losing this service are small, per contract they are still possible. The alternative would be to deploy on a personal computer, but that entails depending on a teammate’s computer being available when needed.

    • Mitigation:

      • Have another teammate set up an additional Oracle account, or a similar service, with a backup server to be used if needed.

  4. Starting from Scratch

    • Risk: The team has decided to start from scratch. This is beneficial because the team doesn’t have to decipher other people’s code, but it also means the team must figure out how to do everything from the ground up.

    • Mitigation:

      • Although the team is building everything from scratch, we can still reference previous years' projects to identify and resolve potential problems that have already been addressed.

  5. Hardcoded Configuration

    • Risk: Certain values (e.g., image directory path, API endpoints) are hardcoded in the codebase, reducing flexibility. Changes require code modifications and redeployment, slowing down maintenance.

    • Resolution:

      • Move configurations to environment variables or a configuration file.

      • Document all configurable settings for easier management.

  6. Technical Skill Gaps

    • Risk: The development team may lack certain technical skills required to maintain and enhance the system.

    • Mitigation:

      • The development team should experiment with and study the different technologies used, either independently or with guidance from a team member who has more expertise.

12. Glossary

Term Definition

Backend

The server-side component of the system, handling API requests, game logic, and data management.

Large Language Model (LLM)

An external AI model integrated into the system via an API to generate hints for quiz questions, aiming to avoid hallucinations or incorrect responses.

Wikidata

A free, collaborative knowledge base providing structured data, used by the system to automatically generate quiz questions and answers.

API

Application Programming Interface; a set of rules allowing communication between software components, e.g., RESTful APIs for user data and question creation.

Question Generation

The process of automatically creating quiz questions, correct answers, and distractors using data retrieved from Wikidata.

Hints

Contextual assistance provided to users during gameplay, generated by the LLM via an API call, based on the question or user input.

Distractors

Incorrect answer options presented alongside the correct answer in quiz questions to challenge the user.

Game Modes

Different gameplay variations, e.g., “Each wise man with his subject,” “Travel with us,” or “The hot question,” offering diverse user experiences.

Scalability

The system’s ability to handle a large number of simultaneous users without performance degradation, a key quality goal.

Reliability

The system’s robustness in handling failures (e.g., LLM API downtime) while maintaining a seamless user experience, a key quality goal.

Usability

The ease with which users can navigate and interact with the application, ensuring an intuitive and engaging experience, a key quality goal.

Performance

The system’s ability to provide fast responses (e.g., <1s for hints, <3s for question generation), a key quality goal.

Security

The protection of user data through encryption, authentication, and compliance with GDPR, a key quality goal.

Game Service

A backend service managing game logic, question presentation, and interaction with external APIs (Wikidata and LLM).

RESTful API

A style of API design using HTTP methods (e.g., GET, POST) for communication between the frontend, backend, and external services.

CRUD Operations

Create, Read, Update, Delete operations managed by the system for handling user data in the database.

Gateway Service

The central entry point for routing external and internal API requests, ensuring security and load balancing.

Players

End-users of the application who register, login, and participate in the quiz game, expecting an enjoyable and dynamic experience.

Administrators

Users responsible for managing game content, monitoring system performance, and maintaining integrity, typically from ChattySw or RTVE.

Cloud Deployment

The practice of hosting the application on a cloud infrastructure to ensure availability, scalability, and ease of maintenance.

Hallucinations

Incorrect or fabricated responses generated by the LLM, which the system aims to mitigate when providing hints.