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 ChattySw, with new features that incorporate large language models (LLMs) and Wikidata for a more interactive and engaging experience. In our case the game with its enhancements will be made ultimately from scratch, utilizing/taking a look at some code from last year’s app for guidance/help.

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.

  • Creation of two well documented APIs for accessing user data and the question creation tool.

  • There is a possibility for users to interact with the application in different game modes, such as “Each wise man with his subject,” “Travel with us,” or “The hot question.”

Optional features include internationalization, mobile version, users' ranking, multiplayer capabilities, and personalized game settings like adjusting time limits and the scope of questions.

1.2. Quality Goals

The quality goals for the architecture are as follows:

Quality Goal Scenario

Scalability

The system must be able to handle a large number of simultaneous users without a noticeable decrease in performance.

Reliability

The system must be robust enough to handle failures in the hint generation API and ensure the user experience is minimally impacted.

Usability

The application must be intuitive and easy to use, allowing users to quickly understand how to play, answer questions, and interact with hints.

Performance

The system should provide fast responses, particularly in generating questions and hints, without delays that impact the user experience.

Security

The system must ensure that user data is securely stored and accessible only to authorized users.

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.

1.3. Stakeholders

Role/Name Contact Expectations

Players

Game users

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

Administrators

Admin users

Effective tools for managing game content, monitoring performance, and maintaining system integrity.

RTVE / Teachers

RTVE management / Teachers

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

Development Team

ChattySw

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

A Web frontend must be developed to ensure a modern, responsive, and maintainable user experience.

Backend Framework

The system should include a backend aiming to support efficient API interactions and robust user management.

Database

The system must use a database 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, or Google Cloud) 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 (e.g., PEP 8 for Python, Airbnb Style Guide for JavaScript).

Testing Requirements

The project must include unit tests, integration tests, and end-to-end 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 user-related data.

Quiz Game System - Business Context Table

Communication Partner Inputs to System Outputs from System

Player (User)

Login credentials, answer selection and hint requests

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

Business context diagram

3.2. Technical Context

The system is linked to several technical interfaces:

  • Frontend-Backend Communication: The client uses React.js 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.

  • User Gateway: Handles user-related API requests, routing authentication and CRUD operations to their respective services.

  • Game Service: Manages game logic and caches question batches to reduce WikiData API overhead.

Quiz Game System - Technical Context Table

Component Technology Communication Method Protocol Format

Frontend

React.js

REST API Calls

HTTPS

JSON

Backend

Node.js + Express

REST API Calls

HTTPS

JSON

Database

Mongoose (MongoDB)

Queries

TCP/IP

JSON

WikiData (via GameService)

External API

REST API, SPARQL queries

HTTPS

JSON/XML

AI (via LLMService)

External API

REST API Calls

HTTPS

JSON

User Gateway

Express.js

REST API Calls

HTTPS

JSON

User CRUD Service

Express.js

REST API Calls

HTTPS

JSON

User Authentication Service

Express.js + Bcrypt

REST API Calls

HTTPS (OAuth2)

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.

Groq API (Not yet decided)

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

Groq API is a flexible service that uses interchangeable LLM models. It allows for the underlying model to be swapped by simply changing the API URL and key. The demo project showcased efficient response times and appropriate latency, with support for up to 1,000 API calls daily.

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.

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

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

  3. Service

    • UserGateway
      Endpoint of user information related requests. This endpoint is used to isolate the access control to user’s information.

    • UserAuthenticationService
      Module that manages the login operation and verifies the client connection.

    • UserCRUDService
      Module that carries the CRUD operations with users with the DB. Moreover, it also manages groups of users and retrieves all user-related information.

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

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

  4. Persistence

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

Architecture design

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:

  • Facade (Unifier Interface)
    As our project will use a LLM module, we have consider the possibility that perhaps we have to change API provider suddenly for a performance or other reason. Therefore, an interface that hide the specific interface of a provider will reduce the coupling in its API.

  • Strategy
    We have considered an optional requirement that include game different modes. Therefore, a game could delegate the logic of an specific mode to an interface, a GameMode interface that is linked once the game is created.

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.

Groq API

Empathy LLM, Gemini LLM, and Deepseek LLM

By using only the Meta API, we miss 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 Meta’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.

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 decide, perhaps K6 or a Python script.

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 such as implementing i18n technology to allow internationalization, respecting the W3C standards in web design where possible and

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

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 is required to authenticate in order to access the game functionality. Once authenticated, users can interact with the system and participate in gameplay.

  • 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 question generator module. This module sends HTTP requests containing SPARQL queries to retrieve structured knowledge from WikiData, which is subsequently processed and used to generate game questions.

  • System to LLM API Interaction: The Wichat EN2B application communicates with the LLM API by passing the entire chat history of the logged-in user in each request. This ensures that the language model has full context of the ongoing conversation, enabling the generation of hints and responses that are contextually relevant and consistent with previous exchanges.

  • 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 React, 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.

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

  • 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 Gateway: A container dedicated to managing user-specific API requests. It handles user authentication, session management, and retrieval of user-related data, ensuring secure and personalized experiences.

  • User Authentication Service: Manages user authentication processes, validating user credentials and ensuring secure access to the platform. It integrates with third-party authentication mechanisms when required.

  • User CRUD Service: Manages the Create, Read, Update, Delete (CRUD) operations for user data. It ensures that user profiles can be created, updated, or deleted, facilitating efficient user management.

  • WikiData API: A third-party external API that provides structured data for generating trivia questions and content. The Wichat EN2B application communicates with WikiData to fetch real-time data using SPARQL queries.

  • LLM: This container represents the external Large Language Model service that dynamically generates content such as hints and contextual information based on user interactions. It interacts with an advanced language model, such as GPT or similar technologies, to offer real-time, personalized content.

5.2.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.2.5. 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 Authentication Service.

  • After successful authentication, the user interacts with the Game Service, which may request data from the WikiData API to generate a question.

  • The LLM Service is called when the user requests a hint, and the entire conversation history is sent to the LLM API in each request to provide context-sensitive guidance and responses.

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. Them, AddUser.js (from package webapp) collects this information and sends it via post to the "/addUser" url.

  3. The Gateway Service will answer to this petition by forwarding the petition to the User Service and saving the user data to the response (if any error happened, it would be saved here).

  4. The User Service then verifies that all the necessary credentials are stored in the request.

  5. It encrypts the password and creates a new User object with the username and the encrypted password.

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

  7. 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. Then the Login.js (from the webapp package) collects this data and sends it via post to the "/login".

  3. In the gateway service, a function answers to this request: forwards the petition to the User Authentication Service and saves the user data to the res, or when an error occurs, the error is saved to that variable.

  4. After that, the User Authentication Service checks and validates the given data, and asks the database to find the user for the given username.

  5. The database returns the user.

  6. The User Authentication Service verifies that the encrypted password given by the user and the encrypted password stored in the database match. If this happens, a JWT Token is generated and saved to the response.

  7. Shows visual confirmation of the login.

6.3. Game example

Here is the sequence diagram when playing the game.

Game diagram

  1. The application requests the questions to show the user.

  2. Gateway Service answers this request and forwards the petition to the Game Service.

  3. Game Service then uses RouterQuestionRetriever.

  4. This class retrieves the number of questions desired from the database.

  5. RouterQuestionRetriever returns the list of questions with answers in a .json file.

  6. Game Service recieves these questions and forwards the data to the Gateway Service.

  7. Then, the Gateway Service forwards them to the application which shows them to the user one by one.

  8. When the game finishes, the app then requests to save the game results.

  9. This request is answered and then forwarded by the Gateway Service and then, Game Service.

  10. Game Service parses the game information to a valid format so it can be saved to de database.

  11. Then this version of the game is sent back to the Game Service to be forwarded to the User Service. This is to reduce workload of the Game Service.

  12. The User Service asks the User CRUD Service to save the game.

In the case user asks for hints:

  1. The player types a question for the LLM.

  2. The application collects the prompt and forwards it to Gateway Service.

  3. The aforementioned service then forwards it to the Game Service which then sends it to the LLM Service.

  4. This service then validates the fields making sure the needed information needed is passed in the request and then sends the question to the LLM.

  5. The LLM makes the answer and returns it to the LLM Service.

  6. After that, the LLM Service parses the answer to json and sends it as the response of the petition.

  7. The Game Service recieves it and forwards it to the Gateway Service and then to the Application, which shows the generated answer to the user.

6.4. Exceptions and Errors Scenarios

Possible errors regarding:

  • Registering:

    • Invalid credentials (empty / blank).

    • 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 /signup` - Shows the signup screen to the user
`POST /signup` - Sends the sign up information to the gateway service
`GET /login` - Shows the signup screen to the user
`POST /login` - Sends the sign up information to the gateway service
`GET /quiz` - Shows the user a question from a quiz whose theme is specified as parameter
`POST /quiz` - Submits the answer to the gateway service
`GET /edit`- Shows the user a form in order to edit their data
`POST /edit` - Sends the updated information to the gateway service
`GET /stats` - Shows the user their game stats

  • 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

`GET /health` - Shows health status of the system
`GET /quiz` - Retrieves quiz questions
`POST /quiz` - Submits user answers
`POST /login` - Authenticates user requests
`POST /adduser` - Registers new users
`POST /edituser` - Edits user information
`GET /stats` - Requests a user historical playing data
`POST /askllm` - Sends a question to the LLM Service

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

Endpoints

`POST /hint` - Provides a hint to the player

  • User Gateway: Manages user-related API calls, including user authentication and CRUD operations.

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

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

Endpoints

`GET /users` - Retrieves a list of all users (admin use)
`POST /users/search` - Searches for users based on filters (e.g., username, email)

  • 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 a batch of quiz questions from WikiData
`POST /quiz` - Validates a user's answer

  • MongoDB Database: Stores user data, including authentication and CRUD-related 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

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

<explanation>

8.2. <Concept 2>

<explanation>

…​

8.3. <Concept n>

<explanation>

9. Architecture Decisions

Contents

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

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

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

Motivation

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

Form

Various options:

  • ADR (Documenting Architecture Decisions) for every important decision

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

  • more detailed in form of separate sections per decision

Further Information

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

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 is planning on deploying 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.

User Gateway

A backend service handling user-related API requests, such as authentication and data retrieval, ensuring secure and efficient user management.

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.

Internationalization (i18n)

An optional feature allowing the application to support multiple languages, enhancing accessibility for diverse users.

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.