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

WIChat is an AI-powered web application for RTVE, aiming to develop an online quiz inspired by Saber y Ganar. This project will introduce a conversational AI feature that provides hints to contestants using an LLM.

This document describes the key requirements and quality goals for the project. It also identifies the stakeholders and their expectations.

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.

The WIChat system must fulfill the following essential requirements:

Further Information

See Introduction and Goals in the arc42 documentation.

  • User registration and authentication: Users must be able to create accounts and log in.

  • Image-based questions: The game will display an image, and users must identify its location.

  • AI-generated hints: Players can request hints about the image through a conversational interface powered by an external LLM.

  • Automatic content generation: Images and hints must be dynamically created using Wikidata.

  • Game scoring and rewards: Users earn points or rewards for correct answers.

  • API access: External systems should be able to retrieve quiz data and user performance information through an API.

  • Time-limited responses: Each question must be answered within a given timeframe.

  • Leaderboard: Users can view their ranking and compare their performance with others.

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 Motivation Concrete Scenario

Usability

The game must provide an intuitive and engaging user experience

The UI should be clear and easy to navigate, with a conversational AI that is easy to interact with

Performance

AI-generated hints should be delivered quickly to avoid disrupting gameplay

Hints generated via the LLM should have a response time of less than 3 seconds

Security

Protecting user data and preventing AI model abuse is critical

User interactions should be encrypted and respect user privacy and data protection laws.

AI Adaptability

The LLM should provide relevant and contextually appropriate hints

The AI must be fine-tuned to ensure accurate and helpful responses based on Wikidata sources

Scalability

The system must handle multiple simultaneous users without slowdowns

The game should support multiple concurrent players with minimal latency

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

Users

General public, quiz players

Engaging and interactive quiz experience with AI-generated hints

Development Team

Carballo Pérez, Andrés (UO287983@uniovi.es)
García Santamarina, Sergio (UO294636@uniovi.es)
Gutiérrez García, Miguel (UO295650@uniovi.es)
Mahía Loredo, Adrián (UO289390@uniovi.es)
Pérez Cuervo, Bruno (UO295445@uniovi.es)

Well-documented architecture and a system that is easy to maintain and extend

Professors

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

A project demonstrating LLM integration and structured team collaboration

RTVE

https://www.rtve.es

An engaging online game that aligns with their brand and audience expectations

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.

Restriction Description

Git/GitHub

Git will be used as the version control system and GitHub as the platform to store the code, allowing for efficient code management, project change tracking, and facilitating collaboration among team members. Additionally, a lack of proficiency with these tools could lead to lower efficiency and greater challenges.

Docker

The application will be deployed using Docker, allowing for a more consistent and flexible deployment, which facilitates the management of scalability and dependencies.

AsciiDoc

All documentation associated with the project must be developed using AsciiDoc, a lightweight and structured format.

Time

The project must be developed, tested, and completed according to the established deadlines, with organization and effective use of time by the team, including meetings and planning, being key.

Web Accessible

The application must be deployed and accessible via web, allowing users to interact with the system from any device with an internet connection, without the need for local installations.

Wikidata

The system must obtain data to generate questions and images from Wikidata, ensuring a structured, updated, and verifiable source of information.

LLM

A language model will be integrated to generate hints for each question through interaction with the application.

3. Contexto y Alcance

Contenido

El ámbito y contexto del sistema, como su nombre lo indica, delimita el sistema (es decir, su ámbito) de todos sus interlocutores (sistemas y usuarios vecinos, es decir, el contexto del sistema). De este modo, especifica las interfaces externas.

Si es necesario, diferencie el contexto empresarial (entradas y salidas específicas del dominio) del contexto técnico (canales, protocolos, hardware)..

Motivación

Las interfaces de dominio y las interfaces técnicas con los socios de comunicación se encuentran entre los aspectos más críticos de su sistema. Asegúrese de comprenderlas por completo.

Formato

Varias opciones:

  • Varios diagramas de contexto

  • Listas de socios de comunicación y sus interfaces.

Más información

Vea Context and Scope en la documentación arc42.

3.1. Contexto de Negocio

Contexto de negocio
Elemento Descripción

Usuario

El concursante que interactúa con la aplicación y le puede preguntar al chatbot integrado, y responder a las preguntas mostradas.

WIChat

Aplicación web principal donde se desarrolla la lógica del juego.

WIChat

Aplicación web principal donde se desarrolla la lógica del juego.

Wikidata

Fuente de donde se extraeran las preguntas y las respuestas, las cuales no estarán visibles hasta que el usuario interactue con la aplicación tras responder.

LLM_API

API que integra un LLM que se utilizará para generar pistas de forma dinámica y que seguira un diálogo conversacional que ayudará al concursante a responder las preguntas, pero que nunca le dirán implícitamente la respuesta.

Base de Datos

Sistema de almacenamiento que guarda información relevante sobre el usuario y anteriores partidas.
Contenido

Especificación de todos los interlocutores (usuarios, sistemas informáticos, etc.) con explicaciones de las entradas y salidas o interfaces específicas del dominio. Opcionalmente, puede añadir formatos o protocolos de comunicación específicos del dominio.

Motivación

Todas las partes interesadas deben comprender qué datos se intercambian con el entorno del sistema.

Formato

Todo tipo de diagramas que muestran el sistema como una caja negra y especifican las interfaces del dominio con los socios de comunicación.

Como alternativa (o adicionalmente), puede utilizar una tabla. El título de la tabla es el nombre de su sistema, las tres columnas contienen el nombre del interlocutor, las entradas y las salidas.

3.2. Contexto Técnico

Contenido

Interfaces técnicas (canales y medios de transmisión) que juntan el sistema con su entorno. Además un mapeo del dominio especifico de entrada/salida a los canales, es decir una explicación de qué entrada salida usa cada canal.

Motivación

Muchos stakeholders toman decisiones arquitectónicas basadas en las interfaces técnicas entre el sistema y su contexto. En especial, los diseñadores de hardware o infraestructura deciden estas interfaces técnicas.

Forma

E.g. Diagrama UML de despliegue describiendo canales con los sistemas vecinos, junto a una tabla de mapeo mostrando las relaciones entre canales y la entrada/salida.

3.2.1. Diagrama de Despliegue

Diagrama de Despliegue

3.2.2. Explicación de Interfaces Técnicas

Gateway

API que hace de enlace entre las distintas partes de la aplicación.

Aplicación React

React aportará al usuario una interfaz con la que interactuar y responder a las preguntas y por medio de la cual hacer las peticiones correspondientes a la parte de backEnd de la aplicación.

Base de Datos de Usuarios

Almacena toda la información referente a los usuarios,datos,historial de partidas.

Servicio de Autenticación

Interfaz que se comunica con la base de datos de usuarios para comprobar el si el inicio de sesión es válido o no.

Servicio de Usuario

Interfaz que se comunica con la base de datos de usuarios para consultar y, o actualizar la información referente a las partidas de los mismos.

LLM_Service

Servicio que procesará las pistas de WikiData y devolverá la respuesta a la pregunta del usuario. ===== API WikiData Wikidata nos aportará todo lo referente a las preguntas, tanto la imágen, como las respuestas y la respuesta correcta, además de que nos permitirá recopilar pistas que servirán al LLM para responder.

3.2.3. Mapeo de Canales de Entrada/salida

Canal Entrada Salida

Aplicación React

Peticiones HTTP del usuario con las acciones

Respuesta a través de la interfaz.

Gateway

Peticiones REST de webapp para obtener datos de las preguntas (imágenes,respuestas), o solicitar operaciones como iniciar sesión

Respuesta con la información solicitada en cada caso.

Servicio Usuario

Datos que se quieren consultar a la base de datos

Respuesta a dicha consulta.

Servicio Autenticación

Datos de inicio de sesión del usuario

Consulta de comprobación de los datos, para ver si son erróneos o no.

LLM_Service

Prompt con la solicitud de pistas que quiere el usuario en ese momento

Pista generada por el modelo.

API Wikidata

Solicitud de las imagenes o pistas en ese momento

Respuesta sobre la imagen solicitada, ya sea en forma de pista, o bien una nueva imagen en caso de que se solicite una nueva pregunta.

Base de Datos de Usuarios

Instrucciones SQL para consultas o insercioes

Resultado de las consultas o confirmación de las inserciones.

Prometheus

Métricas de Gateway

métricas en su base de datos.

Grafana

Métricas organizadas en Prometheus

Visualización de las métricas.

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. 4.1. Technology Decisions

As part of the project’s initial planning phase, we have identified a set of technologies that we believe will be well-suited to implement the WiChat application. These technologies align with the project requirements and will guide the development process once the implementation begins.

  • JavaScript – A versatile, high-level programming language widely used for developing dynamic and interactive web applications. It allows for both client-side and server-side development, making it an ideal choice for the full-stack needs of the project.

  • React – A JavaScript library designed for building efficient user interfaces for single-page applications. React’s component-based architecture will enhance reusability and maintainability, which will be key once development begins.

  • Node.js – A runtime environment for executing JavaScript on the server side. Node.js is well-suited to handling asynchronous operations, making it a good choice for scalable network applications and managing database interactions.

  • Express.js – A lightweight web framework built on top of Node.js, planned to simplify backend development. Express will provide essential features such as routing, middleware management, and API creation, ensuring smooth backend processes during the project’s development.

  • MongoDB – A NoSQL, document-oriented database. MongoDB offers flexibility, scalability, and high availability. Its JSON-like document structure is well-suited for applications that may need to dynamically adjust the database schema as the project evolves.

  • Docker – A containerization platform that allows developers to package applications along with their dependencies, ensuring consistent execution across different environments. This will simplify deployment and enhance scalability when the system is up and running.

  • GitHub – A version control platform that will be essential for managing the project’s codebase. It will enable collaborative development, tracking of changes, and automation of workflows, particularly important for a smooth development process as the team grows.

4.2. 4.2. System Architecture

The architecture for the WiChat application is currently planned to be based on a microservices architecture, a modular approach that allows distinct services to be developed and maintained independently. This structure is chosen to provide scalability, flexibility, and ease of maintainability as the project progresses.

The system will consist of the following microservices, each designed to handle specific responsibilities:

  • User Service – This service will manage user registration, profile management, and the friend system.

  • Gateway Service – The gateway service will serve as the public-facing entry point, routing incoming requests to the appropriate microservices.

  • WebApp Service – This is the frontend web application, which will interact with the gateway service to provide essential functionalities like user authentication.

  • Auth Service – The auth service will manage user authentication processes, ensuring secure login and session handling.

These decisions are being made with the goal of setting up a solid foundation for the development, ensuring that once work begins, the system will be modular and capable of scaling as needed.

4.3. 4.3. Decisions Made to Achieve Quality Goals

Before beginning the development of the project, we identified several quality goals that will guide our design and implementation strategy. The following decisions were made to address these goals and ensure the system meets the expected standards once development begins.

Quality Goal Decision Made

Usability

The application must be designed to be intuitive and accessible for users with various backgrounds. To ensure usability, we have planned: * Conducting user feedback sessions and usability tests at the early stages of development. * Choosing an appropriate typography style and sizing to ensure legibility and user comfort.

Performance Efficiency

The system needs to be optimized to handle potential traffic surges and deliver quick responses to users. The following strategies are planned to optimize performance: * Reducing request frequency to external services (like WikiData) to avoid overloading the system.

Maintainability & Scalability

The system must be modular, easy to maintain, and scalable for future growth. To ensure long-term maintainability and scalability, we have outlined the following approaches: * Choosing a microservices architecture that allows for modular development and easy updates or additions. * Implementing key design patterns, including: Gateway Pattern – A single entry point for external requests to streamline access. Single Responsibility Principle – Ensuring each service has a focused and clear role. * Maintaining clean and documented code, following industry best practices to ensure ease of future modifications.

Security

Protecting user data and maintaining the security of the system is essential. The following security measures are being considered: * Utilizing JWT-based authentication to securely manage user sessions. * Implementing role-based access control (RBAC) to restrict access to sensitive functionalities. * Ensuring secure coding practices to protect against threats such as SQL injection and cross-site scripting (XSS). * Enabling SSL/TLS encryption to secure data during transmission between clients and servers.

Availability & Reliability

The application must be available at all times and provide a reliable experience to users. To ensure availability, the following actions are being planned: * Configuring automated monitoring and alerting systems to detect potential issues and trigger immediate resolution processes. * Designing the system with fault tolerance in mind, so that key services can continue running even in case of failures.

4.4. 4.4. Organizational Decisions

As we are in the early planning phase of the WiChat application, we have outlined the following organizational decisions to help guide the development process once the project begins:

  • Task Distribution – We plan to distribute tasks as evenly as possible among team members to ensure a balanced workload. The goal is to make sure that once a task is completed, at least 50% of the team should review it before it is considered valid. This review process will help maintain high-quality standards throughout the development cycle.

  • GitHub Issues – To manage tasks effectively, we will utilize GitHub Issues. This will allow us to create, assign, and track tasks while also providing a platform for discussing any critical decisions that may arise during development.

  • GitHub Projects – We will incorporate GitHub Projects to organize our workflow and track the overall progress of the project. This will provide a clear overview of tasks and help ensure we stay on track during development.

  • Language – The project will be developed in English. This decision ensures that both the code and documentation are accessible to all team members, as well as to future contributors.

  • External Meetings – Regular external meetings will be held to review the project’s progress and determine the next steps. These meetings will help ensure we stay aligned with the project goals and timelines.

  • Internal Communication – We will use Discord as the primary communication platform for internal discussions. This tool will facilitate real-time collaboration and help resolve issues as they arise during development. Additionally, GitHub Webhooks will be integrated to notify the team of any changes made in the repository, ensuring that everyone stays updated.

  • Documentation – For documentation purposes, we have decided to use Asciidoc. This tool was chosen because it simplifies the process of deploying and maintaining project documentation, making it easier for the team to collaborate and contribute.

5. Building Block View

5.1. Whitebox Overall System

First Level

First level
Motivation

WIChat is the general structure of a system in which a user can play the game interacting with an LLM for hints.

Contained Building Blocks

Name

Description

User

Client of the application which will interact with it.

WIChat

System developed to be used by the users.

Wikidata

Aplication to generate the questions and answers.

Empathy AI

API used for the hints.
Important Interfaces

- API communication between WIChat and external services (WikiData, Empathy AI).

5.2. Level 2 - Internal Structure of WIChat

Detailed System Overview

Second level
Contained Building Blocks
Name Description

GatewayService

Manages incoming requests and routes them to appropriate services.

UserManager

Handles authentication, user management, and ranking system.

LLMService

Connects to Empathy AI to generate hints for users.

WebApp

User-facing interface for gameplay and interactions.
Important Interfaces

  • REST API for WebApp to communicate with GatewayService.

  • Internal service-to-service communication for user authentication and data retrieval.

5.3. Level 3 - Detailed Breakdown of GatewayService

GatewayService Internal Structure

Third level
Contained Building Blocks
Name Description

UserManager

Submodule responsible for managing users and authentication.

AuthService

Handles authentication and security mechanisms.

UserService

Manages user profiles, sessions, and data.

RankingService

Stores and updates leaderboard data.

QuestionService

Retrieves and formats questions from WikiData.

MongoDB Database

Stores user information, rankings, and game data.
Important Interfaces

  • Communication between UserManager and MongoDB for user data storage.

  • Integration of QuestionService with WikiData API to fetch questions.

  • Secure authentication flows via AuthService.

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

Question Generation Diagram

6.2. Question Generation

Question Generation Diagram

6.3. Clue Generation

Clue Generation Diagram

6.4. Game

Clue Generation Diagram

6.5. Show User Info

Clue Generation Diagram

7. Deployment View

Content

The deployment view describes:

  1. Technical infrastructure used to execute your system, including geographical locations, environments, computers, processors, channels, and network topologies, as well as other infrastructure elements.

  2. Mapping of (software) building blocks to these infrastructure elements.

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

Especially document a deployment view if your software is executed as a 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 require.

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 a 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 (using nested diagrams if necessary). * When your (hardware) stakeholders prefer other kinds of diagrams rather than a deployment diagram, let them use any diagram 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

The following overview diagram shows the overall deployment of the Quiz Web Application. It illustrates how the system is distributed within an Azure Virtual Machine using Docker containers, and how the individual services interact with each other as well as with external services.

Motivation

The infrastructure has been designed to support a distributed system where each microservice is encapsulated in its own Docker container. This approach facilitates scalability, ease of deployment, and fault isolation. The use of an Azure VM provides a robust hosting environment, while external integrations (as with Wikidata) enrich the application’s functionality.

Mapping of Building Blocks to Infrastructure

Software components are each deployed in their own Docker container within Azure. The GatewayService orchestrates communication among these services, while persistent data is managed by a MongoDB database. The QuestionService also interacts with the external Wikidata service to retrieve dynamic content for the quiz.

7.2. Infrastructure Level 2

Deployment Diagram for Quiz Web Application

7.2.1. Azure VM and Docker Containers

Within Azure, the following Docker containers are deployed:

  • WebApp: Hosts the Quiz Application front-end, which is accessed via a Web Browser by the end user.

  • GatewayService: Acts as the central API gateway, routing user requests from the WebApp to the appropriate back-end services.

  • AuthService: Manages user authentication and connects to the database for credential verification.

  • UserService: Handles user management functions, including registration, profile updates, and statistics.

  • LLMService: Processes natural language queries and interacts with the database to store and retrieve processed data.

  • QuestionService: Generates quiz questions and, in addition to accessing the internal MongoDB, retrieves external data from Wikidata.

  • MongoDB (Database): Provides persistence for user data and other application data.

Communication between these containers is managed internally within Azure, ensuring secure and efficient data transfer.

7.2.2. External Services

  • Wikidata: The QuestionService accesses Wikidata to fetch additional data for quiz questions.

8. Cross-cutting Concepts

8.1. Domain Concepts

The WIChat system is built around the concept of an interactive question-and-answer game where users receive hints to guess the correct answer. The system integrates data from WikiData and utilizes a Large Language Model (LLM) to generate dynamic hints.

Key domain concepts include:

Users: Participants interacting with WIChat.

Questions & Answers: Content dynamically generated from WikiData.

Hints: AI-generated assistance to guide users.

Ranking System: Scores and leaderboards to enhance engagement.

8.2. User Experience (UX) Concepts

User experience is a fundamental aspect of WIChat, ensuring seamless interaction and intuitive design.

Minimalist UI Design: A clean and distraction-free interface.

Real-time Feedback: Immediate responses to user input.

Gamification Elements: Leaderboards and achievements to boost user engagement.

8.3. Security and Safety Concepts

Security is a critical component of WIChat, ensuring safe interactions and data integrity.

Authentication and Authorization: User authentication through secure protocols.

Input Validation: Preventing injection attacks and ensuring data integrity.

8.4. Architecture and Design Patterns

WIChat follows established software design principles to ensure scalability and maintainability.

Microservices Architecture: Decoupled services to improve scalability.

MVC Pattern: Structuring the web application using Model-View-Controller.

8.5. "Under-the-hood" - Technical Implementation

Backend: Implemented using Node.js with Express.

Frontend: Built with React for a dynamic user experience.

Database: MongoDB as the primary data store.

LLM Integration: Empathy AI used for hint generation.

External Data Source: WikiData for retrieving question-related information.

8.6. Development Concepts

Version Control: Git and GitHub for source code management.

Continuous Integration/Deployment (CI/CD): Automated testing and deployment pipelines.

Code Reviews: Peer reviews to maintain code quality.

8.7. Operational Concepts

Logging & Monitoring: Centralized logging and performance monitoring tools.

Error Handling: Graceful degradation strategies for unexpected failures.

9. Architecture Decisions

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

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

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.

11.1. Risks

Risk Description

Familiarity with technologies

Many of the base technologies used by the project, such as docker, asciidoc or react, are new to the team. The unfamiliarity, specially at the begginging, can cause a slow development and bad decisions.

Implementation

Team members mistakes such as the incorrect/unefficient implementation of a solution can cause big errors. Finding or fixing this errors takes time, which is a very limited reosurce in this project.

Time

This project must be submmited within the agreed dates, and any decision taken to meet this deadlines can cause very different problems. These decisions include deleting functionalities, lack of testing, bad coding or insufficient documentation(including both the GitHub and the source code).

Teamwork

The methodology used and the participation, communication and commitment of the team are cruzial for the succes of this project.

Design

A bad desing decision at the beggining of the project can cause a more difficult development, with more complications when updating or scalating the project, specially in a an application of this size and complexity.

Wikidata

Every aspect related to Wikidata: lack of knowledge wiht the platform, incorrect use, possible unavailability of the platform…​

11.2. Technical Debt

Technical Debt Description

Documentation

The lack of proper documentation can make the project difficult to mantain or upgrade in the future, as it can increase the difficulty of finding mistakes.

Quality code

Prioritizing time over quality when coding can decrease the efficiency of the project. Unefficient methods and repetitive structures should be avoided.

Test-coverage

A bad test-coverage can cause long-term problems, as the project could keep developing with udentified mistakes.

Obsolote technologies

The use of obsolete or unsupported technologies such as frameworks or libraries can lead to reducted performance or security issues.

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

WIChat

The application providing an interactive Q&A experience.

User

A person interacting with WIChat.

Question

A query generated dynamically using WikiData.

Answer

The correct response to a question in the game.

Hint

AI-generated clues to help users guess the correct answer.

Empathy AI

The LLM service used to generate contextual hints.

WikiData

The external knowledge base used to generate questions.

Ranking System

A system tracking user scores and leaderboards.

Gateway Service

The main entry point handling API requests and routing.

User Manager

A component handling authentication and user data management.

AuthService

A service responsible for user authentication and security.

UserService

A service managing user-related operations.

RankingService

A service that tracks and updates user scores.

LLMService

A service that connects to Empathy AI for hint generation.

WebApp

The frontend interface used by players to interact with WIChat.

MongoDB

The database system used to store user and game-related data.

Docker

The containerization platform used for deployment and scalability.

JavaScript

The primary programming language used for both frontend and backend development.

React

The JavaScript library used to build the WIChat frontend.

Express

The web framework for Node.js used to build the WIChat backend.

Node.js

The runtime environment for executing JavaScript code server-side.

CI/CD

Continuous Integration and Deployment processes for automation and code deployment.