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
ChattySw has been hired by RTVE to improve an online quiz game inspired by "Saber y Ganar." The previous version was developed by HappySw.
The new version, WIChat, lets users identify locations from images and answer related questions. A key feature is the ability to get hints through a conversational AI model.
1.1. Requirements Overview
-
Users must be able to register, log in, and manage their accounts.
-
The system must present images and corresponding quiz questions.
-
Users must be able to submit answers within a set time limit.
-
A conversational AI must provide hints when requested.
-
The system must track user performance and maintain historical data.
-
Questions, answers, and hints must be generated automatically from Wikidata.
-
APIs must be available for accessing user data and quiz content.
1.2. Quality Goals
Quality Goal | Description |
---|---|
Reliability |
Ensure that the generated questions and hints are accurate and relevant. |
Scalability |
Support a growing number of users and interactions. |
Usability |
Provide an intuitive and engaging user experience. |
Maintainability |
Allow easy updates and improvements to the system. |
Security |
Protect user data and ensure fair gameplay. |
Performance |
It will work the 95% of the time excluding maintenance periods |
1.3. Stakeholders
Name | Description | Expectations |
---|---|---|
Development Team |
The development team consists of the students that are members of the group. |
They should develop a robust application and learn new technologies. |
ChattySw |
The company responsible for developing the application. |
They should develop a satisfactory product efficiently and cost-effectively. |
RTVE |
The entity responsible for hiring the application development. |
They should obtain the best possible product. |
Registered Users |
Any person using the application. |
They expect to enjoy a great user experience and learn from the quiz questions. |
Admin Users |
The application would need some administrator to fix any strange behaviour in game. |
They expect to fix some minor problems. |
HappySw |
Competitor to ChattySw, developer of the previous version of the application. |
They should compete with ChattySw as the developer of the previous version of the application. |
Rest of competitors |
There is more than one competitor to that type of games. |
They compete with ChattySW and WiChat on engaging the target audience of the game. |
Hosting suppliers - Azure |
The application must be deployed for the public use |
They expect a new client of their services. |
DNS suppliers |
The application must be found in the web by a domain of RTVE |
They expect a new client of their services. |
Saber y Ganar |
The physical version of the game would dictate the rules of its online version |
It expects to have similar functions as this online game. |
2. Architecture Constraints
2.1. Motivation
Constraints, like building codes, budgets, or client needs, must always be considered, but some can be adjusted through discussion or smart solutions. Every decision that collide with the constraints decided will be discussed with the team.
2.2. Technical constraints
Constraint |
Explanation |
Javascript |
The programming language of the project is Javascript, in order to take advantage of some of the frameworks available. |
React |
The use of React.js framefork for the frontend. |
Node |
The use of Node.js framework for the backend. |
Express |
A framework used by Node.js in order to make a structure for application witout a huge complexity. |
MongoDB |
The database will be MongoDb, a NoSQL database system. |
Wikidata |
It will be used to generate questions. |
Github |
All the shares information will be stored at the repo of the project. |
LLM integration |
As the system gives hints to the players, a way of comunicating with a LLM (Long Language Model) sush as Gemini or Mistral is needed. |
Docker |
In order to deploy all the services and make them accesible online, Docker will be used to ease and automate the deployment process. |
APIs usage |
Some of the services will work as an Application Programming Interface. |
Time mangement |
In order to have a complete experience while using the app, timeouts and timers are needed. |
2.3. Organizational constraints
Constraint |
Explanation |
P2P Review |
Every branch for the development will have two roles, the developer and the reviewer, using one of the features of Github, Pull Requests. |
Issues |
As the project is held in Github, Github issues are the best way to track all the tasks that need to be done. |
Meeting reports |
Every time the development team have a meeting to discuss something related with the project. |
Self reports |
By the end of every sprint, each member has to open an issue to write down what they have done over the sprint, as well as the complications they have found while developing. |
Timelines |
As the project has a final deadline, evrything would be finished by May 5th and will not recieve any update after that day. |
Azure budget cap |
As deployment is a mandatory function of the final result, the team have to deal with the budget cap given by Azure as students. |
2.4. Conventions
Constraint |
Explanation |
Use of English |
The documentation will be all written in English as it is the "software-related" language all over the world. |
Arch42 |
The documentation will follow the Arch42 template as a way to split and order all the information related with the software product. |
3. Context and Scope
3.1. Business Context
Communication Partner | Inputs | Outputs |
---|---|---|
Client |
Username, password |
Game score, questions retrieved from Wikidata |
Database |
Username, password, score of each game |
Credential validation, score storage |
Wikidata |
Request for information about the game question |
Generated question with relevant information |
Empathy/Gemini |
Game question and correct answer |
Hints to help the user answer better |

3.2. Technical Context
Technology |
Description |
Database |
MongoDB |
Communication with Empathy/Gemini |
HTTP |
User Interface |
React |
Server |
Node.js |
Virtual Machine |
Azure |

Channels |
Type |
Input/Output |
HTTP/REST |
Output |
WICHAT → User API |
HTTP/REST |
Output |
WICHAT → Question API |
HTTP/REST |
Input |
WICHAT → Wikidata |
HTTP/REST |
Input |
WICHAT → llm |
HTTP |
Input |
wichat → Database |
HTTP |
Output |
WICHAT → Database |
4. Solution Strategy
4.1. Technology Decisions
To develop the application, we have decided to use the following technologies which were the ones provided in the base project:
-
JavaScript: will be the programming language used in the project. We chose it for its widespread popularity, broad browser support, and robust ecosystem(It has a wide variety of tools, libraries, frameworks, and an active community), making it ideal for both frontend and backend development with Node.js.
-
ReactJS: allows us to build user interfaces; its component-based architecture and excellent performance make it ideal for web applications like ours. Furthermore, its seamless integration with JavaScript was a key factor in our decision.
-
Docker: We will use Docker to deploy the web application, as this platform allows us to create containers that package the application and its dependencies, ensuring consistent performance and simplifying deployment across different environments. Additionally, Docker facilitates isolated testing, ensuring that the application runs the same way in each environment (development, testing, production) without external interference.
-
GitHub: is used as a version control and collaboration platform, allowing the team to work efficiently and . Additionally, GitHub Actions provides continuous integration and continuous deployment and organized, as tools from GitHub are used, such as pull requests (to review the code before uploading and avoid conflicts) and issues (to track what each team member is doing or has done).
-
WikiData: will be used as a source of structured data, providing access to large volumes of open data that can be easily integrated into the application.
-
EspressJS: is a minimal and flexible framework for Node.js that simplifies the creation of web applications and APIs. Its simplicity and large ecosystem of middleware(intermediaries between the server and the application,they can perform tasks such as authentication, handling HTTP requests, data validation, logging, among others.) make it ideal for developing the backend of our application.
-
MongoDB was selected as our database due to it’s scalability and flexibility in handling data. As a non-relational database, it allows for more dynamic and adaptable data storage and retrieval compared to traditional relational databases like MySQL. While MySQL provides structured query language and consistency, MongoDB offers greater flexibility, making it more suitable for our application’s needs, especially when dealing with large volumes of unstructured or semi-structured data, such as the data from WikiData used for questions and answers.
4.2. Top-Level Descomposition
We have chosen to adopt a microservices architecture because we believe it is the best approach for our project. In this design paradigm, the application is segmented into small, autonomous services that typically interact via APIs.Currently, we have the following microservices:
-
Authentication service: It is used for user authentication.
-
Question service: It is used to generate questions from the Wikidata API.
4.3. Approaches to Achieve Top Quality Goals
Quality Goal | Decision Made |
---|---|
Usability |
We use ReactJS to build an interactive and modern user interface. Additionally, we follow UX/UI design principles to enhance the user experience. |
Security |
The application should protect user data and prevent unauthorized access. |
Scalability |
We use Docker and microservices to enable independent deployment and scalability of each system component. MongoDB facilitates horizontal scalability. |
Testability |
We apply unit and integration testing. Additionally, we use GitHub Actions for automated testing on each push. |
Adaptability |
We want our application to reach more people, therefore, we need to make it adaptable to different devices such as mobile phones, laptops, etc., in order to provide the best possible user experience. |
Maintainability |
The code should be easy to understand, modify, and extend to facilitate future improvements and allow any new team member to comprehend it without issues. To achieve this, we will implement proper documentation that explains key architectural decisions, the project’s functionality, among other aspects. We will also use GitHub, as version control allows tracking the changes made by each team member. Additionally, we will apply modularization, breaking the code into small, reusable and isolated functions and modules. |
Performance |
To improve the application’s performance and avoid system overload, we will use the minimum number of API calls possible to reduce response time. |
4.4. Organizational Decision
-
Language: We have chosen English as the language for this project, which will make it accessible to everyone.
-
GitHub Projects: We will use it to track the team’s work in general and in a more visual way.
-
Meetings: We will hold them weekly during the lab class, except on special occasions when key decisions for the application need to be made.
-
Tasks: each task assigned to a member must be associated with an issue to track what each member has done or is currently doing
5. Building Block View
5.1. Whitebox Overall System
- Motivation
-
The system consists of a game (Saber y ganar) in which the user interacts with the application to answer questions.
- Contained Building Blocks
Name | Responsibility |
---|---|
Usuario |
Interacts with the application via the frontend. |
Frontend (React) |
Provides the user interface where users interact with the system. |
Backend (Node.js) |
Manages business logic, handles frontend requests, and communicates with the database. |
MongoDB |
NoSQL database used for storing user, race, and registration data. |
Docker |
Containerization platform ensuring portability and scalability of services. |
6. Runtime View
6.1. User Registration

6.2. User Login

6.3. Question Generation

6.4. Answering a Question

6.5. Ranking Query

7. Deployment View
7.1. Infrastructure Level 1

- Motivation
-
Having independent services deployed on the same machine give a lot of flexibility at deciding where the application will be deployed, making possible to have only a virtual machine to run the whole application.
- Quality and/or Performance Features
-
By our experience, we estimate that Azure VM with 2 GiB RAM and 1vCPU could work perfectly.
- Mapping of Building Blocks to Infrastructure
Element |
Description |
Client |
The client will always be a web browser such as Safari or Firefox, by a HTTP request. |
WebApp |
This is the frontend of the application. THe function of the game does not need to store information, everything is dynamic, so there is no need is having the game in an independent service. |
Gateway |
The gateway service contain all the information required to users: their account, the scores they had and so on. These modules connect to the same database, a mongoDB located at the same machine as the application, but not being part of it. |
Questions |
This service connects with de Wikidata API, and requests some types of questions known by our application. |
Wikidata |
Service where questions are collected. SparQL is required to use the API |
LLM |
The LLM decided to support hint requests are Mistral and Gemini. The idea is to give a prompt with the context of how to answer client questions with hints. |
Every interaction between services is done by HTTP requests, and they have defined their own ports on the same machine:
Element |
Port |
Webapp |
3000 |
Gateway Service |
8000 |
User Service |
8001 |
Auth Service |
8002 |
LLM Service |
8003 |
History Service |
8004 |
Questions Service |
8010 |
WebApp |
3000 |
8. Design Concepts and Decisions
8.1. Architectural Patterns and Principles
The system follows a microservices architecture, ensuring modularity and scalability:
Service Layering:
Independent Services: Each microservice is responsible for a specific domain, handling its own data and business logic. API Gateway: Manages communication between services and external clients, ensuring secure and efficient data flow. Frontend Integration: The user interface consumes APIs from multiple microservices, allowing for a flexible and decoupled design. This approach enhances scalability, maintainability, and component reusability, facilitating independent development and deployment of services.
8.2. Key Architectural Decisions
Starting from Scratch with Reference to Previous Projects: The decision was made to develop the system from scratch, leveraging the knowledge and experiences from last year’s projects. This allowed for the design of a more efficient and flexible architecture without the constraints of previous versions.
Use of Modern Technologies: Technologies such as React for the interface, Node.js for the backend, and MongoDB as the database have been chosen, ensuring an agile development process adaptable to the project’s needs.
As development progresses, more key decisions and their justifications will be documented.
9. Architecture Decisions
The architectural decisions are fully documented in our repository Wiki Section. To avoid redundancy, instead of writing the decisions here in the documentation, we will refer o them.
9.1. Architectural Decisions
9.1.1. Organizational Decisions
9.1.2. Technology Decisions
9.1.3. Top-Level Descomposition
10. Quality Requirements
- Motivation
-
"As quality requirements, we aim to meet our quality objectives: usability, maintainability, efficiency, testability, portability."
- Usability
-
The application must be easy to use and allow intuitive interaction. Priority: High
- Maintainability
-
The application must be easy to modify and extend without breaking functionality. Priority: High
- Efficiency
-
The application must perform optimally, minimizing resource and time usage. Priority: Medium
- Testability
-
The application must be easy to test to ensure quality and detect errors. Priority: High
- Portability
-
The application must run on different platforms for better adaptability. Priority: Medium
11. Specific Requirements
- Specific Requirements
-
-
❏ The system must store user registration data.
-
❏ The system must correctly validate answers to questions.
-
❏ The system must not allow modification of question results once answered.
-
❏ The system must inform the user of possible errors through a message.
-
❏ The system must notify the user when they have answered a question correctly or incorrectly and when their time has run out.
-
12. Risks and Technical Debts
Risk | Explanation | Measure |
---|---|---|
Lack of experience with the technologies used |
We lack extensive experience with technologies like React, Node.js, MongoDB, which might complicate their usage. |
Research these technologies and learn how to use them correctly. |
Lack of time |
There are deadlines for each deliverable, and we may run out of time. |
Stay consistent and do as much as possible daily. |
Teamwork challenges |
Working in a team can be difficult, especially since we’ve never done a large project like this. |
Maintain good communication and collaboration. |
Unproductive meetings |
Spending too much time in meetings without making progress can cause issues. |
Prepare briefly for meetings to focus on specific topics. |
Member abandonment |
If a team member quits, their tasks will need to be reassigned, increasing the workload. |
Assign tasks to multiple people and offer support to avoid abandonment. |
External service failure |
An external service like Wikidata or Azure may fail temporarily. |
Stay updated on service changes and work to restore functionality quickly. |
Technical Debt | Explanation | Solution |
---|---|---|
Insufficient documentation |
Lack of proper documentation can make future system understanding and maintenance challenging. |
Ensure thorough and clear documentation is created. |
Suboptimal database design |
A poorly designed database can create scalability issues as the system grows. |
Plan and design the database carefully before implementation or modification. |
Dependence on AI-generated code |
AI-generated code may have inaccuracies, potentially leading to difficulties when revisiting or updating it. |
Review, adjust, and validate AI-generated code before integration. |
LLM performance issues |
The language model may cause slow response times and irrelevant answers, impacting user experience. |
Optimize prompts and continuously monitor the model’s performance for improvements. |
13. Glossary
Term | Definition |
---|---|
React.js |
It is a free and open-source front-end JavaScript library that aims to make building user interfaces based on components more "seamless". |
Node.js |
Node.js is a cross-platform, open-source JavaScript runtime environment that can run on Windows, Linux, Unix, macOS, and more. Node.js runs on the V8 JavaScript engine, and executes JavaScript code outside a web browser. |
MongoDB |
MongoDB is a source-available, cross-platform, document-oriented database program. Classified as a NoSQL database product, MongoDB uses JSON-like documents with optional schemas. |
LLM |
A large language model (LLM) is a type of machine learning model designed for natural language processing tasks such as language generation. LLMs are language models with many parameters, and are trained with self-supervised learning on a vast amount of text. |
Microservices |
A microservice architecture is an architectural pattern that organizes an application into a collection of loosely coupled, fine-grained services that communicate through lightweight protocols. This pattern is characterized by the ability to develop and deploy services independently, improving modularity, scalability, and adaptability. |
Docker |
Containers are isolated from one another and bundle their own software, libraries and configuration files; they can communicate with each other through well-defined channels. Because all of the containers share the services of a single operating system kernel, they use fewer resources than virtual machines. |
SSH |
The Secure Shell Protocol (SSH Protocol) is a cryptographic network protocol for operating network services securely over an unsecured network. Its most notable applications are remote login and command-line execution. |
14. About the game
Term | Definition |
---|---|
Hint Chat - WiChat AI |
The hint chat is referred to the chat where the players can comunicate with the LLM in order to get information about the correct answer |
WiChat |
WiChat is the name of the whole project and the application. |
Ranking |
The ranking page is referred to an online leaderboard of who got the most points overall. |
Category |
Although is not shown yet, categories are referred to the type of questions the game has. This can be expanded or filtered as needed. |
Time |
Each question has its own time of answering, that could be use in several game modes. |