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

This project aims to develop an interactive web application, where users are given an image of a place and a series of options to try and guess where this place might be. The key innovation of the project relies on the integration of a Large Language Model (LLM), allowing users to interact with an AI assistant to request hints about the location. This mechanic enhances the gameplay by offering contextual clues, improving accessibility, and creating a more engaging user experience.

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

1.1. Requirements Overview

The application must meet the following functional and non-functional requirements.

Functional Requirements:

  • Users must be able to access the application through a web interface.

  • Users must be able to create an account and log in.

  • System must be able of displaying an image and options.

  • Users must be able to communicate with an LLM for hints about their location.

  • System must set a time limit to answer the given question.

  • The application must allow users to submit their guess.

  • Users must be able to review their past games.

  • The system must provide APIs for managing users and game data.

Contents

Short description of the functional requirements, driving forces, extract (or abstract) of requirements. Link to (hopefully existing) requirements documents (with version number and information where to find it).

Motivation

From the point of view of the end users a system is created or modified to improve support of a business activity and/or improve the quality.

Form

Short textual description, probably in tabular use-case format. If requirements documents exist this overview should refer to these documents.

Keep these excerpts as short as possible. Balance readability of this document with potential redundancy w.r.t to requirements documents.

Further Information

See Introduction and Goals in the arc42 documentation.

1.2. Quality Goals

Goal Description

Usability

The application must be intuitive and allow seamless navigation and interaction.

Performance

The system should respond promptly to user actions, ensuring smooth gameplay.

Security

User authentication and data storage must be handled securely.

Scalability

The architecture must support a growing number of users without performance degradation.

Accessibility

The application must be accessible to users with different needs, including colorblind-friendly design and screen reader compatibility.
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

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

(Team Member) Ignacio

https://github.com/nack-fs

To create a web application that provides value to stakeholders and learn in the development process.

(Team Member) José

https://github.com/josemzuvi

To create a web application that provides value to stakeholders and learn in the development process.

(Team Member) Leonardo

https://github.com/UnioviLCM27

To create a web application that provides value to stakeholders and learn in the development process.

(Team Member) Daniel

https://github.com/danigpt

To create a web application that provides value to stakeholders and learn in the development process.

(Team Member) Miguel

https://github.com/MigFeH

To create a web application that provides value to stakeholders and learn in the development process.

(Teacher) Diego Martín

https://github.com/DiegoMfer

Demonstrated understanding of web development principles through a functional, well-coded application that meets project requirements and learning objectives.

(Teacher) Emilio Labra

https://github.com/labra

Demonstrated understanding of web development principles through a functional, well-coded application that meets project requirements and learning objectives.

Future Course Students

…​

To have the project as a reference or start point to their own project.

2. Architecture Constraints

The application must be developed according to some constraints that were defined by the client. These constraints are meant to be the cornerstones of our project as they are mandatory and provide a baseline to work on. The following tables will define the constraints.

Technical constraints

Constraint

Description

Webbapp accesibility

The application must be accesible throgh a browser

Wikidata

The validity of questions and the questions themselves must be obtained through their Api

Github

It is imperative that we use Github for the recording of all of our work

Registry

It is obligatory that the program saves and stores data on the different users through a profile

Use of LLM model

We are to build a chatbot for the practice, wich means utilizing an LLM

Organizational constraints

Constraint

Description

Meetings

The team is due to an obligatory meeting per week at the time of Software Architecture class

Deliveries

There are three separate times where the project will be presented and those times are set.

Github

The use of Issues and Pull Requests for the proyects organization is highly sought to the point of necesity

Conventional constraints

Constraint

Description

Documentation in Arc42

The documentation must follow the Arc42 template

Language

It was agreed beforehand that english would be the language chosen for the proyect

Github

As the platform we work on we are obligated to learn Githubs conventions

Wireframes

wireframe XXX
Figure 1. XXX Wireframe

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.

The following table describes the business context, outlining the key actors interacting with the system and their relationships.

Actor Type Description Interaction with the System

Players

External

Users who access the application to play the game.

Interact with the web interface, receive random locations, request hints from the LLM, and submit guesses.

LLM Provider

External

API service providing AI-generated hints for players.

Receives user queries and returns contextual hints about the player’s location.

Web Application

Internal

The frontend React-based web application.

Displays the game interface, processes user interactions, and communicates with backend services.

Gateway Service

Internal

API gateway handling requests between the frontend and backend services.

Routes user requests, manages authentication, and forwards LLM-related queries.

Authentication Service

Internal

Manages user authentication and access control.

Handles user login, registration, and session management.

User Service

Internal

Manages user-related data, including game history and scores.

Stores and retrieves user data, including past game records.

Database

Internal

MongoDB instance storing user and game data.

Stores user accounts, game sessions, and interaction logs.

Deployment Platform

External

Cloud-based hosting service (e.g., AWS, Azure, or DigitalOcean).

Hosts the web application, backend services, and database.

3.2. Technical Context

Contents

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

Motivation

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

Form

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

Diagram or Table

3.2 Technical Context

3.2.1. Explanation of technical interfaces 📃

The application follows an MVC (Model-View-Controller) architectural pattern using Node.js and MongoDB, with the following components:

Agent User (External User)

  • The user interacts with the Web App, which serves as the frontend interface.

Web App (View Layer - Frontend)

  • Sends requests to and receives responses from the Backend (Controller Layer).

  • Acts as a bridge between the external user and the backend services.

Backend (Controller Layer - Node.js API)

  • Central hub that manages communication between different components.

  • Handles authentication, user management, and interaction with external components.

  • Routes requests and calls appropriate services in the Service Layer.

Service Layer (Business Logic)

  • Contains core business logic.

  • Processes requests received from the Controller Layer.

  • Interfaces with the Model Layer to retrieve or store data.

Model Layer (Database & Data Access Layer)

  • Uses Mongoose ORM to interact with the MongoDB database.

  • Defines schemas and handles database operations.

Technical Interfaces

  • Web App & Backend: HTTP Requests/Responses (REST API).

  • Backend & Service Layer: Internal function calls.

  • Service Layer & Model Layer: Database queries.

  • Model Layer & MongoDB: Data storage and retrieval.

<Mapping Input/Output to Channels>

Component Input Output

Web App

User Requests

UI Responses

Backend (Controller Layer)

API Calls

Processed Data

Service Layer

Business Logic Requests

Business Logic Responses

Model Layer

Database Queries

Stored/Retrieved Data

MongoDB

Queries

Stored Data

4. Solution Strategy

What follows is a short summary and explanation of the fundamental decisions and solution strategies, that shape our system’s architecture

4.1. Technology

  • Visual Studio Code as a framework due to its versatility in developing applications with different programming languages and its compatibility with Git.

  • Docker for deploying the project.

  • GitHub Pages for deploying the documentation.

4.2. High-level decomposition

Quality goal

Scenario

Solution approach

Link to Details

Usability

A new user quickly understands how to play and how to ask for basic hints.

Intuitive interface, interactive tutorial, clear design of the interface for interacting with the predefined hint system.

[Link to UI/UX Documentation]

Performance

The game loads images and predefined hints in under 1 second.

Image optimization, predefined hint caching, use of CDN for static resources.

[Link to Performance Optimization Documentation]

Hint Accuracy

Predefined hints are relevant and help players progress.

Creation of a set of well-designed and reviewed hints for each image, validation with user testing.

[Link to Hint Design Documentation]

Testability

Developers can run automated tests to verify game functionality.

Modular code design, implementation of unit and integration tests, use of testing frameworks.

[Link to Testability Documentation]

4.3. Approaches to achieve quality objectives

Quality goal

Scenario

Solution approach

Link to Details

Usability

Players on different devices enjoy a consistent experience.

Responsive CSS design, cross-browser and device testing, use of responsive UI frameworks.

[Link to Responsive Design Documentation]

Performance

The game maintains a smooth experience with multiple concurrent players.

Scalable backend with Docker and orchestration (e.g., Kubernetes), load balancing, database query optimization.

[Link to Scalability Documentation]

Hint Accuracy

Predefined hints are clear and do not generate confusion.

Careful wording of hints, usability testing with real players, feedback system to improve hints.

[Link to Hint Design Documentation]

Testability

Code changes do not introduce regressions.

Continuous integration with automated testing, adequate code coverage, test documentation.

[Link to Automated Testing Documentation]

4.4. Relevant organizational decisions

Currently, we have been meeting once a week, although this may change in the future depending on the team’s needs to address different topics during development.

In most meetings, if not all, all group members participate, and we discuss opinions on different designs and implementations of the application.

We also have a WhatsApp group as a fast messaging channel.

5. Building Block View

Content

The building block view shows the static decomposition of the system into building blocks (modules, components, subsystems, classes, interfaces, packages, libraries, frameworks, layers, partitions, tiers, functions, macros, operations, data structures, …​) as well as their dependencies (relationships, associations, …​)

This view is mandatory for every architecture documentation. In analogy to a house this is the floor plan.

Motivation

Maintain an overview of your source code by making its structure understandable through abstraction.

This allows you to communicate with your stakeholder on an abstract level without disclosing implementation details.

Form

The building block view is a hierarchical collection of black boxes and white boxes (see figure below) and their descriptions.

Hierarchy of building blocks

Level 1 is the white box description of the overall system together with black box descriptions of all contained building blocks.

Level 2 zooms into some building blocks of level 1. Thus it contains the white box description of selected building blocks of level 1, together with black box descriptions of their internal building blocks.

Level 3 zooms into selected building blocks of level 2, and so on.

Further Information

See Building Block View in the arc42 documentation.

5.1. Whitebox Overall System

Here you describe the decomposition of the overall system using the following white box template. It contains

  • an overview diagram

  • a motivation for the decomposition

  • black box descriptions of the contained building blocks. For these we offer you alternatives:

    • use one table for a short and pragmatic overview of all contained building blocks and their interfaces

    • use a list of black box descriptions of the building blocks according to the black box template (see below). Depending on your choice of tool this list could be sub-chapters (in text files), sub-pages (in a Wiki) or nested elements (in a modeling tool).

  • (optional:) important interfaces, that are not explained in the black box templates of a building block, but are very important for understanding the white box. Since there are so many ways to specify interfaces why do not provide a specific template for them. In the worst case you have to specify and describe syntax, semantics, protocols, error handling, restrictions, versions, qualities, necessary compatibilities and many things more. In the best case you will get away with examples or simple signatures.

5.1 Whitebox Overall System
Motivation

This sketch represents the interactions within the Wichat application. It outlines the components of the system and how they communicate, focusing on the user’s experience with the application and its core logic powered by an LLM (Large Language Model).

Contained Building Blocks

  • User: The authenticated individual interacting with the application. They play the game through the system, and their data is stored in the database.

  • Wichat Application (Domain): The main system that drives the game logic. It handles the flow of the game, including interactions between the user and the system, and manages the rules and responses generated by the LLM.

  • LLM (Large Language Model): This external component generates answers and images based on the user’s requests during the game. It processes inputs from the Wichat application to provide appropriate responses.

Important Interfaces

  • User Interaction Interface: The web client through which the user plays the game, allowing them to send requests for new rounds.

  • LLM Communication Interface: This interface handles requests from the Wichat application to the LLM, sending prompts and receiving generated content like answers and images in return.

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. <Runtime Scenario 1 : Login>

LoginDiagram

6.2. <Runtime Scenario 2 SingUp>

SignInDiagram

6.3. <Runtime Scenario 3 Game cycle>

GameCycleDiagram

.

7. Deployment View

Content

The deployment view describes:

  1. technical infrastructure used to execute your system, with infrastructure elements like geographical locations, environments, computers, processors, channels and net topologies as well as other infrastructure elements and

  2. mapping of (software) building blocks to that infrastructure elements.

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

Especially document a deployment view if your software is executed as distributed system with more than one computer, processor, server or container or when you design and construct your own hardware processors and chips.

From a software perspective it is sufficient to capture only those elements of an infrastructure that are needed to show a deployment of your building blocks. Hardware architects can go beyond that and describe an infrastructure to any level of detail they need to capture.

Motivation

Software does not run without hardware. This underlying infrastructure can and will influence a system and/or some cross-cutting concepts. Therefore, there is a need to know the infrastructure.

Form

Maybe a highest level deployment diagram is already contained in section 3.2. as technical context with your own infrastructure as ONE black box. In this section one can zoom into this black box using additional deployment diagrams:

  • UML offers deployment diagrams to express that view. Use it, probably with nested diagrams, when your infrastructure is more complex.

  • When your (hardware) stakeholders prefer other kinds of diagrams rather than a deployment diagram, let them use any kind that is able to show nodes and channels of the infrastructure.

Further Information

See Deployment View in the arc42 documentation.

7.1. Infrastructure Level 1

Describe (usually in a combination of diagrams, tables, and text):

  • distribution of a system to multiple locations, environments, computers, processors, .., as well as physical connections between them

  • important justifications or motivations for this deployment structure

  • quality and/or performance features of this infrastructure

  • mapping of software artifacts to elements of this infrastructure

For multiple environments or alternative deployments please copy and adapt this section of arc42 for all relevant environments.

<Overview Diagram>

Motivation

<explanation in text form>

Quality and/or Performance Features

<explanation in text form>

Mapping of Building Blocks to Infrastructure

<description of the mapping>

7.2. Infrastructure Level 2

Here you can include the internal structure of (some) infrastructure elements from level 1.

Please copy the structure from level 1 for each selected element.

7.2.1. <Infrastructure Element 1>

<diagram + explanation>

7.2.2. <Infrastructure Element 2>

<diagram + explanation>

…​

7.2.3. <Infrastructure Element n>

<diagram + explanation>

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

Concept Description

8.1.1. Hexagonal Architecture

The application follows a hexagonal architecture pattern, separating the different layers: frontend, business logic, microservices, and persistent storage.

8.1.2. Communication Between Components

Each component, such as the web app, Gateway Service, and microservices, communicates using technologies like HTTP and REST. This ensures smooth, scalable interaction.

8.1.3. Presentation Layer

web app serves as the entry point for external users, allowing interaction with the application and routing requests through the Gateway Service.

8.2. Integration with Microservices

Concept Description

8.2.1. Communication Between Microservices

Microservices communicate via REST, enabling flexible integration and handling different functionalities.

8.2.2. Scalability Through Microservices

Microservices architecture allows independent scaling of services without affecting other parts of the app.

8.3. Data Persistence and Management

Concept Description

8.3.1. Database Interaction

The Gateway Service uses JPA to interact with MySQL, ensuring efficient and secure data management.

8.3.2. Data Backup

The MySQL database should be configured for automatic backups, ensuring data integrity and recovery in case of failure.

8.4. LLM Service

Concept Description

8.4.1. LLM Service

The LLM Service is a microservice that interacts with a Large Language Model, generating text or performing language-related tasks based on user input.

8.5. Testeability

Concept Description

8.5.1. Unit Tests

Verify that each individual unit or component of the application functions correctly.

8.5.2. Integration Tests

Check the interaction between different units or components of the application.

8.5.3. Functional Tests

Verify that the application meets the specified functional requirements.

8.5.4. Security Tests

Identify vulnerabilities and ensure the protection of sensitive data.

8.6. Usability

Concept Description

8.6.1. Usability

Usability ensures products are easy and efficient to use, leading to user satisfaction. We’ll prioritize an intuitive design, clear navigation, and accessibility, with a particular focus on making our app user-friendly and requiring a low learning curve.

8.7. Maintainability & Scalability

Concept Description

8.7.1. Maintainability

Focuses on how easily software can be modified, fixed, or improved over time. Good maintainability reduces costs and effort for future changes.

8.7.2. Scalability

Addresses the ability of a system to handle increased load or growth. A scalable system can adapt to more users, data, or transactions without significant performance degradation.

9. Architecture Decisions

During the application development process, a series of decisions may change due to issues encountered during development, research on the technologies to be used, exploration of different work/organization strategies, etc.

These decisions are discussed in personal meetings and recorded in the meeting minutes, with some of the most important decisions being the following:

9.1. Main Framework

7/02/2024

Description: The main programming language for the application’s development will be JavaScript, but we are unsure if we will need to develop certain modules in another programming language.

Decision taken: Due to the need for the framework to be versatile in handling multiple possible programming languages, we have decided to use the Visual Studio Code framework.

9.2. Front-End

7/02/2024

Description: The main way for users to interact with the system and the part which will be deployer

Decision taken: The most likely candidate for its implementation is react, yet it is still up for debate.

9.3. Back-End

7/02/2024

Description: The inner workings of the application which will not be for the clients to use and see.

Decision taken: The most likely candidate for its implementation is a relational database and a Javascript framework, yet it is still up for debate.

9.4. LLM

7/02/2024

Description: The Language modules will be used for the hint generation in the application thus will be one we’ll need to choose

Decision taken: There had been no advancement in this decision.

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.1 Quality Tree

10.2. Quality Scenarios

Quality Attribute Scenario Motivation Expected Response

Performance

A user requests a hint from the LLM and expects a fast response.

Avoid delays that could affect the overall experience.

The LLM responds fast enough so the user isn’t kept waiting for it.

Security

A user attempts to access another user’s information without authorization.

Protect users' privacy and data confidentiality.

The system denies the request and logs the unauthorized access attempt.

Usability

A new user accesses the application and must start a game within reasonable time.

Ensure a low learning curve and an intuitive experience.

The user quickly finds the main options without external documentation.

Maintainability

Some collaborator is trying to edit, fix or add a new functionality to the app.

Ensure the changes can be done seamlessly without having to refactor or edit other areas of the code.

The application continues functioning correctly after the changes thanks t a division of the functionality in blocks.

Compatibility

The app is opened in different devices with varying form factors.

Ensure the game remains functional and all elements are correctly displayed.

The app adapts to the form factor of the user device without impacting the experience.

Reliability

The app has been available for a long time.

Ensure the app continues to work even after it’s dependencies have been updated allowing it to work correctly over time.

The app keeps working correctly without any apparent or changes to it.
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

Risk

Explanation

Mitigation proposed

Little knowledge of the technologies to be used

For all group members, this is the first time developing software that requires implementing an LLM

Search for knowledge on developing applications integrated with LLMs, along with the tools used for this. Consult the code and documentation of last year’s projects to observe the decisions that were made and the technologies they used for the rest of the development

Lack of time

We may face time constraints in fulfilling all the requirements for each deliverable and meeting every deadline

Try to maintain a steady and sustainable development pace. Prioritize building functional components initially, then iterate and enhance from there

Coordination and responsibility problems

It is probably the first time involvement in developing a project from scratch, including decisions on architecture, design, and implementation, introduces various challenges. Misunderstandings regarding tasks and version control management errors can result in individuals inadvertently disrupting the work of others. Additionally, the necessity to make numerous decisions and reach agreements increases the likelihood of errors, potentially consuming significant time and effort

To ensure effective collaboration and organization, follow the teachers' instructions regarding GitHub, including the use of features such as issues, pull requests, and maintain a disciplined approach to work from all team members, using a Kanban methodology integrated as a feature in GitHub

Starting off from scratch?

We’ll have to take the decision of starting our project from scratch or take another project from last year as "inspiration" or as a starting point

Why not both? Starting off from scratch can be really difficult, but if we have another project that serves as a guide or reference we’ll be more productive and focus on new functionalities (such as the LLM integration) rather than in the basis development.

Version Control Software Use

GitHub is one of the most (if not the most) popular version control tools in the market, however, some group member may be not acquainted with it, or even if we are, we still have to get to an agreement on how to work properly and consistently (unique commit format for all commits, wiki page rotation, conflict solving, etc.)

Starting slow with GitHub (making the project documentation) will help us to get used to it. Later, we’ll discuss and register decisions on the workflow when developing.

Spend more time developing than thinking

This one is pretty common, sometimes we just focus on producing huge amounts of code, often forgetting the importance of the previous phases, the ones that draw the line between a software developer and a software engineer/software architect.

Question the decisions "made on autopilot", remembering the goals we need to achieve when the application is done, and working smarter, not harder, on getting there.

12. Glossary

Term Definition

WiChat

The name of our project

Question Generator (QG)

A module of the application responsible for querying Wikidata, creating the questions and storing them

Large Language Models (LLM)

very large deep learning models that are pre-trained on vast amounts of data