About arc42

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

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

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

Note

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

1. Introduction and Goals

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

  • underlying business goals,

  • essential features,

  • essential functional requirements,

  • quality goals for the architecture and

  • relevant stakeholders and their expectations

RTVE has hired the company ChattySw composed of students from the Oviedo School of Software Engineering (EII), to update a game-show like web application that was developed last year by the HappySw company. This application will be called WIChat, where users will be able to register and login to play. The basic game will consist of a game that shows a picture and the users have to guess what it is about. The users will have to answer a list of questions about those pictures from different domains obtaining points for each correct guess. This years update in the game-show will be the posibility of obtaining hints about the picture in a conversational way from an external LLM.

1.1. Requirements Overview

Contents

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

Motivation

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

Form

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

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

Further Information

See Introduction and Goals in the arc42 documentation.

1.1.1. Functionalities definition

  • The system must provide non-registered users with the option to sign up.

  • The system must provide registered but not identified users with the option to log in.

  • The system must only be used by registered users.

  • The system will have at least a Web frontend which will show the pictures and answers as well as the hint system where the users can interact with the system to obtain hints about the pictures.

  • The Web application should be deployed and accessible through the web.

  • Users will be able to register to the system and obtain the historical data from their participation: number of games, questions passed and failed and times.

  • Information about the questions will be automatically generated from Wikidata.

  • It should be possible to interact with the application in each question to obtain hints about the questions. For that, an LLM will be used which will be accessible through an API.

  • It should be possible to use an approach to generate hints from Wikidata that mitigates the generation of incorrect answers or hallucinations.

  • The questions should be answered before some specific time.

  • Each question should have a correct answer and several incorrect ones or distractors. The right answer and the distractors should be automatically generated.

  • The system will give access to the information about the users through an API which should be documented.

  • The system will give access to information about the generated questions through an API.

1.1.2. Functional requirements

Users Register

  • UR 1. The system must allow an unregistered user to register in the application.

  • UR 2. The system must request data to register:

    • UR 2.1.1. Username.

    • UR 2.1.2. Email address.

    • UR 2.1.3. Password.

  • UR 3. The system shouldn’t allow the user to be registered when any value entered by the new user is invalid.

  • UR 4. The system must check for existing users with the data obtained.

    • UR 4.1. The system shouldn’t allow the user to create a new account if the email matches with an existing user.

    • UR 4.2. The system should allow the user to create a new account if the email does not match with an existing user.

  • UR 5. The system must recognice the user as registered.

Users log

  • UL 1. The system must allow an unidentified user to log in.

    • UL 1.1. The system must request the email address as the user identifier.

      • UL 1.1.1. The system must check that its format is valid.

      • UL 1.1.2. The system must check the box is filled.

    • UL 1.2. The system must request the user’s password.

      • UL 1.2.1. The system must check the box is filled.

    • UL 1.3. The system must automatically validate the entered data to verify when it corresponds to a registered user account.

      • UL 1.3.1. When the user is not stored in the system, an error message must be displayed.

      • UL 1.3.2. When the user exists in the system, but the password does not match, a message must be displayed to the user notifying them of the error.

      • UL 1.3.3. When the user is stored in the system and the password matches, the user must be logged in.

  • UL 2. The system must allow users who are logged in to log out.

Users Data

  • UD 1. The system must allow all identified users to access their historical data.

    • UD 1.1. Identified users must be able to access the number of:

      • UD 1.1.1. Games they have played.

      • UD 1.1.2. Questions they have answered correctly.

      • UD 1.1.3. Questions they have answered incorrectly.

    • UD 1.2. Identified users must be able to access the ranking of the game.

Playing WIChat

  • PWIC 1. The system must only allow identified users to play WIChat.

  • PWIC 2. The system must retrieve indormation for the questions from Wikidata.

  • PWIC 3. The system must provide the user with a LLM API to help answering the questions.

    • PWIC 3.1 The LLM must provide the user with hints about the questions.

  • PWIC 4. The game consists of nine rounds by default.

    • PWIC 4.1. the system must automatically provide a question to the identified user.

    • PWIC 4.3. The system must automatically provide one correct answer.

    • PWIC 4.2. The system must automatically provide three distractors.

  • PWIC 5. The system must allow the user to answer the questions if there is time remaining.

    • PWIC 5.1. The system must check when the identified user has provided an answer in the time given:

      • PWIC 5.1.1. If the answer is correct.

      • PWIC 5.1.2. If the answer is incorrect.

    • PWIC 5.2. The system must move to the next round when the specified time has ended.

  • PWIC 6. The system must terminate the game and give a score when the last round is over.

1.2. Quality Goals

Contents

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

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

Categories of Quality Requirements
Motivation

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

Form

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

Goal Description

Functional suitability

The system must fulfill its intended purpose effectively and efficiently, allowing users to register, log in, play the quiz, access their user statistics and get aid from the LLM during the questions.

Reliability

The system should be reliable in generating questions from Wikidata, ensuring that questions are accurate and diverse. The LLM implemented in the system must be reliable and well trained to be able to help the users in answering the questions. The system shall handle user registrations, logins, and game data storage without errors.

Availability

The system shall be available 97% of the time a user tries to access it.

Maitainability

The system shall be designed and implemented in a way that facilitates easy maintenance and updates.

Performance efficiency

The system shall deliver optimal performance, ensuring responsive interactions for users. The automatic generation of questions from Wikidata and the LLM responses with a real-time gameplay shall be efficient. The system shall handle 20 concurrent users.

Usability

The system shall provide a user-friendly interface, making it easy for users to register, log in, and play the game.

Portability

The system shall be portable to various web browsers and devices, ensuring a seamless experience for users regardless of their platform. It has to be optimized for different screen sizes and functionalities.

Security

The system shall prioritize user data security. It must implement robust authentication mechanisms for user registration and login. The API access points for user information and generated questions must be secured with proper authorization.

Testability

Facilitate comprehensive testing to ensure software correctness and identify potential issues early.

Learnability

The system learning time for a user should be low, preferable under 3 hours.

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

RTVE

rtve.dircom@rtve.es

A web application that mimics the popular Spanish TV show "Saber y Ganar".

ChattySw

TBD

An outstanding and highly detailed application that meets with the requirements and constraints required by the product owner (RTVE).

Professors

Perform the role of the product owner (RTVE) as well as helping with doubts related with the application development. They expect an application developed following a highly structured process, documenting as much as necessary and following the requirements imposed by the product owner.

Application Users

A quiz game that, with some help provided by the clues that an AI model provides, is easy to use and understand. Meeting modern quality standards and ensuring a good usability overall.

Development Team

A good and well documented code, as well as following proper design and architectural patterns that ensure an easy code maintainability and extensibility. Also, fulfilling the application requirements and achieving a good usability.

2. Architecture Constraints

Contents

Any requirement that constraints software architects in their freedom of design and implementation decisions or decision about the development process. These constraints sometimes go beyond individual systems and are valid for whole organizations and companies.

Motivation

Architects should know exactly where they are free in their design decisions and where they must adhere to constraints. Constraints must always be dealt with; they may be negotiable, though.

Form

Simple tables of constraints with explanations. If needed you can subdivide them into technical constraints, organizational and political constraints and conventions (e.g. programming or versioning guidelines, documentation or naming conventions)

2.1. Technical constraints

Constraint Description

Web App

The application should be a web application

Wikidata

The system must integrate with Wikidata as it’s going to be the main data souce for the questions.

LLM Integration

The system must handle the interaction of a user with a LLM chat

Data Storage

The system will use a database to store data about the users. The nature of this database is not decided yet

Deployment

The system must be accesible via web and it must be deployed using GitHub actions

2.2. Organizational constraints

Constraint Description

Development Process

This product will be built following Scrum/Kanban methodologies

GitHub Issues

The team will work using GitHub Issues as a way of documenting what is done in the project and to distribute the work among the team members

Pull requests

The team will use pull requests in order to integrate their work with the main one. Each pull request must be reviewed by another team member

Time

This application should be developed in a couple of months

Team meetings

The team will have at least 1 weekly meeting

Continuous integration

This project will use continuous integration using Github Actions

Testing

The system must have robust and meaningful tests to make the application as secure as possible

Version Control System

The development process of the application must use GitHub as Version Control System

2.3. Political constraints

Constraint Description

Data protection

The information about the useres must be properly stored and secured

Open source

This project is an open source project, and it could use other pieces of open source code of another related code

Code reuse

In case that this system requires to use code from other project, this must be specified in the documentation

2.4. Conventions

Constraint Description

English

The members of the team will use english as main language to communicate and write documentation

ARC42

The documentation will be written using ARC42 technology

Branching strategy

Each issue will require a branch that must be merged with the main project using pull requests

3. Context and Scope

This section defines the boundaries of the WIChat application, its communication partners, and the technologies used to interact with them. The system is designed to provide an interactive quiz experience, leveraging Wikidata for question generation and an Empathy API for LLM-based hints.

3.1. Business Context

The WIChat application interacts with the following communication partners:

Communication Partner Inputs Outputs

User

Answers to quiz questions, requests for hints

Quiz questions, hints, feedback (correct/incorrect answers)

Wikidata (via MediaWiki Action API)

Requests for question data (e.g., images, correct answers, distractors)

Question data (e.g., images, correct answers, distractors)

Empathy API

Requests for hints based on question data

Generated hints for quiz questions

Explanation of External Domain Interfaces:

  • Users: Interact with the system via a web frontend, answering questions and requesting hints.

  • Wikidata: Provides structured data for generating quiz questions and answers.

  • Empathy API: Generates conversational hints for users based on the question data.

System Context Diagram

3.2. Technical Context

The technical interfaces and communication channels for the WIChat application are as follows:

Communication Partner Channel/Protocol Input/Output Mapping

User

HTTP/HTTPS (Web Browser)

User interactions (answers, hint requests) and system responses (questions, hints)

Wikidata

HTTP/HTTPS (MediaWiki Action API)

API requests for question data and API responses with structured data

Empathy API

HTTP/HTTPS (REST API)

API requests for hints and API responses with generated hints

Explanation of Technical Interfaces:

  • Frontend: Built with React, communicates with the backend via HTTP/HTTPS.

  • Backend: Built with NodeJS + Express, handles API requests to Wikidata and Empathy, and manages user data in MongoDB.

  • Database: MongoDB stores user data, including historical performance and game statistics.

  • LLM Integration: Empathy API is used for generating hints.

Deployment Diagram

Mapping Input/Output to Channels:

  • User inputs (answers, hint requests) are sent via HTTP/HTTPS to the backend.

  • The backend sends API requests to Wikidata and Empathy, and processes their responses.

  • The backend sends quiz questions, hints, and feedback to the user via HTTP/HTTPS.

3.3. System Scope

The WIChat application includes the following components:

  1. Frontend: A React-based web application for user interaction.

  2. Backend: A NodeJS + Express server for handling business logic and API integrations.

  3. Database: MongoDB for storing user data and game statistics.

  4. External APIs:

    • Wikidata: For generating quiz questions and answers.

    • Empathy API: For generating conversational hints.

The system does not include:

  • Development of the LLM (Empathy) itself.

  • Hosting or maintenance of Wikidata.

3.4. Team Context

The project is being developed by a team of 5 students with the following responsibilities:

  1. Frontend Development: Implementation of the React-based user interface.

  2. Backend Development: Implementation of the NodeJS + Express server and API integrations.

  3. Database Management: Design and maintenance of the MongoDB database.

  4. Testing and Quality Assurance: Ensuring the system meets functional and non-functional requirements.

  5. Documentation and Deployment: Compiling documentation using AsciiDoc and PlantUML, and deploying the application to GitHub Pages.

3.5. Summary

The WIChat application is a web-based quiz system that integrates with Wikidata for question generation and Empathy API for hint generation. The system is built using modern web technologies (React, NodeJS, MongoDB) and follows the Arc42 template for documentation. Our team is responsible for all aspects of development, testing, and deployment.

4. Solution Strategy

Contents

A short summary and explanation of the fundamental decisions and solution strategies, that shape system architecture. It includes

  • technology decisions

  • decisions about the top-level decomposition of the system, e.g. usage of an architectural pattern or design pattern

  • decisions on how to achieve key quality goals

  • relevant organizational decisions, e.g. selecting a development process or delegating certain tasks to third parties.

Motivation

These decisions form the cornerstones for your architecture. They are the foundation for many other detailed decisions or implementation rules.

Form

Keep the explanations of such key decisions short.

Motivate what was decided and why it was decided that way, based upon problem statement, quality goals and key constraints. Refer to details in the following sections.

Further Information

See Solution Strategy in the arc42 documentation.

4.1. Technologies

  • React : React will simplify the task build reusable and modular UI elements for our application thanks to its component-based structure. It also allows us to use JSX, which is a syntax extension for JavaScript that allows us to write HTML elements inside our JavaScript code.

  • Express : Web application framework for Node.js which will simplify development on the server side. There is also available a wide range of third-party middlewares that we could include on our application.

  • MongoDB : No-SQL database based on flexible schemas, native support for JSON and simple query language

  • Docker: Handy portability and perfect integration with microservices applications.

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.

Building block level 1
Motivation

In this level we represent the general overview of the system from a high level point of view. This level represents the general idea in which the application is based.

Insert your explanations of black boxes from level 1:

If you use tabular form you will only describe your black boxes with name and responsibility according to the following schema:

Name Responsibility

<black box 1>

 <Text>

<black box 2>

 <Text>

If you use a list of black box descriptions then you fill in a separate black box template for every important building block . Its headline is the name of the black box.

5.1.1. WIChat

Here you describe <black box 1> according the the following black box template:

  • Purpose/Responsibility

  • Interface(s), when they are not extracted as separate paragraphs. This interfaces may include qualities and performance characteristics.

  • (Optional) Quality-/Performance characteristics of the black box, e.g.availability, run time behavior, …​.

  • (Optional) directory/file location

  • (Optional) Fulfilled requirements (if you need traceability to requirements).

  • (Optional) Open issues/problems/risks

Responsibility

Represents the whole system. It is in charge of managing the different modules that compose the application, as well as communicating with the LLM provider and Wikidata.

Interfaces

  • Wikidata: Retrieve questions and answers.

  • LLM Provider: Retrieve hints for the user.

5.1.2. Wikidata

This interface represents the Wikidata service that is in charge of providing the necessary information to create the questions that the user will have to answer. They should also provide the answers to the questions that the user will have to answer.

5.1.3. LLM Provider

This interface represents the provider of the LLM who the application communicates with to obtain the hints required by the user in order to answer the questions.

5.2. Level 2

Here you can specify the inner structure of (some) building blocks from level 1 as white boxes.

You have to decide which building blocks of your system are important enough to justify such a detailed description. Please prefer relevance over completeness. Specify important, surprising, risky, complex or volatile building blocks. Leave out normal, simple, boring or standardized parts of your system

Building block level 2
Motivation

In this level we represent the inner structure of the WIChat module. This level represents a communication between several parts of the application by means of a gateway.

5.2.1. WebApp

Responsibility

Represents the interacting point of the application. It contains the different modules that conform the application front-end. It is in charge of managing the user interaction.

Interfaces

  • Gateway Service: Communicate with the back-end.

5.2.2. WIChat Services

Responsibility

Represents the services that the WIChat module provides. It represents the back-end of the application.

Interfaces

  • Gateway Service: Communicate with the front-end.

  • LLM Provider: Retrieve hints for the user.

  • Wikidata: Retrieve questions and answers.

5.2.3. Gateway Service

This interface represents the accessing point where all services are joined together. It allows an easy communication between the different modules of the application and provides useful methods to fulfill that end.

5.3. Level 3

Building block level 3
Motivation

In this level we represent the inner structure of the front and back-end modules of the application. This level illustrates the different responsibilities of the modules that are encountered at the lowest level of the application.

5.3.1. Home

Represents the main page. It allows users to either log in or sign up.

Interfaces

  • Gateway Service: Display application status information.

5.3.2. New User

Represents the page where users can sign up.

Interfaces

  • Gateway Service: Save the registration data in the database.

5.3.3. Log In

Represents the page where users can log in.

Interfaces

  • Gateway Service: Authentication purposes.

5.3.4. User menu

Represents the menu that users can access once they have logged in or created an account.

5.3.5. Statistics

Represents the page where users can see their statistics.

Interfaces

  • Gateway Service: Obtain those statistics.

5.3.6. Game

Represents the page where users can play the game.

Interfaces

  • Gateway Service: Questions and hints.

5.3.7. Auth Service

Represents the authentication service where users will log into their accounts.

Interfaces

  • Gateway Service: Send the login status of the user that tried to log in.

  • Database: Retrieve the user information to check if the user information is valid.

5.3.8. User Service

Represents the service where users will manage their account creations.

Interfaces

  • Gateway Service: Accept the user account creation information.

  • Database: Insert the retrieved information for their persistance.

5.3.9. Statistics Service

Represents the service where statistics from users will be retrieved.

Interfaces

  • Gateway Service: Send those statistics to be displayed in the application.

  • Database: Store the statistics needed for the application to work.

5.3.10. Question Service

It is in charge of managing the creation of questions and answers.

Interfaces

  • Gateway Service: Sharing the question and possible answers to the user.

  • Database: Store the questions that might be needed for the application to work.

5.3.11. LLM Service

It represents the service that will provide the hints to the users by means of an LLM.

Interfaces

  • Gateway Service: Sending hints retrieved to the user.

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.

This section describes how the system components interacts between them. In this early stage, the information in this section cannot be too detailed.

6.1. User Authentication Flow

6.1.1. Sign up Flow

Authentication Sign Up Sequence

Notable Aspects: Ensures secure signup via an authentication service. Protects against duplicated.

6.1.2. Log in Flow

Authentication Log In Sequence

Notable Aspects: Ensures secure authentication via an authentication service. Protects against unauthorized access and ensures session management.

6.2. Quiz Question Retrieval Flow

Quiz Question Retrieval

Notable Aspects: Ensures an improvement in performance, reducing external api calls.

6.3. LLM Chat Interaction Flow

LLM Chat Interaction

Notable Aspects: Ensures that the application does not crash if the external provider of the LLM fails

6.4. Question Game Interaction Flow

Question Game Interaction

6.5. Statistics Interaction Flow

Statistics Interaction

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.

Our project is configured using GitHub actions so that every new github release publish triggers an attempt to deploy the application to a server.

This server is hosted on Azure and is configured to run the application using Docker containers. Only 2 ports are open to the public: The port to be used by the web application and the port to be used by the gateway service. We have configured in github a set of secrets: DEPLOY_HOST (the IP address of the server), DEPLOY_USER (the user to connect to the server), DEPLOY_KEY (the SSH key to connect to the server) that allows us to deploy the application to the server using SSH.

This setup enables our team to achieve continuous deployment and delivery (CD) together with continuous integration (CI).

7.1. Infrastructure Level 1

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

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

  • important justifications or motivations for this deployment structure

  • quality and/or performance features of this infrastructure

  • mapping of software artifacts to elements of this infrastructure

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

Deployment view L1
Motivation

  • The diagram above illustrates the initial version of our architecture and the delineation among its components. Our approach adopts a straightforward client-server architecture, where the server interacts with external services such as Wikidata or Empathy LLM. This division enforces a clear separation between the client/frontend and the server/backend. Such separation benefits the entire system by ensuring that as long as the common API is implemented, the specific implementations can remain interchangeable.

  • Utilizing an Ubuntu server on Azure provides us with an isolated environment equipped with the essential configurations and installations necessary for running our services. By hosting our server on Azure, we can minimize costs associated with machine uptime while alleviating responsibilities such as security, availability, and maintenance.

  • We use Docker as it is a containerization platform that allows us to package our application and its dependencies into a standardized unit for software development. This approach ensures that our application will run consistently on any environment, regardless of the machine’s configuration.

Quality and/or Performance Features

As mentioned earlier, the primary advantage of this architecture lies in the interchangeability of its components.

7.2. Infrastructure Level 2

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

7.2.1. Server Side

Deployment view L2

The gateway service works as an adapter between the micro services and the web client. The web application is the main interface for the user to interact with the system.

We’ve opted for a microservices architecture using Docker containers instead of a monolithic setup. Each service has its own Docker image. This Docker-based approach streamlines deployment, management, and resource utilization while enhancing the overall flexibility and scalability of our system.

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 All the documentation added is purely introductory, it doesn’t represent final decisions as the aplication isn’t developed yet.

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.

Class

Explanation

Question

The model of the questions stores both right and wrong answers.

User

The people using the application, they have statistics and take part in a ranking to compete.

Answer

Models each possible answer, created to reuse answers that are common to different questions, as well as distractors.

Game

It is created when the user starts a game and includes the rounds that the user has to answer.

Statistics

Stores information about the amount of correct and wrong answers that each user has answered.

QuestionCategory

Category for the question

AnswerCategory

Category of the answer (used for getting distractors)

8.1. Architecture and design patterns:

8.2. Safety and Security concepts:

Passwords must be hashed both in client and in API to ensure as much security as possible.An example to do it could be using SpringBoot3

8.3. Development concepts:

8.4. User Experience:

As this is a game, the focus must be in our users so players can have a good experience, for achieving this, the response time should be less than 1,5 seconds and the interfaces should be intuitive and easy to learn.

8.5. Robustness:

It is desired to make the application as independant as possible from Wikidata. This way, if Wikidata is down our application can still manage to be available for our users.

8.6. Under-the-hood:

9. Architecture Decisions

ID Decision Rationale Impacted Quality Attributes

AD-001

React with JavaScript frontend

Eliminates the overhead of type annotations and compilation; simplifies setup and iteration

Maintainability, Usability, Flexibility

AD-002

Node.js/Express backend

Unified JavaScript stack enables code reuse; event-driven architecture supports concurrent users

Performance Efficiency

AD-003

MongoDB Atlas (free tier)

Schema flexibility for evolving game stats; managed service reduces DevOps overhead

Reliability, Portability

AD-004

Empathy API + Wikidata validation layer

Balances LLM cost vs accuracy; validation prevents hallucinations

Reliability, Functional Suitability

AD-005

JWT authentication

Faster implementation than OAuth; sufficient for MVP security needs

Security

AD-006

Server-Sent Events (SSE)

Lightweight real-time updates without WebSocket complexity

Performance Efficiency

AD-007

Progressive Web App strategy

Single codebase for web/mobile; offline-first capabilities

Portability

9.1. Alternatives Considered (Discarded)

Decision

Alternative

Reason for Rejection

AD-004

Gemini API

Higher cost/complexity for student budget

AD-006

WebSockets

Added implementation time for academic timeline

AD-007

Native mobile app

Requires separate iOS/Android development

10. Quality Requirements

10.1. Quality Tree

Quality Tree

10.2. Quality Scenarios

ID Scenario Test Criteria

FS-1

Stimulus: User clicks "Get Hint" button
Response: System displays LLM-generated hint within 3 seconds

95% of hints match Wikidata facts (manual sampling)

REL-1

Stimulus: Auto-generate question from Wikidata
Response: Question has 1 correct + 3 valid distractors

SPARQL validation script passes 100% test cases

PE-1

Stimulus: 50 concurrent users start quiz
Response: Average API latency <2s

Locust.io report for /api/questions endpoint

MNT-1

Stimulus: Add new question category
Response: Developer implements feature in <4h

Git commit timestamps across branches

SEC-1

Stimulus: Invalid JWT token sent
Response: API returns 401 Unauthorized

Automated Postman tests

11. Risks and Technical Debts

Contents

A list of identified technical risks or technical debts, ordered by priority

Motivation

“Risk management is project management for grown-ups” (Tim Lister, Atlantic Systems Guild.)

This should be your motto for systematic detection and evaluation of risks and technical debts in the architecture, which will be needed by management stakeholders (e.g. project managers, product owners) as part of the overall risk analysis and measurement planning.

Form

List of risks and/or technical debts, probably including suggested measures to minimize, mitigate or avoid risks or reduce technical debts.

Further Information

See Risks and Technical Debt in the arc42 documentation.

In this section, the detected risks and technical debts of our project are presented in table format. Identifying this risks at the beggining of the project we can prevent them to scale, avoiding future problems

Risk Description Solutions

Security Vulnerabilities

Potential security risks such as SQL injection, cross-site scripting (XSS), or data leaks due to improper input validation or misconfigured authentication.

Conduct security audits, apply input validation, and use industry-standard authentication mechanisms.

Third-Party Dependency Risks

The application relies on third-party libraries and APIs, which may introduce vulnerabilities or become deprecated.

Regularly update dependencies, monitor security advisories, and have fallback options for critical libraries.

Performance Bottlenecks

Inefficient front-end rendering or API response times could degrade user experience.

Use lazy loading, asynchronous processing, and optimize API response times.

Lack of Automated Testing

Absence of sufficient test coverage may lead to undetected bugs and regression issues.

Implement unit, integration, and end-to-end testing as part of the CI/CD pipeline

Limited Documentation

Incomplete or missing technical documentation may slow down onboarding and maintenance.

Establish documentation guidelines and regularly update the knowledge base.

Inconsistent Coding Standards

Different team members might follow different coding styles, leading to inconsistency.

Define and enforce coding standards through linters, code reviews, and shared guidelines.

12. Glossary

Contents

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

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

Motivation

You should clearly define your terms, so that all stakeholders

  • have an identical understanding of these terms

  • do not use synonyms and homonyms

Form

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

Potentially more columns in case you need translations.

Further Information

See Glossary in the arc42 documentation.

Term Definition

REST

REST is an architectural style for web services that uses standard HTTP methods (GET, POST, PUT, DELETE) to manage resources. It is simple, stateless, and widely used for APIs.

SPARQL

SPARQL (SPARQL Protocol and RDF Query Language) is a query language used to retrieve and manipulate data stored in RDF (Resource Description Framework) format. It is the W3C standard for querying semantic databases and extracting structured information from the web.

LLM

LLM (Large Language Model) is a type of artificial intelligence model designed to process and generate human-like text. These models, such as GPT-4, are trained on vast amounts of text data and use deep learning techniques, particularly transformer architectures, to understand context, generate responses, and perform tasks like translation, summarization, and text completion.

Gateway

A gateway is a network device or software that acts as a bridge between two different networks, protocols, or systems, enabling communication and data transfer. It translates data formats, protocols, or addresses to ensure interoperability. Gateways are commonly used in networking, cloud computing, and API integrations.

Framework

A framework is a pre-structured set of tools, libraries, and best practices that provides a foundation for developing software applications. It offers reusable code and predefined components to streamline development, enforce consistency, and improve efficiency. Frameworks exist for various domains, including web development (e.g., React, Django), machine learning (e.g., TensorFlow, PyTorch), and software architecture.

Technical Debt

Technical debt refers to the trade-offs made in software development where shortcuts, quick fixes, or suboptimal solutions are implemented to speed up delivery but create future maintenance challenges. Over time, this "debt" accumulates, requiring refactoring, rewriting, or fixing, which can slow down development and increase costs. Managing technical debt involves balancing short-term productivity with long-term code quality and sustainability.

Front-end

Front-end refers to the part of a software application or website that users interact with directly. It includes the user interface (UI), design, and client-side logic, typically built using technologies like HTML, CSS, and JavaScript, along with frameworks such as React, Angular, or Vue.js. The front-end communicates with the back-end to fetch and display data while ensuring a smooth user experience.

Back-end

Back-end refers to the server-side part of a software application that handles data processing, business logic, and database interactions. It is responsible for managing requests from the front-end, executing operations, and returning responses. Back-end technologies include programming languages like Python, Java, Node.js, and Ruby, frameworks such as Django, Spring, Express.js, and Rails, databases like MySQL, PostgreSQL, and MongoDB, and server infrastructure.

Docker

Docker is an open-source platform that automates the deployment, scaling, and management of applications within lightweight, portable containers. Containers bundle an application and its dependencies (such as libraries and configurations) into a single, consistent unit that can run anywhere—on a developer’s laptop, on a server, or in the cloud. Docker ensures that applications work uniformly across different environments, simplifying development, testing, and production workflows.

MongoDB

MongoDB is a NoSQL, document-oriented database that stores data in flexible JSON-like documents, making it scalable and easy to use.

Node.js

Node.js is a JavaScript runtime built on Chrome’s V8 engine that allows developers to run JavaScript on the server side. It is used to build scalable, high-performance applications, especially for real-time services like chat applications and APIs.

13. Annex