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

Purpose

WiChat is an extension of a previous experimental web application that allowed users to answer quiz questions emulating the "Saber y Ganar" quiz show. This year, the system is being expanded by adding images accompanying all the questions and introducing a conversational hint system powered by an external Large Language Model, enhancing the user experience by providing dynamic and interactive assistance.

The project is requested by RTVE and developed by ChattySw, which will build the application using some pieces of code or modules from the work previously done by HappySw company, but creating the application from scracth.

Scope of Work

WiChat will expand the existing quiz system by:

  • Retaining the core gameplay, where users answer image-based questions from various domains.

  • Introducing an AI-powered hint system for interactive assistance.

  • Keeping automation of questions using Wikidata, minimizing manual effort.

  • Ensuring accessibility through a web-based platform.

  • Add additional features such as custom games and an AI vs user game mode. Additionally, the system should be designed with extensibility in mind, allowing for future improvements.

Driving Forces

The development of WiChat is guided by the following key goals:

  • Enhancing User Engagement: Implementing an interactive AI-based hint system.

  • Automating Content Generation: Using Wikidata to provide dynamically created questions.

  • Ensuring Accessibility: Delivering a web-based solution that is easy to access and use.

  • Providing a Structured Experience: Offering game statistics and historical data for users.

This document will outline the foundational aspects of the system, including its requirements, quality goals, stakeholder expectations and all the strategies and decisions taken.

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.

The main requirements of the system that encapsulates the key features are:

  • The system shall allow unregistered users to sign up.

  • The system shall provide authentication for users to log in.

  • The system shall allow registered users to log out.

  • The system shall allow registered users to play.

  • The system shall allow registered users to check their statistics.

  • The system shall allow users to request hints for a question.

The complete list of requirements can be found in the Annex of the documentation.

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

Quality Goal Concrete Scenario

Reliability

The system should be reliable and diverse in generating questions from Wikidata, having no more than 5% of questions with wrong distractors. AI hint system should be accurate and allucinations should be minimized to no more than 2%. The system shall handle user registrations, logins, game data storage and gameplay with an error rate of less than 1%.

Performance Efficiency

The system should efficiently handle an increasing number of concurrent users up to 20 while keeping response times below 1 second. AI hint generation should not cause performance bottlenecks.

Security

Users' personal data and authentication details should be securely stored. API requests should be protected from unauthorized access.

Usability

The UI should be intuitive for first-time users, and game interactions should be easy to understand. The system learning time for a new user should be less than 1 hour.

Maintainability

The architecture should be microservices to allow developers to easily add new game modes, AI features, or question sources without major system refactoring.

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

Development Team

Héctor Triguero del Río - UO288992@uniovi.es, Daniel Fernández Cabrero - UO288499@uniovi.es, Umut Dolangac - UO311846@uniovi.es, Diego Martínez Chamorro - UO294054@uniovi.es

They aim to develop a clear, scalable, and well-documented system while gaining hands-on experience in software development.

Development Company

ChattySw

They expect the project to be well-structured, maintainable, and extensible, ensuring it meets the client’s needs.

Previous Developer

HappySw

They expect their previous work to be properly used, ensuring compatibility and that they receive their credits when their work is used.

Client - RTVE

RTVE Representatives - rtve.dircom@rtve.es

They hope to receive an engaging quiz application that aligns with their vision and improves their digital presence.

Client - Professors (Evaluator)

Pablo González González - gonzalezgpablo@uniovi.es, Jose Emilio Labra Gayo - labra@uniovi.es, Irene Cid Rico - cidirene@uniovi.es, Diego Martín Fernández - martinfdiego@uniovi.es

They expect a well-structured architectural document, clear software design decisions, and a properly implemented system.

Users

End Users

They hope for a fun and competitive experience, with the ability to view statistics and receive personalized interactions.

Wikidata (Wikimedia Foundation)

Wikidata Community

They hope for correct and responsible usage of their data, including proper attribution and compliance with API policies.

LLM Provider

Gemini/Empathy.ai

They expect proper API usage, adherence to ethical AI practices, and avoidance of misuse that could generate misleading or inappropriate hints.

Competitors

Kahoot, Quizziz, Trivia Crack

They provide a reference for best practices in engagement and accessibility.

Legal Advisors and Regulators

GDPR Regulators, RTVE Legal Team

They expect the system to comply with data protection regulations and respect intellectual property rights.

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)

Further Information

See Architecture Constraints in the arc42 documentation.

2.1. Technical Constraints

Constraint Explanation

WikiData

The application requires data retrieval and processing to generate questions using images from WikiData.

Version control and monitoring (GitHub)

GitHub is a useful tool for version control and collaboration among the team members working on the project.

User Experience (UI and UX)

The application’s design must prioritize a user-friendly and intuitive experience.

Test coverage

The code must achieve high test quality and coverage to ensure reliable and expected outcomes.

Data Storage and Management

User data must be stored securely and efficiently. In order to achieve this goal, database selection is crucial.

LLM (Large Language Models)

The application will leverage LLMs for specific functionalities (e.g., question generation, hint.)

Web Accessible Front-End

The application will be accessed through a web browser

2.2. Organizational Constraints

Constraint Explanation

Team Size and Structure

The project will be developed by a team of 5 students.

Git-Based Development

The project will follow a Git-based workflow. All tools and processes must integrate seamlessly with Git for version control, collaboration, and code management.

Meetings and Documentation

Team meetings will be held every Monday to discuss progress, challenges, and next steps. The development process must be documented in meeting minutes, including decisions made, action items assigned, and progress updates.

Delivery Deadlines

The project has 3 deliverables, each with a 3-week interval.

Communication Channels

The team will use WhatsApp and GitHub for daily updates, discussions, and issue tracking.

2.3. Political Constraints

Constraint Explanation

Documentation

Arc42 template is pre-selected for documentation.

Language

Documentation will be written in english and application will support english and spanish.

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

This project consists of a web application in which users can play a quiz game, as well as registering and logging in. Also, it allows to consult information as an API. The quiz game’s questions are generated using an LLM and WikiData.

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

Business Context
Communication Partner Input Output

User

Interaction with the application like answering to questions, introducing credentials and asking for user data.

Proper response to the interaction performed by the user.

WIChat

Interaction by the user.

Data to the user like questions, question’s results and user data.

Wikidata

Queries from the application for obtaining information from Wikidata.

Data returned from the Wikidata database that is asked for in the query.

LLM

Queries from the application for generating hints.

The hints that have been generated by the LLM.

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

Technical Context
Component Description

User

The user that interacts with the application.

User device

The device used by the user to interact with the application.

User agent

The browser through which the user can request and access the application.

Cloud

The cloud that hosts the application.

WIChat

The application which the users can interact with.

Database

Database that stores all the data of the application.

Wikidata

Returns data to the application requested by SPARQL queries received.

LLM

Generates and returns hints based in the queries received.

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

  • JavaScript: It is the chosen programming language for this application. After comparing it with TypeScript, we concluded it is the best choice taking into account easiness in the use and team experience.

  • React: We have chosen this JavaScript library for the UI because it is the industry standard and other alternatives don’t provide any benefits compared to it and it’s easy use.

  • Node.js: We decided to use it so we use JavaScript both in the frontend and backend. Also, since Mongoose, which will be used to comunicate with the database, is a Node.js library, Node.js is a good option for this application.

  • Docker: We chose it since several members of the team have experience with it and it’s easy to learn for new users compared to other alternatives. Also, it’s open-source and user friendly.

  • MongoDB: We decided to use this document database due to its flexibility and simple query language.

  • Microsoft Azure: We chose this platform since it provides the needed infrastructure and the team members have experience with it.

  • Express.js: We have chosen this web application framework for Node.js due to its high flexibility, its easy use and learning and its powerful middleware.

There are more technology decisions that are not listed here, but they are not as relevant as the ones listed above. The complete list can be found in the Architecture Decisions section of the documentation.

4.2. Top-level decomposition decisions

  • Non-pure microservices pattern: This pattern is used, so the application is divided into different components with a responsibility each one. This makes the different components independent and lowly coupled, allowing mantainability. Also, it reduces possible conflicts between the development carried out by the team members and the code dependencies. The pattern is non-pure to reduce the complexity of the application and redundancies between the microservices.

  • Gateway pattern: This pattern is chosen because it allows to give the application a single request interface that redirects requests by the user to the appropiate application component. It is the appropiate pattern to complement the Microservices pattern due to these reasons.

4.3. Decisions to achieve key quality goals

  • Mantainability: The application will be well structured and documented to allow a proper mantainability.

  • Usability: A user-friendly application will be developed, as well as intuitive.

  • Testability: Multiple tests will be performed on the application to ensure the proper functioning of the application and to ensure there are no errors.

4.4. Organizational decisions

  • Use of a Github repository for the project.

  • Weekly meeting of the team to review and discuss work done during the week, to take decisions for the project and assigning tasks that must be made.

  • Communication between members and task assigning using Github Issues.

  • For a quick and agile communication, use of a WhatsApp group of the team.

  • Keep track of all the work done by the team using Github Projects, linking on it the different Issues.

  • Record the weekly meeting minutes and details and project decisions by means of Github Wiki.

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

blackbox.drawio
Contained Building Blocks
Building Block Brief description

WiChat

Overall system that is being documented.

Player

Regular players of the game which interact with the system through the web interface.

API User

Users of the different public APIs.

WikiData

API used to generate questions and answers for the game.

LLM

LLM API used to generate hints for the game.

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

overview.drawio
Motivation

We divided the system into microservices according to their responsibilities to ensure:

  • simplicity: Each component is minimal and is responsible for a single function, which makes it easier to understand and maintain.

  • reusability: Microservices have interfaces which can be easily used by other new or old components if required.

  • independence: Components are made as independent as possible, also dependencies are always on stable abstractions protecting client services from the implementation.

  • maintainability: Each component is simple and as independent as possible from the others allowing fast understanding and reducing the probability of making mistakes.

  • extendability: New features can be added easily by adding new code to components or by adding new components, avoiding having to modify / rewrite code.

  • switchability: External services can be easily replaced by other services by just writing an adapter.

Note
 Check LLM Service for an example of reusable design.
Contained Building Blocks
Building Block Brief description

LLM Service

Serves as an adapter for the external LLM service.

Questions Service

Generates questions using WikiData.

Game Service

Manages game states and tracks the user’s progress.

Statistics Service

Tracks and provides statistics for the users.

Authentication Service

Handles login, signup and session for the users.

Gateway

Proxies some services to the Internet and supports the WebApp.

WebApp

Provides the web UI.
Interfacing

  • The different microservices communicate with each other via RESTful APIs using an intranet.

    • The Gateway and WebApp are the only services which allow external requests and communicate with eachother through Internet.

    • LLM Service and Question Service also communicate with the external LLM and WikiData respectively using the Internet.

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.2.1. LLM Service

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

Motivation

This thin module could be integrated in Questions Service, but we decided to keep it separate to promote reusability, since one of the optional requirements is using AI for anything other than hints.

Purpose

Act as a bridge (adapter) between the external LLM service and the other internal services of the application.

Interface

Internal RESTful API for communication with the other internal microservices.

Structure

Just an Express.js app with an adapter for the external LLM.

5.2.2. Statistics Service

Purpose

Tracks and provides statistics for the users.

Interface

Internal RESTful API for communication with the other internal microservices.

Structure

It’s a typical Express.js application with a model for the statistics and a database adapter to store the data.

5.2.3. WebApp

Purpose

Provides the web UI for the application.

Interface

Web UI for the users.

Structure

Follows the structure of a typical React application with several routes.

5.2.4. Gateway

Purpose

Proxies some services to the Internet (public API) and supports the WebApp. Adds "firewall" mechanisms typical of APIs: ratelimiting, HTTPs, security headers, etc.

Interface

RESTful API exposed to the Internet with a subset of the internal services.

Structure

It’s a typical Express.js application with middleware, proxy and endpoint documentation modules.

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

5.3.1. White Box "Questions Service"

…​describes the internal structure of building block 1.

questions service.drawio
Purpose

Generates questions and hints ensuring performance and correctness.

  • Questions and answers are generated through WikiData.

Motivation

Handles the responsibility of generating questions.

Why is WikiData part of the module and not standalone?

Since the service is used only for generating questions and answers (and this will most likely remain true), it is more efficient to have it as part of the module and reduce the overall system complexity at the cost of increasing the module’s one.

Contained Building Blocks
Building Block Brief description

WikiData Adapter

Serves as an adapter for the external WikiData API.

Questions Module

Generates questions from the WikiData information.

Questions Cache

Allows caching of questions to reduce the load on the WikiData API. It is necessary for performace reasons.

Express.js Server

Provides an internal RESTful API for the rest of microservices.

5.3.2. White Box "Auth Service"

auth service.drawio
Purpose

Allows users to login, signup and verify their local session.

Motivation

Keeps the user’s sensitive data and session separate from the rest of the application to ensure higher standards of security and privacy.

Contained Building Blocks
Building Block Brief description

Data Model

Represents the user’s data.

DB Adapter (Mongoose)

Provides persistence for the model entities.

Login Handler

Allows login and obtaining a session.

Register Handler

Allows registering a user.

Verify Handler

Allows verifying an user session. Internal service

Encryption Utilities (Argon2/JWT)

Provides encryption utilities to secure sessions and stored passwords.

Configuration

Provides configuration for the service.

Validators

Provides validation inputs.

Server (Express.js)

Provides an internal secured RESTful API for the rest of microservices.

5.3.3. White Box "Game Service"

game service.drawio
Purpose

Responsible for connecting Questions Service with Statistics Service, that way we can keep track of the user’s progress and provide statistics. It also generates hints using LLM Service.

Motivation

Takes care of the game logic and user’s progress. Also it tracks the user’s progress to provide statistics.

Contained Building Blocks
Building Block Brief description

Game Manager

Keeps track of user games and fires stats events.

Hints Module

Generates hints using the LLM Service.

Express.js Server

Provides an internal secured RESTful API for the rest of microservices.

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. Abstract states of the application

  • General usage, the user arrives to the application, creates an account or logs in, goes through the menu settings and plays. The state diagram shows the relation of the different situations of the app.

State Diagram of the general game behaviour

6.2. Login of a user

  • Login, the app shows the login interface, where the user is asked for the username and password, and the possibility to create an account.

When logging, the app does a login request to the authentication service through the GatewayService, which redirects the user to the identity provider, which handles the authentication by checking the registered users. If the login is succesfully, the app shows the different options of the game. In case the login isn’t succesfully, a warning message is shown.

Sequence Diagram of the login of a user

6.3. Game

  • Game transitions and process behind the user interface.

When playing, the user interface interacts with the distribution facade Gateway, in charge of hiding the back-end services, business and persistance layers.

Sequence Diagram of the game runtime behaviour

6.4. Statistics of a user

  • Statistics of a user.

When the user enters the view, statistics about themselves are shown.

Sequence Diagram of displaying the statistics of a user

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 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 Diagram Level 1 Infrastructure

Motivation:

The system uses Docker to keep services isolated and portable, ensuring smooth transitions between development, testing, and production. A microservices approach separates key functions like authentication, game logic, stats, and question handling, allowing independent scaling and preventing failures in one service from affecting the rest.

A central API Gateway simplifies client interactions and enhances security by preventing direct access to internal services. External services like WikiData and an LLM API handle question generation and AI-driven hints, reducing infrastructure complexity and using external computing power.

Quality and/or Performance Features:

This system is built to handle growth. Each part can be scaled up as needed. In this diagram we use containers, so if we need more of something like the Question Service, we can easily add it. With Docker-compose we can automate this.

Security is important.The API Gateway adds a layer of security by managing and authenticating all incoming requests.

If something goes wrong, the container system helps because if one part fails, it can be restarted without affecting the others. We also have logging and monitoring to help us find and fix problems quickly.

We’ve focused on performance too, MongoDB is used for flexible and efficient data storage for game info.

Mapping of Building Blocks to Infrastructure
Artifact Infrastructure

webapp (React)

WebApp Container

gatewayservice (Node.js/Express)

Gateway Container

authservice (Node.js/Express)

AuthService Container

statservice (Node.js/Express)

StatsService Container

gameservice (Node.js/Express)

GameService Container

questionservice (Node.js/Express)

QuestionsService Container

llmservice (Node.js/Express)

LLMService Container

Database (MongoDB)

Database Container

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. User Experience (UX)

The user experience in the system involves the design of the user interface and the level of accessibility, usability and satisfaction that it provides. As the part of the system that the user interacts with, the focus is put in providing a user-friendly interface, which gives a proper user experience. This user experience is a key concept in web applications such as the one developed, in which a high degree of usability is required for the user’s satisfaction and overall experience.

8.2. Internationalization

As a key part of User Experience, Internationalization (i18n) is a very important part in the system. The adjustment to several languages and the flexibility it provides, allows the system to be user-friendly, providing a high usability to several types of users based on their languages, overrunning language barriers.

8.3. Architectural patterns

The system follows several architectural patterns: Microservices pattern, so the system is composed of different independent components, and Gateway pattern, which provides a single interface for all the users that manages and redirects all their requests. The use of these architectural patterns provides a high degree of mantainability and also high flexibility in the development.

8.4. Security

As a key in all types of systems, security is a very important concept in this one and its development. Resources and data are protected and only provided to allowed users, implementing an authentication systemps that enforces the system’s security.

8.5. Error handling

Proper error handling techniques are implemented in each system’s component to ensure the reliability and availability of the system. Every call or dependency between components or important parts is managed to throw and detect types of errors and not propagate them thorughout the application, sending proper messages and codes to the different components to ensure the availability of the system and its proper working without failing. This enhances, in case an error occurs, the user experience so the user is informed if some process can not be carried out.

8.6. Observability

The system is designed to be observable, allowing gateway request monitoring from Grafana + Prometheus, as well as a more rudimentary monitoring of the different components through the use of a common and consistent logging system. This system allows logging errors, warnings and requests among others. It also enables faster debugging. Lastly the system is configured to censor sensitive information in the logs, such as authentication tokens and referrers.

9. Architecture Decisions

The ADRs (Architecture Decision Records) are stored in the GitHub Wiki of the project and are available at: https://github.com/Arquisoft/wichat_en1c/wiki/Decision-Records

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.

Reliability

The system must maintain a high level of operational stability and accuracy. This is measurable through several key indicators:

  • Question Generation Accuracy: The rate of incorrectly generated distractors in quiz questions sourced from Wikidata should be less than 5%.

  • AI Hint Accuracy: The AI-powered hint system should provide accurate and relevant hints, with the occurrence of hallucinations or misleading information being less than 5% of hint requests.

  • Core Functionality Error Rate: The system’s handling of user registrations, logins, game data storage, and gameplay should have an error rate of less than 1%.

Performance Efficiency

The system must provide a responsive and efficient user experience, even under moderate load. This can be measured by:

  • Concurrent User Capacity: The system should be able to handle up to 20 concurrent users while maintaining an average response time for critical user interactions (loading questions, submitting answers, requesting hints) below 1 second.

  • AI Hint Generation Latency: The time taken to generate an AI hint should not introduce a performance bottleneck, adding no more than 1 second to the overall response time for a hint request.

Security

The confidentiality and integrity of user data and system access must be ensured. Measurable aspects include:

  • Data Storage Security: User personal data and authentication credentials must be stored using robust encryption algorithms and protected against unauthorized access.

  • API Access Control: API endpoints should be secured through authentication and authorization mechanisms (JWT), preventing any successful unauthorized access attempts as verified by security testing.

Usability

The system should be intuitive and easy to use for all users, including those new to the application. This can be evaluated by:

  • First-Time User Success Rate: At least 80% of new users should be able to successfully register and complete a basic game within 10 minutes without needing external assistance.

  • User Interface Clarity: User feedback should indicate that at least 90% of users find the game interactions to be "easy to understand."

  • Learning Curve: The average time required for a new user to become proficient with the core functionalities of the system should be less than 1 hour, as measured by their ability to complete defined tasks during an onboarding process.

Maintainability

The system’s architecture should facilitate future modifications, extensions, and bug fixes with minimal effort and risk. This can be assessed by:

  • Modularity for New Features: Adding a new game mode or integrating a new question source should require modifications to no more than 5% of the existing codebase and be achievable within a timeframe of 2 weeks.

  • Ease of Updating External Dependencies: Updating the AI hint model or integrating a completely new LLM service should be possible with a development effort of no more than 3 days.

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

Usage Scenarios

Usage Scenario

System Reaction

User Login: A user opens the web application, enters valid credentials (username and password), and clicks the "Login" button.

The system authenticates the user within 0.5 seconds and redirects them to the home interface. If the credentials are invalid, an error message is displayed to the user within 0.3 seconds.

Start Game: A logged-in user clicks the "Play" button.

The system retrieves the first question (including image and answer options) within 1 second and displays it to the user.

Answer Question: The user selects an answer option and clicks it.

The system evaluates the answer within 0.3 seconds, provides immediate feedback (correct/incorrect), updates the user’s score, and presents the next question within 2 seconds.

Request Hint: The user writes a question and clicks the "Hint" button for a question.

The system sends a request to the LLM Service and displays a relevant hint to the user within 1 second.

View Statistics: A logged-in user navigates to the "Statistics" section.

The system retrieves and displays the user’s game statistics (games played, correct answers, etc.) within 1 second.

Change Scenarios

Change Scenario

System Reaction

Adding Email Login: The requirement is to allow users to log in using their email address in addition to their username.

The Authentication Service is modified and deployed without disrupting the existing username-based login functionality. New users can register with email, and existing users can optionally link their email to their account. Both login methods function correctly after the change, verified by automated tests.

Integrating a New Game Mode: A new game mode (e.g., 1 text question, 4 image answers ) needs to be added to the application.

New components and logic for the new game mode are added primarily within the Game Service and WebApp. The existing game modes remain functional without modification. The new mode can be accessed through the user interface without altering the main navigation flow.

Switching LLM Provider: The current LLM provider is replaced with a new one (requiring a different API).

The LLM Service is adapted to communicate with the new LLM provider through a new adapter. The interface exposed by the LLM Service to other microservices remains consistent, minimizing impact on the Game Service. Hint functionality remains operational after the change.

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.

Considering the recent loss of a team member, the team’s tendency towards end-of-sprint workload accumulation, challenges with branch merging due to testing, and the adoption of new technologies, the following are key risks and potential areas of technical debt that require attention (Relevance from 1(low) to 3(high)):

Category & Item

Relevance

Considerations & Potential Mitigation

Team Capacity Risk: Loss of a team member.

2

Reduced team capacity directly impacts velocity and potentially deadlines. Mitigation: Re-evaluate current workload distribution, prioritize critical tasks, explore options for temporary or permanent replacement, and ensure thorough knowledge transfer from the departed member.

Workflow Risk & Potential Debt: End-of-sprint workload spikes.

2

Accumulating work at the end of a sprint leads to rushed implementations, increasing the risk of bugs and impeding sustainable pace. It can also result in "quick fixes" that introduce technical debt. Mitigation: Implement stricter "work in progress" limits, encourage continuous integration and testing throughout the sprint, and focus on completing tasks earlier.

Code Integration Risk & Potential Debt: Branch merge conflicts due to testing issues.

2

Frequent merge conflicts disrupt development flow and signal potential issues with test coverage, quality, or understanding. This can lead to hastily resolved conflicts and hidden technical debt. Mitigation: Enhance team understanding and application of testing strategies, enforce stricter test requirements before merging, and consider more robust branching strategies. Investigate the root causes of test failures and conflicts.

Technology Adoption Risk & Potential Debt: Limited experience with React, MongoDB, Jest, and Puppeteer.

1-2 (reducing over time)

While the team is using these technologies, a lack of deep understanding can lead to suboptimal implementations, performance issues, or maintainability challenges (potential technical debt). Mitigation: Encourage ongoing learning through documentation, tutorials, and internal knowledge sharing. Implement thorough code reviews focusing on best practices for these technologies. Dedicate time for focused learning on testing frameworks.

Implicit Knowledge Risk: Reliance on individual team member knowledge.

1

Despite efforts towards knowledge sharing, some critical aspects or modules might still heavily rely on the understanding of specific team members. Proactive knowledge transfer and documentation of key functionalities and architectural decisions are crucial to ensure maintainability by the entire team.

12. Test Report

Our application has been tested using the following methods:

12.1. Unit tests

Unit tests were written to test each microservice independently, by mocking the dependent microservices and ensure each microservice works as expected.

The unit tests were written using the Jest framework, which is a popular testing framework for JavaScript applications.

12.1.1. Coverage

These tests have a minimum required coverage of >80% of the codebase which, at the time of writing this report is, 86.8%.

For a more detailed report about the coverage, refer to the following link.

12.2. Acceptance / integration tests (E2E tests)

Integration tests were written using the Cucumber framework, and Jest as the execution platform.

A total of five sets of tests were created to ensure all features of the application are covered and tested.

These tests allow verifying that the system behaves as expected when all components interact together.

The functionalities that were tested are:

  • Register

  • Login

  • Game flow

  • Statistics storage and display

  • Customization of game

12.3. Load tests

Load tests were written using the Gatling framework, which is a popular testing framework for load testing.

A load test comprising all the features except for custom games was created and run by 20 active users at a time. Overall the test output was positive, as the system was able to handle the most of the load without issues, thus proving the "performance" quality attribute.

The last test report can be found in the repository.

Load Test Report

12.3.1. Issues found

Some performance issues were detected during the load tests, and an issue in the repository was created to track them:

  • We detected that the question service struggled with getting the first question, which took >1200ms almost half of the time. The question service should be improved to be able to handle more requests.

Slow Questions Issue

To solve it the queries to WikiData were optimized which improved a lot the timings.

Solved Question Issue

  • Also, we detected that serving the background video stream was a bottleneck, so it should be moved to an external CDN to alliviate the load on the WebApp.

Slow Video Issue

We currently don’t have means for solving this issue, but we are aware of it and will try to solve it in the future.

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

Question

A set comprising: a textual question referring to an image, the image itself, and a series of options where one is correct while the others serve as distractors.

Distractor

A wrong answer to a question. The distractors are the options that are not correct, and they are used to mislead the user into selecting them instead of the correct answer.

LLM (AI)

A large language model is a type of artificial intelligence that uses deep learning techniques to understand and generate human-like text. It is trained on vast amounts of text data and can perform various natural language processing tasks, such as text generation, translation, summarization, and more. In the context of this project, the LLM is used to generate hints based on questions.

Hint

Textual clue or suggestion provided to the user (when requested) to help them answer a question correctly. These are generated by the LLM based on the question and the image associated with it.

Docker

A platform for developing, shipping, and running applications in isolated environments called containers. Used in WiChat for service isolation and portability.

Docker-compose

A tool for defining and managing multi-container Docker applications.

Microservices Approach

The architectural style of building an application as a collection of small, independent services.

API Gateway

The Gateway component that acts as a single entry point for all client interactions, simplifying access to backend services and enhancing security.

HTTPS

Hypertext Transfer Protocol Secure, a protocol for secure communication over a computer network, widely used on the Internet.

SPARQL

SPARQL is a simple query language for data in RDF format (Resource Description Framework). It helps find specific information by describing patterns.

14. Annex

14.1. Functional Requirements

14.1.1. Registration

  • FR-REG-1: The system must allow unregistered users to create an account.

    • FR-REG-1.1: The system shall require the following information for registration:

      • FR-REG-1.1.1: Username (mandatory and unique).

        • FR-REG-1.1.1.1: The username must be:

          • FR-REG-1.1.1.1.1: Longer than or equal to 5 characters

          • FR-REG-1.1.1.1.2: Shorter than or equal to 20 characters

          • FR-REG-1.1.1.1.3: Alphanumeric (no special characters allowed)

      • FR-REG-1.1.2: Password (mandatory).

        • FR-REG-1.1.2.1: The password must have at least one from each of the following:

          • FR-REG-1.1.2.1.1: Uppercase letter.

          • FR-REG-1.1.2.1.2: Lowercase letter.

          • FR-REG-1.1.2.1.3: Number.

          • FR-REG-1.1.2.1.4: Special character.

        • FR-REG-1.1.2.2: The password must have at least 8 characters.

      • FR-REG-1.1.3: Confirm Password (mandatory).

        • FR-REG-1.1.3.1: The input must be the same as the one in the Password field.

  • FR-REG-2: The system shall validate input data.

    • FR-REG-2.1: If any field is invalid, the system shall prevent registration.

  • FR-REG-3: The system shall check for duplicate accounts.

    • FR-REG-3.1: If an account with the same username already exists, the system shall prevent registration.

14.1.2. Login and Logout

  • FR-LOG-1: The system must allow unidentified users to log in.

    • FR-LOG-1.1: The system shall require the following information for log in:

      • FR-LOG-1.1.1: Username (mandatory).

      • FR-LOG-1.1.2: Password (mandatory).

  • FR-LOG-2: The system shall validate login credentials.

  • FR-LOG-3: The system must allow logged-in users to log out at any time.

14.1.3. User Data Management

  • FR-UPD-1: The system must allow users to access their historical data.

    • FR-UPD-1.1: The system shall display the following statistics for each user:

      • FR-UPD-1.1.1: Number of games played.

      • FR-UPD-1.1.2: Number of questions answered correctly.

      • FR-UPD-1.1.3: Number of questions answered incorrectly.

      • FR-UPD-1.1.4: Number of questions unanswered.

      • FR-UPD-1.1.5: Total time played.

      • FR-UPD-1.1.6: Minimum time spent per game.

      • FR-UPD-1.1.7: Maximum time spent per game.

      • FR-UPD-1.1.8: Average time spent per game.

      • FR-UPD-1.1.9: Minimum time spent per question.

      • FR-UPD-1.1.10: Maximum time spent per question.

      • FR-UPD-1.1.11: Average time spent per question.

      • FR-UPD-1.1.12: Total number of questions answered.

      • FR-UPD-1.1.13: Accuracy percentage (based on correct/total questions).

14.1.4. Game Session

  • FR-GAME-1: The system shall allow only authentified users to play.

    • FR-GAME-1.1: The game shall consist of 10 rounds.

      • FR-GAME-1.1.1: Each round shall include:

        • FR-GAME-1.1.1.1: A generated question from Wikidata using a template.

        • FR-GAME-1.1.1.2: A set of possible answers (one correct, at least one distractor).

        • FR-GAME-1.1.1.3: An image from Wikidata related to the question.

        • FR-GAME-1.1.1.4: A time limit of 20 seconds to answer the question.

    • FR-GAME-1.2: The system shall move to the next round when:

      • FR-GAME-1.2.1: An answer is submitted.

      • FR-GAME-1.2.2: Time runs out.

        • FR-GAME-1.2.2.1: When time runs out the question is considered incorrectly answered.

    • FR-GAME-1.3: The game shall end after all the rounds are completed.

  • FR-GAME-2: The system shall allow authentified users to play against the AI.

    • FR-GAME-2.1: The configuration would be the same as the normla game.

    • FR-GAME-2.2: At the end of the game the result of the game shall be informed to the user.

14.1.5. Hint System

  • FR-HINT-1: The system shall allow users to request hints for a question.

    • FR-HINT-1.1: The hints shall be generated using an LLM.

      • FR-HINT-1.1.1: The system shall send to the LLM:

        • FR-HINT-1.1.1.1: The message from the player.

        • FR-HINT-1.1.1.2: An additonal message explaining that it is being used as a hint provider for a quiz game.

        • FR-HINT-1.1.1.3: The question.

        • FR-HINT-1.1.1.4: The correct answer.

        • FR-HINT-1.1.1.5: The distractors.

        • FR-HINT-1.1.1.6: The previous hints given by the LLM for that question if possible.

    • FR-HINT-1.2: The system shall allow up to 3 hints per question.

    • FR-HINT-1.3: After getting a hint, there will be a cooldown of 3 seconds for asking again.

14.1.6. Custom Games

  • FR-CGAME-1: The system shall allow users to create custom game sessions.

    • FR-CGAME-1.1: The system shall allow users to customize:

      • FR-CGAME-1.1.1: Number of rounds.

        • FR-CGAME-1.1.2.1: The minimum number will be 1 round.

        • FR-CGAME-1.1.2.2: The maximum number will be 50 rounds.

        • FR-CGAME-1.1.2.3: There will be an option for infinite rounds.

          • FR-CGAME-1.1.2.3.1: In this case, the game will end when a question is answered incorrectly.

      • FR-CGAME-1.1.2: Time per question in seconds.

        • FR-CGAME-1.1.2.1: The minimum time will be 10 seconds.

        • FR-CGAME-1.1.2.2: The maximum time will be 60 seconds.

      • FR-CGAME-1.1.3: Hints per question.

        • FR-CGAME-1.1.3.1: The minimum will be 0 hints.

        • FR-CGAME-1.1.3.2: The maximum will be 5 hints.

      • FR-CGAME-1.1.3: There will be an option for AI game mode.

      • FR-CGAME-1.1.4: Question categories.

        • FR-CGAME-1.1.4.1: If no category is selected, all categories would be active.

14.1.7. Question Management

  • FR-APIQ-1: The system shall provide an API to access generated questions.

    • FR-APIQ-1.1: The API shall include endpoints to retrieve questions and answers.

    • FR-APIQ-1.2: The API shall be documented for developers.

14.1.8. User Data Access

  • FR-APIU-1: The system shall provide an API to access user data.

    • FR-APIU-1.1: The API shall include endpoints for retrieving user statistics.

    • FR-APIU-1.2: The API shall be documented for developers.