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

1.1. Context and Motivation

WIChat is a web-based question-and-answer application where users must guess the location of an image. The platform automatically generates questions based on Wikidata and allows users to receive hints through an external language model (LLM). This functionality adds a conversational component to the game, enhancing the user experience.

RTVE has contracted ChattySw to update an experimental version of the online contest previously developed by HappySw, incorporating new interactive hint functionalities and improving the gameplay experience.

1.2. Key Requirements

The system must meet the following requirements:

  • A web application accessible from any browser.

  • User registration and authentication.

  • Automatic question generation based on Wikidata.

  • The ability to obtain hints generated by a language model (LLM) via an API.

  • Validation and mitigation of incorrect responses from the language model.

  • Time control for answering each question.

  • A documented API for accessing questions and user data.

  • Automatic generation of correct and incorrect answers (distractors).

1.3. Quality Objectives

The following quality objectives will guide architectural decisions:

Objective Priority Description

Scalability

High

The system must support a growing number of users without affecting performance.

Availability

High

The application must be available at all times with minimal downtime.

Security

High

Protection of user data and validation of responses generated by the LLM.

Usability

Medium

Intuitive interface and smooth user experience.

Maintainability

Medium

Modular and well-documented code to facilitate future improvements.

1.4. Stakeholders

The following stakeholders are involved in the development and use of the system:

Role Contact Expectations

Client (RTVE)

rtve@rtve.es

Ensure that the application meets contract requirements.

Development Team (ChattySw)

devteam@chattysw.com

Implement the system according to quality objectives.

Users

Registered in the application

Access an interactive and seamless gaming experience.

2. Constraints

2.1. Technical Constraints

The following technical constraints affect the development of WIChat:

  • Web Technology: The application must be developed using modern web technologies (React.js for the frontend and Node.js/Python for the backend).

  • Database: PostgreSQL or MongoDB will be used for data storage.

  • Language Model: A language model (LLM) will be integrated through an external API.

  • Question Source: Questions must be automatically generated based on Wikidata data.

  • Response Time: Answers to questions must be recorded within a set time limit.

2.2. Organizational Constraints

The following organizational constraints affect the project:

  • Delivery Deadlines: The application must be operational before the project closure as agreed.

  • Documentation: The architecture and development must be documented following the arc42 standard.

  • Open Source: The source code must be hosted in an accessible repository for review and tracking.

2.3. Security and Privacy Constraints

To ensure user security and privacy, the following constraints are established:

  • Data Management: User data must be protected in compliance with data protection regulations.

  • Response Validation: Potential errors or "hallucinations" from the language model must be mitigated to prevent incorrect information in hints.

These constraints will define the boundaries within which WIChat will be designed and developed.

3. Context and Scope

Contents

Context and scope - as the name suggests - delimits your system (i.e. your scope) from all its communication partners (neighboring systems and users, i.e. the context of your system). It thereby specifies the external interfaces.

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

Motivation

The domain interfaces and technical interfaces to communication partners are among your system’s most critical aspects. Make sure that you completely understand them.

Form

Various options:

  • Context diagrams

  • Lists of communication partners and their interfaces.

Further Information

See Context and Scope in the arc42 documentation.

3.1. Business Context

Contents

Specification of all communication partners (users, IT-systems, …​) with explanations of domain specific inputs and outputs or interfaces. Optionally you can add domain specific formats or communication protocols.

Motivation

All stakeholders should understand which data are exchanged with the environment of the system.

Form

All kinds of diagrams that show the system as a black box and specify the domain interfaces to communication partners.

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

Business context

3.2. Technical Context

Contents

Technical interfaces (channels and transmission media) linking your system to its environment. In addition a mapping of domain specific input/output to the channels, i.e. an explanation which I/O uses which channel.

Motivation

Many stakeholders make architectural decision based on the technical interfaces between the system and its context. Especially infrastructure or hardware designers decide these technical interfaces.

Form

E.g. UML deployment diagram describing channels to neighboring systems, together with a mapping table showing the relationships between channels and input/output.

Technical context

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. Types of Decisions

4.1.1. 1. Organizational Decisions

These decisions are related to the work structure and how the team is organized.

  • Using a Kanban-style project: The decision to use a visual task management approach, Kanban, to organize work and ensure that all team members know the status of tasks and what remains to be done.

  • Using GitHub Flow as a workflow: The decision to adopt a GitHub Flow-based workflow, allowing all team members to collaborate easily through Pull Requests and ensuring that all code is reviewed before being merged into the main branch.

4.1.2. 2. Technical Decisions

These decisions are related to how the project is built and the tools used.

  • Using a starter template: The decision to begin with a basic but functional project, allowing for a quick start with a pre-configured structure that works, avoiding the need to build everything from scratch.

  • Starting the project from scratch: Although a starter template can be used, the decision is to create a new project from scratch. This helps the team become more familiar with the code and project structure. Additionally, the previous project can be used as a reference to solve problems or improve the design without relying on it directly.

4.1.3. 3. Quality and Maintenance Decisions

These decisions are about ensuring that the project is high quality and easy to maintain.

  • Using GitHub Flow and Pull Requests: Through Pull Requests, we ensure that every code change is reviewed by the team before integration, maintaining code quality and minimizing errors in the main branch.

5. Building Block View

5.1. Whitebox Overall System

5.1.1. Overview Diagram

BuildingBlockViewOverviewDiagram

5.1.2. Motivation

WIChat is a real-time messaging system that allows users to communicate via text, images, and other media. The system’s architecture is modular, facilitating scalability and integration with different technologies.

5.2. Contained Building Blocks

Name Responsibility

Frontend

Web and mobile user interface.

Backend API

Handles authentication, messaging, and business logic.

Database

Stores users, conversations, and messages.

Wikidata

Structured data source to enhance user experience.

Language Model for Hints

Provides intelligent suggestions and autocomplete for messages.

5.3. Important Interfaces

Database Access: Interface between the API and the database.

Wikidata API: Accesses structured and relevant data.

Language Model: Interface with the AI system for text suggestions.

5.4. System Components

5.4.1. Frontend

Purpose / Responsibility

Provide an interactive interface for the user.

Send and receive real-time messages.

Manage sessions and contacts.

Interfaces

Graphical user interface.

Connection to the API for authentication and data retrieval.

Use of the language model for message suggestions.

5.4.2. Backend API

Purpose / Responsibility

Manage user authentication and authorization.

Provide access to message and user data.

Integrate with other services (Wikidata, Language Model).

Interfaces

API for communication with the frontend.

Connection to the database for data storage.

Access to Wikidata to enrich the user experience.

Integration with the language model for message assistance.

5.4.3. Database

Purpose / Responsibility

Store information about users, messages, and conversations.

5.4.4. Wikidata

Purpose / Responsibility

Provide structured data to enhance the user experience in the chat.

Interfaces

Wikidata API to obtain relevant real-time information.

5.4.5. Language Model for Hints

Purpose / Responsibility

Offer intelligent suggestions and message autocomplete.

Interfaces

AI API for text analysis and response generation.

5.5. Level 2

level 2

5.5.1. White Box Gateway Service

Module Functionality

WebApp

Provides the user interface and manages user interaction.

Gateway Service

Acts as an intermediary between the WebApp and other system services.

Users Manager

Handles user management, including authentication and profiles.

Question Manager

Processes and manages user questions.

Wikidata

Structured data source used to answer questions.

5.6. Component Description

5.6.1. WebApp

Purpose / Responsibility:

Provide an interactive interface for users.

Allow access to system functionalities.

Send and receive requests through the Gateway Service.

Interfaces:

Connection with the Gateway Service to manage users and questions.

5.6.2. Gateway Service

Purpose / Responsibility:

Centralize communication between the WebApp and other services.

Manage request and response routing.

Interfaces:

Bidirectional communication with WebApp, Users Manager, and Question Manager.

5.6.3. Users Manager

Purpose / Responsibility:

Manage users and their profiles.

Administer authentication and access permissions.

Interfaces:

Connection with Gateway Service for user validation and data retrieval.

5.6.4. Question Manager

Purpose / Responsibility:

Process user questions.

Retrieve relevant information from Wikidata.

Interfaces:

Communication with Gateway Service and Wikidata for information queries.

5.6.5. Wikidata

Purpose / Responsibility:

Provide structured data to enrich responses to user questions.

Interfaces:

Query API used by the Question Manager.

5.7. Level 3

5.7.1. White Box Message Handling (Backend API)

Component Description

Message Storage

Manages message persistence in the database, ensuring integrity and availability.

5.7.2. White Box Wikidata Integration

Component Description

Data Retrieval

Queries relevant data from Wikidata in real time to enhance user experience.

6. Runtime View

  • At this stage, we have not yet started development, so the runtime scenarios are still undefined. Once the implementation progresses, we will document key runtime interactions, including authentication flows, data storage, and relevant communication between system components.

  • For now, the following section will be updated as we gain a clearer understanding of how different components interact in real-time.

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.

Esto es lo que estaba escrito antes:

=== <Runtime Scenario 1>

  • <insert runtime diagram or textual description of the scenario>

  • <insert description of the notable aspects of the interactions between the building block instances depicted in this diagram.>

It is possible to use a sequence diagram:

Sequence diagram

=== <Runtime Scenario 2>

=== …​

=== <Runtime Scenario n>

7. Deployment View

7.1. Infrastructure Level 1

Deployment View

In addition to what is shown in the diagram, we will also use arc42 for documentation.

Motivation

Initially, the application is deployed using Docker in developers systems, depending on resource availability. This way, each developer will have a local deployment environment for testing.

Quality and/or Performance Features

  • The system is designed with microservices, each running in its own container for better scalability and fault tolerance.

  • A database service will be used for structured data, and a File Storage Service will handle multimedia content.

  • arc42 documentation will be managed within a dedicated Docker 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)

  • Usable Interface:

Ease of Use

A simple, predictable, and familiar interface design will be presented, ensuring that all essential elements and options of the application are easily accessible.

Intuitive

The system will provide an intuitive interface, making it easy for users to understand.

Stability

The application’s loading times will be minimized to ensure a smooth experience.

  • Immediate Feedback: The user will instantly see whether their answer was correct or not. Additionally, the game history, rankings, and generated questions will always be up to date.

8.2. Security & Protection

  • Secure Access Control: User authentication security will be enforced by verifying the correctness of the entered credentials and denying access otherwise.

8.3. Under-the-Hood

  • Persistence: Both user data and game records will be stored to ensure their integrity and availability.

  • Maintainability: The code is written clearly and legibly, following a modular approach to facilitate maintenance when fixing bugs or adding improvements.

  • Extensibility: The application is built in a way that allows new functionalities to be added easily in the future without significantly affecting existing components.

8.4. Development

  • Implementation: The application will be developed using JavaScript. The front-end will be built with React, while Node.js and microservices architecture will be used for the back-end. MongoDB will be used for managing the NoSQL database.

  • Testing: Various tests will be conducted to ensure a high-quality product.

8.5. Architectural Style

  • Layers: A three-layer architecture will be implemented to ensure better organization and modularity:

Presentation

Responsible for operating and generating the graphical interface displayed to the user.

Business Logic

Where all the necessary logic for the correct operation of the application will be executed.

Persistence

Used to store and retrieve various data needed for both the player and the question-and-answer game system.

8.6. Concept Map

Cross cutting Concepts

9. Architecture decisions

  • These decisions are not final and may change as the project evolves. They represent our current approach based on the available information and team expertise, but adjustments might be necessary as we gain more experience and face new challenges.

Decision Reasons Disagvantanges

JavaScript

We have decided to develop the application using JavaScript because, in addition to having some prior knowledge, working with the provided template encourages us to do so, avoiding unnecessary complexity in the initial development phase.

It is a complex language that can cause us problems while other simpler languages could make our work easier.

React.js

It is the most popular JavaScript framework, with extensive documentation available.

None of us in the team have worked with it before, so we will all need to learn how to use it.

MongoDB

As a non-relational database, it offers ease of use. Additionally, it is widely adopted by major telecommunications companies.

Non-relational databases are the ones with which we have the least experience.
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

The WIChat system prioritizes five critical quality attributes to ensure success:

  1. Usability:

    • Goal: An intuitive interface that allows users to play and access hints easily.

  2. Maintainability:

    • Goal: Modular and well-documented code to facilitate updates.

  3. Performance:

    • Goal: Low latency in critical operations:

    • Question generation.

    • LLM response.

  4. Security:

    • Goal: Data protection and resistance to attacks.

  5. Functionality:

    • Goal: Reliably meeting key business requirements:

    • Automatic question/answer generation from Wikidata.

    • Conversational hints with hallucination mitigation (RAG).

These requirements guide technical decisions and ensure the system meets both RTVE’s expectations and the end-user experience.

10.1. Quality Tree

Quality Attribute Goal/Description Associated Scenarios

Usability

Intuitive interface for gameplay and hint access

[SC-4]

Maintainability

Modular and well-documented code for updates

[SC-5]

Performance

Low latency in question generation and LLM responses

[SC-2]

Security

Data protection and resistance to attacks

[SC-3]

Functionality

Reliable question/answer generation with hallucination mitigation (RAG)

[SC-1]

10.2. Quality Scenarios

Scenario Stimulus/Source Environment Artifact Expected Response

SC-1: Accurate question generation

System needs a new question

Normal load

Wikidata Service

Question generated with verified data (no hallucinations)

SC-2: Performance under load

500 users start a game simultaneously

Peak demand

Question API

Low generation latency

SC-3: User data protection

Unauthorized attempt to access sensitive data

Brute force attack

Database

Encryption of sensitive data

SC-4: Intuitive hint access

New user tries to get a hint

First use

User interface

Hint accessible

SC-5: Maintainability of topics

Developer adds "European History" topic

Development environment

Codebase

Topic integrated quickly

11. Risks and Technical Debt

11.1. Technical Risks

  1. Inadequate Version Control Management

    • Possible Issues

      • GitHub conflicts due to multiple team members collaborating.

      • Risk of code loss or overwriting.

    • Preventive Measure

      • Define a clear Git workflow with mandatory Pull Requests.

  2. Tight Deadlines and Lack of Experience

    • Possible Issues

      • Inability to complete planned tasks due to other courses or poor time estimation.

      • Difficulties in implementing advanced features due to lack of experience in JavaScript.

      • Increased number of errors due to limited proficiency in the language.

    • Preventive Measure

      • Better task organization and development time estimation.

      • Self-learning of the language to improve proficiency.

  3. Documentation Deficiencies

    • Possible Issues

      • Code with few comments and insufficient technical documentation.

      • Difficulty for other team members to understand the existing code.

    • Preventive Measure

      • Maintain clear and up-to-date documentation in the GitHub repository.

  4. Lack of Automated Testing

    • Possible Issues

      • Dependence on manual testing, which is prone to errors.

      • Increased time to detect and fix bugs.

    • Preventive Measure

      • Introduce unit and functional testing using tools like Jest or Mocha.

  5. Lack of Code Standards

    • Possible Issues

      • Different programming styles within the team.

      • Difficulty in unifying code from different team members.

    • Preventive Measure

      • Define common code standards to ensure consistency and ease of collaboration.

  6. Inefficient and Repetitive Code

    • Possible Issues

      • Lack of modularity and code reuse.

      • Difficulty in project maintenance and scalability.

    • Preventive Measure

      • Apply modular programming principles and perform periodic refactoring.

  7. Suboptimal Performance

    • Possible Issues

      • Inefficient use of data structures and algorithms.

      • Potential performance issues during application execution.

    • Preventive Measure

      • Review and optimize the code once it is functional.

11.2. Technical Debt

11.2.1. There is no technical debt

Currently, there is no significant technical debt in the project. However, we will monitor the codebase to ensure that technical debt does not accumulate over time.

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

JavaScript

JavaScript is a high-level, dynamic, and event-driven programming language primarily used for web development. It is an interpreted language, prototype-based, and weakly typed, running in the browser through the JavaScript engine. It can also be used on the backend with environments like Node.js.

Frontend

JavaScript in the frontend is used to manipulate the DOM, handle events, and enhance web interactivity. It runs in the browser and works alongside HTML and CSS to create dynamic experiences. Frameworks like React make it easier to develop more structured and efficient applications.

React

React is a JavaScript library for building user interfaces efficiently and modularly. It follows a component-based approach and uses a Virtual DOM to improve performance. Developed by Facebook, it is primarily used in the frontend to create interactive and dynamic web applications.

Backend

On the backend, JavaScript is used with environments like Node.js to handle servers, databases, and business logic. It enables API creation, HTTP request management, and database connections with systems like MongoDB.

Node.js

Node.js is a JavaScript runtime environment based on Chrome’s V8 engine, designed to execute code outside the browser. It is asynchronous and event-driven, making it ideal for real-time applications and scalable servers. It uses the CommonJS module system and has npm for package and dependency management.

MongoDB

MongoDB is a NoSQL document-oriented database that stores data in BSON format (similar to JSON). It is scalable, flexible, and allows handling large amounts of data without a fixed structure. It integrates well with Node.js and is commonly used in modern web applications.