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

Content

The system’s scope and context, as the name suggests, define the system’s boundaries (i.e., its scope) from all its stakeholders (neighboring systems and users, i.e., the system’s context). This specifies the external interfaces.

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

Motivation

Domain interfaces and technical interfaces with communication partners are among the most critical aspects of your system. Ensure you fully understand them.

Format

Various options:

  • Multiple context diagrams

  • Lists of communication partners and their interfaces

More Information

See Context and Scope in the arc42 documentation.

3.1. Business Context

Business Context
Element Description

User

The contestant who interacts with the application, can ask the integrated chatbot, and answer the displayed questions.

WIChat

Main web application where the game logic takes place.

Wikidata

Source from which the questions and answers will be extracted.

LLM_API

API integrating an LLM that will be used to dynamically generate hints and follow a conversational dialogue to help the contestant answer the questions without explicitly giving away the answer.

Database

Storage system that keeps relevant user information and past game sessions.
Content

Specification of all stakeholders (users, IT systems, etc.) with explanations of domain-specific inputs, outputs, or interfaces. Optionally, you may add specific domain communication formats or protocols.

Motivation

All stakeholders must understand what data is exchanged with the system’s environment.

Format

Any type of diagram showing the system as a black box and specifying domain interfaces with communication partners.

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

3.2. Technical Context

Content

Technical interfaces (channels and transmission media) connecting the system with its environment. Additionally, a mapping of domain-specific input/output to the channels, explaining which input/output uses each channel.

Motivation

Many stakeholders make architectural decisions based on technical interfaces between the system and its context. Hardware or infrastructure designers, in particular, decide on these technical interfaces.

Format

For example, a UML deployment diagram describing channels with neighboring systems, alongside a mapping table showing the relationships between channels and input/output.

3.2.1. Deployment Diagram

Deployment Diagram

3.2.2. Technical Interface Explanation

Gateway

API that links the different parts of the application.

React Application

React provides the user with an interface to interact with, answer questions, and make requests to the backend.

User Database

Stores all information related to users, data, and game session history.

Authentication Service

Interface that communicates with the user database to verify whether a login attempt is valid.

User Service

Interface that communicates with the user database to query or update game-related information.

LLM Service

Service that processes hints using Gemini AI and returns responses to the user’s questions via prompt engineering on the code, so it only answers game-related questions.

Question Service

Service that processes information from Wikidata to generate questions and possible answers.

WikiData API

WikiData provides all question-related content, including images, answers, and the correct response.

Gemini AI

The LLM we are using for hints.

3.2.3. Input/Output Channel Mapping

Channel Input Output

React Application

HTTP requests from the user with actions

Response through the interface.

Gateway

REST requests from the web app to obtain question data (images, answers) or perform operations like login

Response with the requested information in each case.

User Service

Data queries to the database

Response to the query.

Authentication Service

User login data

Data verification query to check if the credentials are correct.

LLM_Service

Prompt with the hints requested by the user

Hint generated by the model.

WikiData API

Request for question information

Response with the requested information.

Question Service

A request from the game when it needs a question

Question and answers generated using the information retrieved from Wikidata API.

User Database

SQL instructions for queries or insertions

Query results or confirmation of insertions.

Prometheus

Gateway metrics

Metrics stored in its database.

Grafana

Metrics organized in Prometheus

Visualization of metrics.

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.

Gemini AI

API used for the hints.
Important Interfaces

- API communication between WIChat and external services (WikiData, Gemini 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 Gemini AI to generate hints for users.

QuestionService

Communicates with WikiData to retrieve questions and answers.

Wikidata

External service for retrieving data to compose questions and answers.

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 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: 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: Gemini 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

The Architectural Decision Records (ADRs) have been incorporated into the Wiki section of our GitHub page. The corresponding links are provided below:

Contents

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

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

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

Motivation

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

Form

Various options:

  • ADR (Documenting Architecture Decisions) for every important decision

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

  • more detailed in form of separate sections per decision

Further Information

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

10. Quality Requirements

Content

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

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

Motivation

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

Further Information

See Quality Requirements in the arc42 documentation.

10.1. Quality Tree

Quality Tree"

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.

10.2.1. Usage Scenarios

Quality Goal Motivation Usage Scenario Priority

Usability

The application must be intuitive and easy to navigate, especially for new users.

A new user can register, understand the rules, and start a quiz without external guidance.

High

Interactivity

To engage users with real-time feedback during the quiz.

Upon selecting an answer, the system immediately displays whether the answer is correct and then seamlessly transitions to the next question.

High

Availability

The app must be accessible at any time to ensure users can play the quiz whenever desired.

The system maintains enabled most of the time.

High

Scalability

The system should accommodate a growing number of concurrent users without performance degradation.

The application supports multiple concurrent users .

Medium

Performance

To ensure a smooth and responsive quiz experience.

When a user submits an answer, the system processes the response and updates the UI as quickly as possible.

Medium

Reliability

To deliver consistent and accurate quiz results.

The system accurately records user answers, scores, and game statistics in every quiz session.

High

Testability

The design should allow for efficient automated testing.

Developers can run unit and integration tests to verify quiz logic and API endpoints with minimal configuration.

Medium

10.2.2. Change Scenarios

Change Scenario Motivation Expected Response Priority

Adding New Quiz Categories

To expand content and keep the quiz engaging.

New categories can be integrated into the system without impacting existing functionality.

Medium

Enhancing Chat Assistance

To improve user support by leveraging upgrades in the Gemini LLM.

The chat module can be updated or replaced with enhanced capabilities without affecting core quiz functionality.

Medium

Updating External Data Sources

To incorporate more diverse or current geographical data.

The dedicated QuestionService can be extended to fetch data from additional external APIs or sources with minimal refactoring.

Medium

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.

Gemini AI

The LLM service used to generate contextual hints.

WikiData

The external knowledge base used to generate questions.

Gateway Service

The main entry point handling API requests and routing.

User Manager

A component handling authentication, user data management and also tracks user scores and leaderboard.

AuthService

A service responsible for user authentication and security.

UserService

A service managing user-related operations.

LLMService

A service that connects to Gemini 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.