About arc42

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

Template Version {revnumber}. {revremark}, {revdate}

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

Note

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

1. Introduction and Goals

This project aims to develop an interactive web application, where users are given an image of a place and a series of options to try and guess where this place might be. The key innovation of the project relies on the integration of a Large Language Model (LLM), allowing users to interact with an AI assistant to request hints about the location. This mechanic enhances the gameplay by offering contextual clues, improving accessibility, and creating a more engaging user experience.

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

  • underlying business goals,

  • essential features,

  • essential functional requirements,

  • quality goals for the architecture and

  • relevant stakeholders and their expectations

1.1. Requirements Overview

The application must meet the following functional and non-functional requirements.

Functional Requirements:

  • Users must be able to access the application through a web interface.

  • Users must be able to create an account and log in.

  • System must be able of displaying an image and options.

  • Users must be able to communicate with an LLM for hints about their location.

  • System must set a time limit to answer the given question.

  • The application must allow users to submit their guess.

  • Users must be able to review their past games.

  • The system must provide APIs for managing users and game data.

Contents

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

Motivation

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

Form

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

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

Further Information

See Introduction and Goals in the arc42 documentation.

1.2. Quality Goals

Goal Description

Usability

The application must be intuitive and allow seamless navigation and interaction.

Performance

The system should respond promptly to user actions, ensuring smooth gameplay.

Security

User authentication and data storage must be handled securely.

Scalability

The architecture must support a growing number of users without performance degradation.
Contents

The top three (max five) quality goals for the architecture whose fulfillment is of highest importance to the major stakeholders. We really mean quality goals for the architecture. Don’t confuse them with project goals. They are not necessarily identical.

Consider this overview of potential topics (based upon the ISO 25010 standard):

Categories of Quality Requirements
Motivation

You should know the quality goals of your most important stakeholders, since they will influence fundamental architectural decisions. Make sure to be very concrete about these qualities, avoid buzzwords. If you as an architect do not know how the quality of your work will be judged…​

Form

A table with quality goals and concrete scenarios, ordered by priorities

1.3. Stakeholders

Contents

Explicit overview of stakeholders of the system, i.e. all person, roles or organizations that

  • should know the architecture

  • have to be convinced of the architecture

  • have to work with the architecture or with code

  • need the documentation of the architecture for their work

  • have to come up with decisions about the system or its development

Motivation

You should know all parties involved in development of the system or affected by the system. Otherwise, you may get nasty surprises later in the development process. These stakeholders determine the extent and the level of detail of your work and its results.

Form

Table with role names, person names, and their expectations with respect to the architecture and its documentation.

Role/Name Contact Expectations

(Team Member) Ignacio

https://github.com/nack-fs

To create a web application that provides value to stakeholders and learn in the development process.

(Team Member) José

https://github.com/josemzuvi

To create a web application that provides value to stakeholders and learn in the development process.

(Team Member) Leonardo

https://github.com/UnioviLCM27

To create a web application that provides value to stakeholders and learn in the development process.

(Team Member) Miguel

https://github.com/MigFeH

To create a web application that provides value to stakeholders and learn in the development process.

(Teacher) Diego Martín

https://github.com/DiegoMfer

Demonstrated understanding of web development principles through a functional, well-coded application that meets project requirements and learning objectives.

(Teacher) Emilio Labra

https://github.com/labra

Demonstrated understanding of web development principles through a functional, well-coded application that meets project requirements and learning objectives.

Future Course Students

…​

To have the project as a reference or start point to their own project.

2. Architecture Constraints

The application must be developed according to some constraints that were defined by the client. These constraints are meant to be the cornerstones of our project as they are mandatory and provide a baseline to work on. The following tables will define the constraints.

Technical constraints

Constraint

Description

Webbapp accesibility

The application must be accesible throgh a browser

Wikidata

The validity of questions and the questions themselves must be obtained through their Api

Github

It is imperative that we use Github for the recording of all of our work

Registry

It is obligatory that the program saves and stores data on the different users through a profile

Use of LLM model

We are to build a chatbot for the practice, wich means utilizing an LLM

Organizational constraints

Constraint

Description

Meetings

The team is due to an obligatory meeting per week at the time of Software Architecture class

Deliveries

There are three separate times where the project will be presented and those times are set.

Github

The use of Issues and Pull Requests for the proyects organization is highly sought to the point of necessity

Conventional constraints

Constraint

Description

Documentation in Arc42

The documentation must follow the Arc42 template

Language

It was agreed beforehand that english would be the language chosen for the proyect

Github

As the platform we work on we are obligated to learn Githubs conventions

3. Context and Scope

Contents

Context and scope - as the name suggests - delimits your system (i.e. your scope) from all its communication partners (neighboring systems and users, i.e. the context of your system). It thereby specifies the external interfaces.

If necessary, differentiate the business context (domain specific inputs and outputs) from the technical context (channels, protocols, hardware).

Motivation

The domain interfaces and technical interfaces to communication partners are among your system’s most critical aspects. Make sure that you completely understand them.

Form

Various options:

  • Context diagrams

  • Lists of communication partners and their interfaces.

Further Information

See Context and Scope in the arc42 documentation.

3.1. Business Context

Contents

Specification of all communication partners (users, IT-systems, …​) with explanations of domain specific inputs and outputs or interfaces. Optionally you can add domain specific formats or communication protocols.

Motivation

All stakeholders should understand which data are exchanged with the environment of the system.

Form

All kinds of diagrams that show the system as a black box and specify the domain interfaces to communication partners.

Alternatively (or additionally) you can use a table. The title of the table is the name of your system, the three columns contain the name of the communication partner, the inputs, and the outputs.

The following table describes the business context, outlining the key actors interacting with the system and their relationships.

Actor Type Description Interaction with the System

Players

External

Users who access the application to play the game.

Interact with the web interface, receive random locations, request hints from the LLM, and submit guesses.

LLM Provider

External

API service providing AI-generated hints for players.

Receives user queries and returns contextual hints about the player’s location.

Web Application

Internal

The frontend React-based web application.

Displays the game interface, processes user interactions, and communicates with backend services.

Gateway Service

Internal

API gateway handling requests between the frontend and backend services.

Routes user requests, manages authentication, and forwards LLM-related queries.

Authentication Service

Internal

Manages user authentication and access control.

Handles user login, registration, and session management.

User Service

Internal

Manages user-related data, including game history and scores.

Stores and retrieves user data, including past game records.

Database

Internal

MongoDB instance storing user and game data.

Stores user accounts, game sessions, and interaction logs.

Deployment Platform

External

Cloud-based hosting service (e.g., AWS, Azure, or DigitalOcean).

Hosts the web application, backend services, and database.

3.2. Technical Context

Contents

Technical interfaces (channels and transmission media) linking your system to its environment. In addition a mapping of domain specific input/output to the channels, i.e. an explanation which I/O uses which channel.

Motivation

Many stakeholders make architectural decision based on the technical interfaces between the system and its context. Especially infrastructure or hardware designers decide these technical interfaces.

Form

E.g. UML deployment diagram describing channels to neighboring systems, together with a mapping table showing the relationships between channels and input/output.

Diagram or Table

3.2 Technical Context
Component Description

Agent User (External User)

Interacts with the Web App, serving as the system’s end user.

Web App (View Layer - Frontend)

Sends requests to and receives responses from the Backend. Acts as a bridge between the external user and backend services.

Backend (Controller Layer - Node.js API)

Serves as the central hub that manages communication between components. Handles authentication, user management, and external interactions. Routes requests to the appropriate services in the Service Layer.

Service Layer (Business Logic)

Contains core business logic. Processes requests from the Controller Layer and interfaces with the Model Layer to access data.

Model Layer (Database & Data Access Layer)

Uses Mongoose ORM to interact with MongoDB. Defines schemas and performs all database operations.

3.2.1. Technical Interfaces

  • Web App & Backend: HTTP Requests/Responses.

  • Backend & Service Layer: Internal function calls.

  • Service Layer & Model Layer: Database queries.

  • Model Layer & MongoDB: Data storage and retrieval.

Mapping Input/Output to Channels
Component Input Output

Web App

User Requests

UI Responses

Backend (Controller Layer)

API Calls

Processed Data

Service Layer

Business Logic Requests

Business Logic Responses

Model Layer

Database Queries

Stored/Retrieved Data

MongoDB

Queries

Stored Data

4. Solution Strategy

What follows is a short summary and explanation of the fundamental decisions and solution strategies, that shape our system’s architecture

4.1. Technology

  • Visual Studio Code as a IDE due to its versatility in developing applications with different programming languages and its compatibility with Git.

  • Docker to deploy the project, as it allows for the definition of consistent execution environments, ensuring that the application runs the same way in development, testing, and production. Additionally, it supports continuous deployment.

  • GitHub Pages for deploying the documentation.

  • MongoDB as a database due to its flexibility when implementing new properties in schemas without having to redo the "tables" every time a new property is added.

  • Azure portal to deploy the application on the internet due to its ease of configuration, following the instructions provided to developers for deployment, and its potential to install Docker for deploying the Docker containers created in continuous deployment.

4.2. High-level decomposition

Quality goal Scenario Solution approach

Usability

A new user quickly understands how to play and how to ask for basic hints.

Intuitive interface, clear design of the interface for interacting with the predefined hint system.

Performance

The game loads images and predefined hints in 1-3 seconds.

Image optimization, predefined hint caching.

Hint Accuracy

Hints provided by the LLM are coherent with user questions and relevant to players progress.

Creation of well-designed System Instructions for the LLM, paired with user testing to ensure the overall validity of the results.

Testability

Developers can run automated tests to verify game functionality.

Modular code design, implementation of unit and integration tests, use of testing frameworks.

4.3. Approaches to achieve quality objectives

Quality goal Scenario Solution approach

Usability

Players on different devices enjoy a consistent experience.

Responsive CSS design, cross-browser and device testing, use of responsive UI frameworks.

Performance

The game maintains a smooth experience with multiple concurrent players.

Scalable backend with Docker, load balancing, database query optimization.

Hint Accuracy

Hints provided for the LLM are clear, don’t confuse the user or give them the straight answer.

Careful wording of instructions, testing to ensure this scenarios are minimal and fallback mechanisms to stop malfunctions interferencing with the game.

Testability

Code changes do not introduce regressions.

Continuous integration with automated testing, adequate code coverage, test documentation.

4.4. Relevant organizational decisions

We have been meeting once a week, although this may change in the future depending on the team’s needs to address different topics during development.

In most meetings, if not all, all group members participate, and we discuss opinions on different designs and implementations of the application.

We also have a WhatsApp group as a fast messaging channel.

5. Building Block View

Content

The building block view shows the static decomposition of the system into building blocks (modules, components, subsystems, classes, interfaces, packages, libraries, frameworks, layers, partitions, tiers, functions, macros, operations, data structures, …​) as well as their dependencies (relationships, associations, …​)

This view is mandatory for every architecture documentation. In analogy to a house this is the floor plan.

Motivation

Maintain an overview of your source code by making its structure understandable through abstraction.

This allows you to communicate with your stakeholder on an abstract level without disclosing implementation details.

Form

The building block view is a hierarchical collection of black boxes and white boxes (see figure below) and their descriptions.

Hierarchy of building blocks

Level 1 is the white box description of the overall system together with black box descriptions of all contained building blocks.

Level 2 zooms into some building blocks of level 1. Thus it contains the white box description of selected building blocks of level 1, together with black box descriptions of their internal building blocks.

Level 3 zooms into selected building blocks of level 2, and so on.

Further Information

See Building Block View in the arc42 documentation.

5.1. Whitebox Overall System

Here you describe the decomposition of the overall system using the following white box template. It contains

  • an overview diagram

  • a motivation for the decomposition

  • black box descriptions of the contained building blocks. For these we offer you alternatives:

    • use one table for a short and pragmatic overview of all contained building blocks and their interfaces

    • use a list of black box descriptions of the building blocks according to the black box template (see below). Depending on your choice of tool this list could be sub-chapters (in text files), sub-pages (in a Wiki) or nested elements (in a modeling tool).

  • (optional:) important interfaces, that are not explained in the black box templates of a building block, but are very important for understanding the white box. Since there are so many ways to specify interfaces why do not provide a specific template for them. In the worst case you have to specify and describe syntax, semantics, protocols, error handling, restrictions, versions, qualities, necessary compatibilities and many things more. In the best case you will get away with examples or simple signatures.

5.1 Whitebox Overall System
Motivation

This sketch represents the interactions within the Wichat application. It outlines the main components of the system, focusing on the user’s experience with the application and its bound technologies like the LLM (Large Language Model).

Contained Building Blocks
Name Description Responsibilities

User

The authenticated individual interacting with the application. They play the game through the system, and their data is stored in the database.

The user interacts with the Wichat application, playing the game and requesting hints.

Wichat Application

The main system that drives the game logic. It handles the flow of the game, including interactions between the user and the system, and manages the rules and responses generated by the LLM.

The Wichat application manages user interactions, game logic, and communication with the LLM.

LLM (Large Language Model)

This external component generates hints based on the user’s requests through a hint chat.

The LLM processes user requests and generates hints, enhancing the gaming experience.

Wikidata API

The external API that provides valid questions and answers for the game.

The Wikidata API supplies the Wichat application with valid questions and answers, ensuring the game’s content is accurate and relevant.
Important Interfaces
Name Description

User Interface

The web client through which the user plays the game, allowing them to send requests for new rounds.

LLM Communication Interface

This interface handles requests from the Wichat application to the LLM, sending prompts and receiving generated content like answers in return.

Wikidata API Interface

This interface allows the Wichat application to communicate with the Wikidata API, fetching valid questions and answers for the game.

6. Runtime View

Contents

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

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

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

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

  • error and exception scenarios

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

Motivation

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

Form

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

  • numbered list of steps (in natural language)

  • activity diagrams or flow charts

  • sequence diagrams

  • BPMN or EPCs (event process chains)

  • state machines

  • …​

Further Information

See Runtime View in the arc42 documentation.

6.1. Runtime Scenario 1 : Login

LoginDiagram

6.2. Runtime Scenario 2 SingUp

SignInDiagram

6.3. Runtime Scenario 3 Game cycle

GameCycleDiagram

7. Deployment View

Content

The deployment view describes:

  1. technical infrastructure used to execute your system, with infrastructure elements like geographical locations, environments, computers, processors, channels and net topologies as well as other infrastructure elements and

  2. mapping of (software) building blocks to that infrastructure elements.

Often systems are executed in different environments, e.g. development environment, test environment, production environment. In such cases you should document all relevant environments.

Especially document a deployment view if your software is executed as distributed system with more than one computer, processor, server or container or when you design and construct your own hardware processors and chips.

From a software perspective it is sufficient to capture only those elements of an infrastructure that are needed to show a deployment of your building blocks. Hardware architects can go beyond that and describe an infrastructure to any level of detail they need to capture.

Motivation

Software does not run without hardware. This underlying infrastructure can and will influence a system and/or some cross-cutting concepts. Therefore, there is a need to know the infrastructure.

Form

Maybe a highest level deployment diagram is already contained in section 3.2. as technical context with your own infrastructure as ONE black box. In this section one can zoom into this black box using additional deployment diagrams:

  • UML offers deployment diagrams to express that view. Use it, probably with nested diagrams, when your infrastructure is more complex.

  • When your (hardware) stakeholders prefer other kinds of diagrams rather than a deployment diagram, let them use any kind that is able to show nodes and channels of the infrastructure.

Further Information

See Deployment View in the arc42 documentation.

7.1. Infrastructure

Element

Description

User service

Utilized by logged-in users, retrieves their data from the MongoDB database and displays it within the web application.

Auth service

Ensure user authentication during their initial registration in the game. Collect and securely store all their information in the MongoDB database to facilitate seamless login experiences in subsequent sessions.

Gateway service

Acts as a central entry point for client requests, routing them to appropriate backend microservices.

WebApp

Interface for display to the user where the application is housed. Utilizes React as it main form of code and Javascript to interact with the Wikidata external service.

LLMService

Manages the Language Module and the AI made for the hint system of the application

MongoDB

The database management system, serves as the backend storage for the application’s functionality. It stores user data, generated questions and other game-related information.
Diagram

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

Concept Description

Microservices Architecture

The application follows a microservices architecture pattern, where the system is divided into independently deployable services that encapsulate specific business capabilities. This enables modular development, deployment, and scalability.

Communication Between Components

Each component, such as the web app, Gateway Service, and backend microservices, communicates using technologies like HTTP. This ensures smooth, decoupled, and scalable interactions.

Presentation Layer

The web app serves as the entry point for external users, providing the user interface and routing requests through the Gateway Service to appropriate backend microservices.

8.2. Data Persistence and Management

Concept Description

Database Interaction

Microservices interact with their respective data stores. The Gateway Service interact with a shared database for the WebApp ownned microservices using an internal MongoDB database.

8.3. Testeability

Concept Description

Unit Tests

Ensure that each individual unit or component functions as expected in isolation.

Integration Tests

Validate the interaction and data flow between multiple services or components.

Functional Tests

Confirm that the application’s behavior aligns with specified functional requirements.

Security Tests

Detect vulnerabilities and verify the protection of sensitive data and system integrity.

8.4. Usability

Concept Description

Usability

Usability focuses on creating an intuitive and efficient user experience. We prioritize clear navigation, accessibility, and a minimal learning curve to maximize user satisfaction.

8.5. Maintainability & Scalability

Concept Description

Maintainability

Emphasizes ease of modifying, extending, or fixing the system over time. Microservices improve maintainability by isolating changes to specific services.

Scalability

The architecture supports horizontal scalability, allowing each service to scale independently based on demand, ensuring robust performance under load.

9. Architecture Decisions

During the application development process, a series of decisions may change due to issues encountered during development, research on the technologies to be used, exploration of different work/organization strategies, etc.

These decisions are discussed in personal meetings and recorded in the meeting minutes, with some of the most important decisions being the following:

Decision Description

Main Language

The group decided for the main programming language for the application’s development to be JavaScript.

Front-End

The main way for users to interact with the system is the front-end, which will be developed in React.

Back-End

The inner workings of the application which will not be for the clients to use and see developed in Node.js.

LLM

The Language modules used for the hint generation in the application rely on google gemini as is the chosen LLM for the proyect.

Deployment

The application will be deployed on Azure, as it is the platform that best suits the needs of the project and is of easier access for the group members.

10. Quality Requirements

Content

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

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

Motivation

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

Further Information

See Quality Requirements in the arc42 documentation.

10.1. Quality Tree

Content

The quality tree (as defined in ATAM – Architecture Tradeoff Analysis Method) with quality/evaluation scenarios as leafs.

Motivation

The tree structure with priorities provides an overview for a sometimes large number of quality requirements.

Form

The quality tree is a high-level overview of the quality goals and requirements:

  • tree-like refinement of the term "quality". Use "quality" or "usefulness" as a root

  • a mind map with quality categories as main branches

In any case the tree should include links to the scenarios of the following section.

10.1 Quality Tree

10.2. Quality Scenarios

Quality Attribute Scenario Motivation Expected Response

Performance

A user requests a hint from the LLM and expects a fast response.

Avoid delays that could affect the overall experience.

The LLM responds fast enough so the user isn’t kept waiting for it.

Usability

A new user accesses the application and must start a game within reasonable time.

Ensure a low learning curve and an intuitive experience.

The user quickly finds the main options without external documentation.

Maintainability

Some collaborator is trying to edit, fix or add a new functionality to the app.

Ensure the changes can be done seamlessly without having to refactor or edit other areas of the code.

The application continues functioning correctly after the changes thanks to the division of the functionality in different microservices.

Compatibility

The app is opened in different devices with varying form factors.

Ensure the game remains functional and all elements are correctly displayed.

The app adapts to the form factor of the user device without impacting the experience.

Reliability

The app has been available for a long time.

Ensure the app continues to work even after it’s dependencies have been updated allowing it to work correctly over time.

The app keeps working correctly without any apparent changes to it.
Contents

Concretization of (sometimes vague or implicit) quality requirements using (quality) scenarios.

These scenarios describe what should happen when a stimulus arrives at the system.

For architects, two kinds of scenarios are important:

  • Usage scenarios (also called application scenarios or use case scenarios) describe the system’s runtime reaction to a certain stimulus. This also includes scenarios that describe the system’s efficiency or performance. Example: The system reacts to a user’s request within one second.

  • Change scenarios describe a modification of the system or of its immediate environment. Example: Additional functionality is implemented or requirements for a quality attribute change.

Motivation

Scenarios make quality requirements concrete and allow to more easily measure or decide whether they are fulfilled.

Especially when you want to assess your architecture using methods like ATAM you need to describe your quality goals (from section 1.2) more precisely down to a level of scenarios that can be discussed and evaluated.

Form

Tabular or free form text.

11. Risks and Technical Debts

Risk

Explanation

Mitigation proposed

Little knowledge of the technologies to be used

For all group members, this is the first time developing software that requires implementing an LLM

Search for knowledge on developing applications integrated with LLMs, along with the tools used for this. Consult the code and documentation of last year’s projects to observe the decisions that were made and the technologies they used for the rest of the development

Lack of time

We may face time constraints in fulfilling all the requirements for each deliverable and meeting every deadline

Try to maintain a steady and sustainable development pace. Prioritize building functional components initially, then iterate and enhance from there

Coordination and responsibility problems

It is probably the first time involvement in developing a project from scratch, including decisions on architecture, design, and implementation, introduces various challenges. Misunderstandings regarding tasks and version control management errors can result in individuals inadvertently disrupting the work of others. Additionally, the necessity to make numerous decisions and reach agreements increases the likelihood of errors, potentially consuming significant time and effort

To ensure effective collaboration and organization, follow the teachers' instructions regarding GitHub, including the use of features such as issues, pull requests, and maintain a disciplined approach to work from all team members, using a Kanban methodology integrated as a feature in GitHub

Starting off from scratch?

We’ll have to take the decision of starting our project from scratch or take another project from last year as "inspiration" or as a starting point

Why not both? Starting off from scratch can be really difficult, but if we have another project that serves as a guide or reference we’ll be more productive and focus on new functionalities (such as the LLM integration) rather than in the basis development.

Version Control Software Use

GitHub is one of the most (if not the most) popular version control tools in the market, however, some group member may be not acquainted with it, or even if we are, we still have to get to an agreement on how to work properly and consistently (unique commit format for all commits, wiki page rotation, conflict solving, etc.)

Starting slow with GitHub (making the project documentation) will help us to get used to it. Later, we’ll discuss and register decisions on the workflow when developing.

Spend more time developing than thinking

This one is pretty common, sometimes we just focus on producing huge amounts of code, often forgetting the importance of the previous phases, the ones that draw the line between a software developer and a software engineer/software architect.

Question the decisions "made on autopilot", remembering the goals we need to achieve when the application is done, and working smarter, not harder, on getting there.

12. Testing

Software quality is a critical aspect of the development lifecycle. To ensure this quality, a combination of automated testing strategies and static code analysis has been implemented. This section outlines the unit tests, code coverage, security hotspots, and provides an introduction to end-to-end (E2E) testing.

12.1. Unit Tests, Code Coverage & Security Hotspots

To verify the correct behavior of individual modules, unit tests have been developed using tools appropriate for the project’s technology stack. These tests cover both business logic and key utility functions.

Code coverage and static analysis were performed using SonarQube, with the following results:

  • Code coverage: 89.9% on 952 lines of code.

  • Security hotspots: 18 identified, pending review and classification.

  • Code duplication: 0.3%, indicating a very low level of redundancy.

  • Code quality: The project passed the Quality Gate with an "A" rating in security, reliability, and maintainability.

SonarQube Results

This level of coverage and quality provides high confidence in the stability of the system’s components.

12.2. E2E Tests

In addition to unit testing, end-to-end (E2E) tests are being developed to validate complete user flows—from the user interface through to the backend. These tests aim to ensure that all components of the system integrate properly and behave as expected under various usage conditions.

Implemented e2e tests

12.3. Stability Testing

Stability is a critical aspect of the development process, ensuring that the system can handle expected loads and perform reliably over time. This includes testing for memory leaks, performance under stress, and overall system resilience.

Here we can see the results of the stability tests performed on the system over time:

Results of testing for the app stablity

13. Glossary

Term Definition

WiChat

The name of our project and application.

Question Generator (QG)

A module of the application responsible for querying Wikidata, creating the questions and storing them.

Wikidata

A free knowledge base that can be read and edited by both humans and machines. It is used to obtain the questions and their validity.

Microservice

A software development technique that structures an application as a collection of small autonomous services, modeled around a business domain.

Grafana

An open-source platform for monitoring and observability, used to visualize and analyze data from various sources.

Prometheus

An open-source systems monitoring and alerting toolkit, used to collect and store metrics data.

MongoDB

A NoSQL database that uses a document-oriented data model, used to store user profiles and game-related data.

Azure

A cloud computing service created by Microsoft for building, testing, deploying, and managing applications and services through Microsoft-managed data centers.

Docker

A platform that enables developers to automate the deployment of applications inside lightweight, portable containers.

React

A JavaScript library for building user interfaces, used to develop the front-end of the application.

Node.js

A JavaScript runtime built on Chrome’s V8 JavaScript engine, used to develop the back-end of the application.

Large Language Models (LLM)

The name via which we refer to the AI models that are trained on large pools of data for text generation and we useto generate hints for the game.

E2E Tests

End-to-end tests that validate complete user flows, ensuring that all components of the system integrate properly and behave as expected.

SonarQube

An open-source platform for continuous inspection of code quality, used to perform static analysis and code coverage.

Quality Gate

A set of conditions that a project must meet to be considered of acceptable quality, as defined by SonarQube.