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

The functional requirements that the application will include:

  • The system will have at least a web frontend that will display images and responses.

  • A hint system that will allow users to obtain hints with images.

  • User registration.

  • Users will be able to check their statistics (time played, number of games, games won/lost, etc.).

  • The information for questions and answers will be generated automatically from Wikidata.

  • An LLM model will be used for the hint system.

  • Questions must be answered within a specified time limit.

  • Each question will have one correct answer and several incorrect or distracting answers.

1.1. Objetivos de calidad

Quality Objectives Motivation Priority

Usability

Provide a good user experience, with a simple and attractive interface

High

Maintainability

Be able to make modifications to the game relatively easily, such as new questions or new game modes

Medium

Acceptable Performance

To ensure a good user experience, we must provide an application with reduced loading times and smooth gameplay.

High

1.2. Stakeholders

Role/Name Contact Expectations

Students

Yeray Rodríguez Granda, Diego García Gonzalez, Sara Fernández González, Daniel Álvarez Blanco, Carlos Cabrera Moral, Fernando Begega Suarez

Develop a good application

Teachers

Diego Martín Fernandez

Ensure that we develop a good application and learn the concepts taught in class

Users

Anyone using the application

Have fun playing the application we develop

WikiData

Wikimedia Deutschland

They are interested in us using their services

RTVE

RTVE

They want us to provide a good application based on the game "Saber y Ganar" to attract people to the program

LLM API Provider

LLM API Provider

They are interested in us using their services

2. Architecture Constraints

  • Frontend Restriction: The system will have at least a web frontend that will display images and answers, as well as a hint system that will allow users to obtain hints about the images.

  • Web Deployment: The web application must be deployed and accessible via the internet.

  • User Registration: Users will be able to register in the system and consult their participation history, including the number of games played, correct/incorrect answers, times, etc.

  • Use of the Wikidata API: The questions' information will be automatically generated from Wikidata data.

  • Use of an LLM: Users will be able to interact with the application for each question to obtain hints. A language model (LLM) will be accessed via an API. A technique must be introduced to generate hints from Wikidata data and mitigate incorrect answers and hallucinations during the conversation.

  • Question Model: Questions must be answered within a set time limit. Each question will have one correct answer and several incorrect or distractor answers. Both the correct and incorrect answers will be generated automatically.

  • Creation and Documentation of a Custom API: The system will allow access to user information through a documented API. The system will also provide access to generated questions through an API.

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)

Further Information

See Architecture Constraints in the arc42 documentation.

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.

technicalcontext

Element

Description

User

Plays the game through his device

System

The application that runs the game

Wikidata

Gives the info necessary for the questions and answers

LLM Service

Chat with the user through the System to give clues

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>

<optionally: Explanation of technical interfaces>

<Mapping Input/Output to Channels>

4. 4. Solution Strategy

4.1. 4.1. Technological Decisions

For the development of the system, technologies have been selected to optimize performance, maintainability, and scalability of the project.

  • Programming Language: TypeScript TypeScript was chosen as the main language for the project. Unlike JavaScript, TypeScript is a statically typed language, which helps with early error detection during programming. Its adoption avoided the need to completely migrate the existing JavaScript code to Java with Spring Boot.

  • Database: MongoDB MongoDB was chosen as the NoSQL database. This database allows handling data in a flexible format and scaling efficiently, facilitating integration with Node.js.

  • Frameworks and Libraries

    • React.js: Used for developing the user interface due to its modularity and ease of building interactive web applications.

    • Node.js: Used as the runtime environment for the backend layer, enabling a full-stack architecture based on JavaScript/TypeScript.

  • Version Control: GitHub GitHub was selected for version control. It allows for efficient source code management, continuous integration, and remote collaboration.

  • APIs: Wikidata y Gemini

    • Wikidata: Wikidata will be used to retrieve structured information about any given topic. The system will query Wikidata to gather relevant data, which will then be processed to dynamically generate questions. By using Wikidata as a data source, the system ensures that the information is accurate and up-to-date.

    • Gemini: The Gemini API will be used to create an interactive chat feature that generates hints for a quiz game. This will enhance user engagement by providing intelligent clues based on the context of the questions.

4.2. 4.2. Decisions on how to achieve key quality goals

To ensure the system meets high-quality standards, several decisions have been made regarding development, deployment, and maintainability:

  • Performance: The system will use a NoSQL database (MongoDB) to allow fast read and write operations.

  • Maintainability:

    • TypeScript is used to prevent runtime errors and improve code readability.

    • Modularization of the frontend and backend code to facilitate updates and enhancements.

  • Scalability: The backend is built on Node.js, allowing it to handle multiple concurrent requests efficiently.

  • Usability and Accessibility:

    • The UI will be designed following accessibility guidelines to ensure an inclusive user experience.

    • The interactive hint system using Gemini AI will improve user engagement and learning.

  • Testing and Deployment:

    • Unit and integration tests will be implemented to ensure system reliability.

    • End-to-end (E2E) testing will validate the complete user experience.

    • Continuous Integration/Continuous Deployment (CI/CD) pipelines will automate testing and deployment processes.

    • Performance and load testing will be conducted to ensure stability under high traffic conditions.

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.

5. Building Block View

5.1. Level 1: Whitebox Overall System

Hierarchy of building blocks
Motivation

This level shows the interaction of the user with the main system of the application, which in turn makes use of external resources.

Contained Building Blocks
Name Responsibility

Whichat

Is the main system. Handles user interaction and interacts with external resources

5.2. Level 2: Internal Structure of Level 1 Blocks

Hierarchy of building blocks

This level shows the division between the frontend and the backend, as well as the interface that connects both services.

Contained Building Blocks
Name Responsibility

WebApp

This system will allow the user to interact with the application, i.e. the frontend.

Gateway

This block will act as the API of our application, taking care of redirecting requests to the corresponding microservices.

WichatServices

This system acts as a backend, being responsible for both managing application services and interacting with external resources.

5.3. Level 3: Internal Structure of Level 2 Blocks

Hierarchy of building blocks

In this level of descomposition of the system we identify the different views of the webapp and microservices of the WichatServices.

Contained Building Blocks

Webapp

Name Responsibility

Home

__

Login

__

Signup

__

GameMenu

__

Stats

__

Game

__

WichatService

Name Responsibility

UserService

__

AuthService

__

StatsService

__

QuestionService

__

ClueService

__

6. Runtime View

6.1. Secuence diagram of application

actor p as "Player"
participant g as "Game"
participant r as "Repository"

p -> g: Start Game
p -> g: Choose model and init
loop Game Loop
g -> r: Requests random question
r -->g
g -> p: Ask the question
|||
...Player takes some time to answer the question......
|||
p -> g: Answer the question
g -> r: Store question's answer
r -> r: Calculate score
r -> g: Returns final score
g -> p: Show final score
g -> p: Show ranking
end
p -> g: Ends game

7. Deployment View

7.1. Infrastructure Level 1

Schema
Motivation

While developing and testing the app it will be run on the developer’s localhost enviroment (Using docker for standarization). However, in the production stage we aim for the aplication to be running on a Azure Server.

Quality and/or Performance Features

We haven’t tested the app’s performance

Mapping of Building Blocks to Infrastructure
Element Description

Azure Server

Where the application will be deployed.

Docker Engine

Daemon inside the azure server which will run our docker containers

WebApp

It is the frontend of our application.

MicroServices

They create the backend of the application, they manage every aspect of the application.

WikiData

It is an external service which will provide the necessary data for the application to work properly.

LLM

It is an external service that will provide the clues to the user by conversation

8. 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. 8.1. Domain Model

  • Users: Represents the players, including data such as name, email, game statistics and answer history.

  • Questions and Answers: Model that includes the image, statement, answer options (correct and incorrect), and the source (Wikidata).

  • Hints: Data dynamically generated from a language model (LLM).

  • Game Sessions: Records the users' sessions, including given answers, times, and results.

8.2. 8.2. User Experience concepts (UX)

The user interacts with the application through a user interface. In this interface, the user must either register or log in. Once the user has been identified, they can start a quiz or check their participation history.

Regarding the quiz, the user will see a question on the screen along with a series of possible answers. When one of these answers is selected, the user will receive feedback based on whether the chosen answer is correct or not. Additionally, there will be a chat in the bottom left corner that will interact with the user to provide a series of hints.

9. Architecture Decisions

1.TypeScript

Contents

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

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

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

Motivation

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

Form

Various options:

  • ADR (Documenting Architecture Decisions) for every important decision

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

  • more detailed in form of separate sections per decision

Further Information

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

10. Quality Requirements

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

Quality

Description

Scenario

Usability

The application must be easy to learn to use by design.

__

Performance

The application should have a waiting time of no more than 5 seconds between actions.

__

Persistence

The system should prevent any possible lose of user information.

__

Integrity

The system should grant confidentiality to the user’s data.

__
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.2. Quality Scenarios

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

11.1. Risks

Risk Relevance Considerations

Limited knowledge of certain tools or languages

High

A solution could be to use the tools and languages that are most well-known to the team members. Also, each member should try to learn those aspects they know less about.

Limited expertise in emerging technologies

High

Ignorance of emerging technologies relevant to the project might result in missed opportunities for innovation and efficiency.

The team has not worked together before

Low

A suggestion could be to mantain a good communication and inform about any aspect that could affect others.

Delivery time

Medium

Being many members can difficult the communication. However, if the previous suggestions are followed there should not be any problem.

Connection failure

Medium

It is possible that some of the parts of the project that may require a connection to a server are not available, and due to time it may cause problems.

Documentation

Low

Since the documentation is carried out at the same time as the project, it can generate delays.

11.2. Technical debts

Technical Debt Relevance Considerations

Not implementing automated tests from the beginning

High

It is not a recommended practice and can avoid problems in the future.

12. Glossary

Contents

Insert a brief description of what this glossary contains.

Motivation

Explain why it’s important to define these terms for your stakeholders: * Ensure a shared understanding. * Avoid ambiguity with synonyms or homonyms.

Form

Describe the structure of this glossary (e.g., a table with columns for Term and Definition).

Further Information

Insert any additional references or links (e.g., documentation or guidelines).

Term Definition

LLM (Large Language Model)

Large Language Model based on artificial intelligence and deep learning. It is used to process and generate text with contextual understanding, such as OpenAI’s GPT, Google Bard, and others.

Microservices Architecture

A software architecture style in which an application is divided into small independent services that communicate with each other through APIs. Each microservice focuses on a specific functionality and can be developed, deployed, and scaled independently.

Docker

A containerization platform that allows packaging applications and their dependencies into portable containers. It facilitates consistent execution across different environments without worrying about compatibility issues.

JavaScript

An interpreted programming language primarily used for web development. It enables the creation of interactive and dynamic pages, functioning both in the browser and on the server through environments like Node.js.

React

A JavaScript library developed by Meta (Facebook) for building interactive and efficient user interfaces. It utilizes a component-based model and a Virtual DOM to improve performance in web applications.

Node.js

A server-side JavaScript runtime environment built on Google Chrome’s V8 engine. It allows building scalable and high-performance applications using an asynchronous, event-driven programming model.

Backend

The part of an application that handles business logic, databases, authentication, and communication with the frontend. It is typically developed using technologies such as Node.js, Python, or Java.

Frontend

The visual interface of an application with which users interact. It is built using HTML, CSS, and JavaScript, along with frameworks like React, Angular, or Vue.js.

Express.js

A minimalist web framework for Node.js that simplifies the creation of applications and APIs. It provides tools for handling routing, middleware, and HTTP requests efficiently.

Term

…​