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

The Yovi Project is a software development initiative carried out within the Software Architecture course (3rd year) of the Software Computer Engineering degree at the University of Oviedo. The primary objective is to develop a web-based gaming solution for the company Micrati within a single academic semester (4 months).

The game, named YOVI, is based on the classic board game Y. It features a triangular board where two players compete to connect all three sides of the triangle. The first player to successfully establish this connection wins the match.

The development team consists of the following members:

  • Juan Fernández López (uo296143)

  • Daniel López Fernández (uo289510)

  • Juan Losada Pérez (uo302850)

  • Pablo Pérez Saavedra (uo288816)

  • Mateo Rubio Zamarreño (uo300069)

Describes the relevant requirements and the driving forces that software architects and development team must consider. These include underlying business goals, essential features, quality goals, and relevant stakeholders.

1.1. Requirements Overview

  • System Architecture: The application is divided into two independent sub-systems:

    • Web Application: Built with TypeScript, providing the user interface to play different Y game variants and an external API for bots.

    • Logic Module: Built with Rust, responsible for win-condition checking and move suggestions via a web service interface.

    • Communication: Data exchange between modules is handled through JSON messages using the YEN notation.

  • Core Functionality: Implementation of the classic Y game (Human vs. CPU) with variable board sizes.

  • Deployment: The system must be fully deployed and publicly accessible via the web.

  • AI & Strategies: The computer opponent must support multiple AI strategies and difficulty levels selectable by the user.

  • User Management: Support for user registration and persistent match history (statistics, games played, win/loss ratio).

  • Bot Interaction: A documented API allowing bots to manage user data and play matches using the play method.

1.2. Quality Goals

Quality Goal Description

Performance

Ensure low latency and fast response times, particularly for AI move generation, to provide a fluid user experience.

Testability

The system must support high test coverage (unit, integration, e2e, and load tests) to guarantee reliability and facilitate maintenance.

Usability

The interface should be intuitive, aesthetic, and easy to navigate for any type of user.

Maintainability

The architecture must promote clean code and modularity, allowing for easy future updates, bug fixes, and documentation consistency.

1.3. Stakeholders

Role/Name Contact Expectations

Micrati (Client)

info@micrati.games

- A robust, integrated solution (Rust + TypeScript).
- Strict adherence to the YEN notation standard.
- A functional product that upholds the company’s quality standards.

Professors

Celia Melendi: melendicelia@uniovi.es
Jose Labra: labra@uniovi.es

- Transparency in technical decisions through ADRs.
- High software quality standards (Testing & Observability).
- Full traceability between requirements and implementation.

Development Team

Juan Fernández López - uo296143@uniovi.es

Daniel López Fernández - uo289510@uniovi.es

Juan Losada Pérez - uo302850@uniovi.es

Pablo Pérez Saavedra - uo288816@uniovi.es

Mateo Rubio Zamarreño - uo300069@uniovi.es

- A modular architecture that enables parallel development.
- Clearly defined API contracts to avoid integration conflicts.
- A stable CI/CD pipeline for automated deployment.

End Users (Players)

usuarios-yovi@micrati.es

- An attractive and fast web interface.
- Reliable persistence of game stats and user profiles.
- Challenging and fair AI opponents.

Bot Developers

api-support@micrati.es

- Exhaustive and clear API documentation (Swagger).
- Stability in JSON data formats and low API latency.

2. Architecture Constraints

Contents

Any requirement that constraints software architects in their freedom of design and implementation decisions or decision about the development process. These constraints sometimes go beyond individual systems and are valid for whole organizations and companies.

Motivation

Architects should know exactly where they are free in their design decisions and where they must adhere to constraints. Constraints must always be dealt with; they may be negotiable, though.

Form

Simple tables of constraints with explanations. If needed you can subdivide them into technical constraints, organizational and political constraints and conventions (e.g. programming or versioning guidelines, documentation or naming conventions)

Further Information

See Architecture Constraints in the arc42 documentation.

2.1. Technical Constraints

Constraint Background/Motivation

TC1

Frontend: React + TypeScript

Requirement defined by the project supervisor to ensure a scalable, component-based UI with the benefits of static typing for fewer runtime errors.

TC2

Game engine: Rust

The core engine for 'Game Y' must be implemented in Rust and accessible via API.

TC3

User service: NodeJs + Express

Backend logic for user management and game history accessed via API.

TC4

Docker

All microservices must be containerized for consistent deployment.

2.2. Organizational Constraints

Constraint Background/Motivation

OC1

Team Composition

The project is developed by a team of 5 members within the academic timeframe.

OC2

Deadlines

All project deliverables must be submitted on time according to the academic calendar.

2.3. Conventions

Constraint Background/Motivation

C1

Documentation Template: arc42

Following the arc42 structure to ensure a professional and standardized architecture description.

C2

Documentation Language: English

International standard chosen for the documentation.

C3

Development Workflow: Pull Requests

All code changes must be reviewed through Pull Requests to ensure quality and team synchronization.

C4

Collective Code Ownership

All team members are responsible for the entire codebase, regardless of who authored a specific part.

C5

Meeting Documentation

All meetings (lab or extraordinary) must be documented in the repository’s Wiki to maintain a record of decisions.

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 Diagram

  • YOVI is a web platform that allows human users and bots to play the game Y.

  • The Rust module is part of the system and is responsible for validating game states and suggesting moves using YEN notation.

  • External bots can interact with the system via a public API.

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 Diagram

  • YOVI Web Application: the module responsible for user and bot interaction. It acts as the system’s main interface, coordinating requests to internal services. It is implemented in TypeScript.

  • User service: internal service responsible for user management.

  • Game Y: a specialized service that implements all the logic of the game Y. It handles validating game states, checking for a winner, and suggesting the next move. It exposes a basic web service that receives and returns data in JSON format using YEN notation.

  • MongoDB: database used by the WebApp and internal services to store persistent information.

4. Solution Strategy

Further Information

See Solution Strategy in the arc42 documentation.

4.1. Contents

The main technologies used for the development of the project will be those already provided by the skeleton, such as, Rust and Cargo for the game engine, Node.js and Express for the User Service, and Vite and React for the Webapp implementation. The team also agreed on the use of MongoDB as a database to store user’s login information and scores.

To achieve our quality goals, each member of the team is commited to ensure that every code delivered is of correct implementation, ensuring that it won’t break other member’s code. Every member is responsible for the entirety of the code implemented within the project, regardless of the authorship of said code.

4.2. Form

Our main decision made was to use MongoDB as our prefered database, this is because, it is of easy use and implementation, and a standard with the rest of our peers.

Our main constraints are those imposed by the default programming languages and the skeleton already provided.

5. Building Block View

5.1. Whitebox Overall System

5.1.1. Overview diagram

This diagram shows how the user interacts with the system.

User Interaction Sequence
Motivation

The Yovi system is web application that lets users play 'The game of Y'. The architecture of the project has been designed following a clear separation between presentation, application logic, game logic and data persistence. With this clear separation we improve maintanability, scalability and testability of the system.

Contained Building Blocks
Name Responsibility

Web Frontend

 Implemented using React and TypeScript, provides a responsive and easy user interface that allows players to play the game, save your score and perform moves in real time.

Backend

 Using Node.js and Express, managing user requests and game sessions, validates actions and coordinates communication between the frontend, the game logic server and the database.

Game server

Implemented in Rust, encapsulates the core logic of the 'Game of Y', including validation, game state management and win condition detection.

Database

MongoDB was chosen as the persistence layer as it provides flexibility and scalability for managing structured data.

5.2. Level 2 - Container View

This level illustrates the structural decomposition of the system into its three primary services, as established in the project architecture.

5.2.1. White Box

System behaviour
Motivation

The system uses a modular architecture for separating the user interface and services with the game logic service.

Contained Building Blocks
Name Responsibility

WebApp

Delivers the graphical user interface and communicates with backend services to handle user actions and requests. Located in /webapp directory.

Users Service

Manages user registration and stores user information. Located in /users directory.

Game Engine

Implements the core mechanics of the Game of Y, handling move validation and AI strategies, leveraging Rust for high performance. Located in /gamey.

MongoDB

Database used to store the user data and game information and history.

6. Runtime View

The runtime view describes the dynamic behavior and interactions of the YOVI system’s building blocks. Interaction with YOVI is centered around game turns, external API access, rust computing, and data persistence.

I have identified two primary use cases where the runtime view is architecturally significant to demonstrate the coordination between the TypeScript Web App and the Rust Module: human user interaction and automated bot interaction.

6.1. Human Player Game (Web UI)

This scenario shows how a valid user interacts with the application to play a match. The sequence includes authentication, game logic processing, and persistent storage of results.

User Interaction Sequence

In essence the system supports three core user interactions: account registration and authentication, playing matches against an AI opponent (bot), and reviewing personal game history and statistics.

6.2. Bot Interaction (External API)

The second use case focuses on how an external app or bot interacts with the system via the API "play" method, which is a core requirement for interoperability.

User Interaction Sequence

  1. API Request: The bot sends a JSON message to the /play endpoint containing a board position in YEN notation.

  2. Authorization: The Web App validates if the API key is valid.

  3. Stateless Computation: The Web App forwards the YEN data to the Rust Module.

  4. Logic Return: The Rust Module suggests the next movement based on the requested strategy and say it to the WebApp.

  5. API Response: The Web App returns the calculated movement directly to the bot in YEN format.

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.

Motivation

Software does not run without hardware. This underlying infrastructure can and will influence a system and/or some cross-cutting concepts.

7.1. Infrastructure Level 1: Production Environment

Describe distribution of a system to multiple locations, environments, computers, processors, physical connections, justifications, and mapping of software artifacts.

Infrastructure Level 1 Overview
Motivation

The system is deployed using a hybrid cloud strategy. The application logic is hosted on a Virtual Machine in Microsoft Azure running Ubuntu Linux, providing a scalable and reliable environment for Docker containerization. Persistence is decoupled via MongoDB Atlas to ensure data durability. This setup allows us to manage the technological heterogeneity (Node.js and Rust) while maintaining high availability.

Quality and/or Performance Features

  • Scalability: Azure allows for vertical scaling of the VM if the Rust engine or monitoring stack requires more resources.

  • Reliability: MongoDB Atlas provides a managed, replicated cluster that guarantees data persistence regardless of the VM state.

  • Portability: Using Docker on Ubuntu ensures that the entire stack can be replicated in any other cloud provider with minimal changes.

Mapping of Building Blocks to Infrastructure
Building Block Infrastructure Element Description

WebApp

Azure VM (Docker Container)

Nginx server delivering the React bundle.

Users Service

Azure VM (Docker Container)

Node.js API for user management and business logic.

GameY Engine

Azure VM (Docker Container)

High-performance Rust engine for game logic.

Monitoring

Azure VM (Docker Container)

Prometheus and Grafana for system observability.

Database

MongoDB Atlas (Cloud)

Managed NoSQL storage for persistent data.

7.2. Infrastructure Level 2: Azure VM & Docker Network

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

7.2.1. Application Host (Ubuntu Linux on Azure)

Inside the Azure Virtual Machine, all services are orchestrated via Docker Compose within a shared bridge network called monitor-net. This allows internal communication and metrics scraping using container names as DNS.

Execution Environments & Artifacts:

  • Web Server Container: An execution environment hosting the WebApp static files (HTML/JS/CSS) served by Nginx.

  • Users Service Container: An execution environment running the Node.js runtime for the Users API.

  • GameY Engine Container: A high-performance environment running the compiled Rust binary.

  • Monitoring Engine (Prometheus): A containerized artifact that scrapes metrics from the other services via monitor-net.

  • Visualization Tool (Grafana): A containerized artifact that queries Prometheus to display real-time dashboards, exposed on port 9091.

7.2.2. Client Side (User Environment)

The user’s browser acts as the primary execution environment for the React application. 1. Bootstrap: The browser requests the static bundle from the Azure VM (Port 80). 2. Execution: Once downloaded, the logic runs on the client’s device. 3. Communication: The client makes direct asynchronous REST calls to the Users (Port 3000) and GameY (Port 4000) containers hosted in Azure.

7.2.3. Persistence (MongoDB Atlas)

The Users Service connects to the MongoDB Atlas cluster via the MongoDB Wire Protocol. Access is secured through IP whitelisting (restricted to the Azure VM’s public IP) and TLS encryption, ensuring that sensitive user data is handled securely outside the main application host.

8. Cross-cutting Concepts

To better understand how the application works as a whole, it is useful to highlight a set of transversal concepts that influence different parts of the system. These ideas can be grouped into the following categories:

  • Domain Concepts

  • User Experience (UX)

  • Safety and security concepts

  • Architecture and design patterns

  • Development concepts

The following sections describe each of these categories in detail.

8.1. Domain Concepts

The domain of the YOVI platform is centered around the representation and management of games based on the Y game family. To support both human players and automated agents, the system defines several core concepts that structure how matches are created, played, validated, and interpreted.

  • User: Represents a human player interacting with the Web application. A user can start new games, make moves, and access game-related information.

  • Game: A game models an active or completed match of a Y‑based game. It includes the current board state, the sequence of moves, and the rules that determine valid actions. The Web application manages game creation, updates, and persistence, while delegating rule validation to the Rust module.

  • YEN Notation: The platform uses the YEN notation to encode game states and moves in JSON format. This notation provides a standardized way to represent a match, ensuring that both the Web application and the Rust module interpret the game consistently.

  • Bot Interaction Entities: The Web application exposes an external API that allows bots to participate in games. Bots receive the current game state and respond with their chosen move.

  • Rule Evaluation and Move Suggestion (Rust Module): The Rust subsystem encapsulates the logic for determining whether a game has been won and for suggesting the next optimal move.

Together, these domain concepts define the core structure of the YOVI ecosystem.

8.2. User Experience (UX)

The user experience design for the YOVI Web application is still in progress.

8.3. Safety and security concepts

Although the system is still under development, several security considerations have already been identified to ensure that both the web application and the Rust module operate in a controlled and reliable environment.

  • Restricted Access to Game Features Only authenticated users will be able to start or participate in games. This prevents unauthorized access to the platform and reduces the risk of misuse of the public API.

  • Protection of User Credentials User passwords will be stored using secure methods to prevent the exposure of credentials in the event of a breach.

  • Error Handling Without Confidential Information Error messages returned by the web application or the Rust service will prevent the exposure of internal data. This reduces the risk of information leaks that could be exploited by attackers.

These measures lay the foundation for a secure environment in which both human players and automated agents can safely interact with the YOVI platform.

8.4. Architecture and Design Patterns

The YOVI platform architecture is based on a modular design that separates responsibilities between the web application and the Rust service.

  • Architecture

    • The web application, implemented in TypeScript, manages users, game sessions, and the external API for bots.

    • The Rust module acts as a specialized service responsible for validating game states and suggesting moves.

This separation allows each subsystem to evolve independently, maintaining a clear contract through JSON-based communication.

  • API-Based Design

Both human players and bots interact with the system through well-defined APIs.

  • Communication via JSON (YEN notation) All game information is encoded using YEN notation, which provides a standardized and technology-independent representation of game states.

These architectural principles provide a solid foundation for the YOVI platform, ensuring that the system remains flexible, scalable, and easily evolves as new game variants or features are introduced.

8.5. Development concepts

8.6. Development Concepts

The development process of the YOVI platform follows a set of practices intended to ensure code quality and smooth collaboration among team members.

  • Testing Strategy The project includes automated tests at different levels.

  • Continuous Integration and Continuous Deployment (CI/CD) The codebase is maintained under a continuous integration workflow. Team members commit changes frequently, allowing automated pipelines to run tests and detect issues early.

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.

9. Architecture Decisions

Contents

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

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

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

Motivation

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

Form

Various options:

  • ADR (Documenting Architecture Decisions) for every important decision

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

  • more detailed in form of separate sections per decision

Further Information

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

The architectural decisions documented in this section complement the solution strategy described in Section 4. While the solution strategy outlines the main technologies and constraints inherited from the project skeleton, this section focuses on the reasoning behind the most relevant structural and organizational choices made during the early stages of the project.

Since the system is still in an initial development phase, the decisions captured here may evolve as the project grows. Their purpose is to provide clarity, traceability, and a shared understanding of the architectural direction.

9.1. Use of technologies provided with the project skeleton

9.1.1. Context

The project is based on a predefined skeleton that includes Rust for the game engine, Node.js/Express for the user service, and Vite/React for the web application.

9.1.2. Decision

Adopt the technologies already provided by the skeleton as the baseline for all components.

9.1.3. Rationale

Ensures consistency with the course requirements.

Reduces setup time and avoids unnecessary re‑evaluation of the technology stack.

Allows the team to focus on architectural design rather than tool selection.

9.1.4. Consequences

Limits the freedom to choose alternative frameworks or languages.

Requires the team to adapt to the constraints imposed by the skeleton.

9.2. Adoption of MongoDB as the project’s database.

9.2.1. Context

The project requires persistent storage for user login information and game scores.

9.2.2. Decision

Use MongoDB as the primary database for the system.

9.2.3. Rationale

Easy to use and integrate with Node.js.

Widely used among peers, facilitating knowledge sharing.

Flexible schema suitable for early‑stage academic projects.

9.2.4. Consequences

Requires maintaining a separate database service in the deployment environment.

May require schema validation mechanisms if the project grows in complexity.

9.3. Service-oriented separation of responsibilities

9.3.1. Context

The system consists of three components with distinct roles: frontend, user service, and game engine.

9.3.2. Decision

Maintain a clear separation of concerns by treating each component as an independent service with its own responsibilities and lifecycle.

9.3.3. Rationale

Improves modularity and maintainability.

Allows each component to evolve independently.

Aligns with the educational goal of exposing students to distributed architectures.

9.3.4. Consequences

Introduces the need for well‑defined communication interfaces.

Increases operational complexity compared to a monolithic approach.

10. Quality Requirements

10.1. Quality Tree

Quality Requirements

10.2. Quality Scenarios

Scenario ID Scenario Name Source Stimulus Environment Artifact Response Priority

SC-01

Performance

User

Open or refresh the page

Normal operation

Frontend, Backend, Rust

The system analyzes the action and summarizes the page to its previous state in the shortest possible time.

Medium

SC-02

Security

User, cheater

Tries to hack the game to claim a victory without playing

Normal Operation

Backend

The server checks teh client’s data and denies the request.

High

SC-03

Usability

User

New user enters the game for the first time

Normal operation

Frontend

The system shows clear instructions, intuitive controls and visual feedback so the user can understand how to play without external help.

Medium

SC-04

Maintainability

developer

Request to fix a bug

Maintenance phase

Backend, Frontend, Rust

The system design allows the developer to locate the problem and apply the fix with minimal impact on other components.

Medium

11. Risks and Technical Debt

This section describes the technical risks and the intentional (or unintentional) technical debt identified during the development of the YOVI system.

11.1. Risks

Risk Description Priority

Rust/TS Integration

Potential communication failures or performance bottlenecks in the YEN notation exchange between the TypeScript Backend and the Rust Module.

High

Security and API Protection

Risks of unauthorized access to the game history or the bot-exclusive API if API keys and authentication mechanisms are not properly secured.

High

Performance and Scalability

The system’s ability to handle multiple simultaneous games could be compromised if the Rust calculation engine is not optimized or if the API bridge blocks threads.

High

Infrastructure Dependency (Azure)

Total reliance on Microsoft Azure for the production environment. Any service outage directly impacts the availability of the game for both users and bots.

Medium

Lack of prior collaboration within the team

Since the team has not worked together before, there is a risk of inefficiencies in coordination. Establishing clear communication channels and regularly updating each other on progress will mitigate this issue.

Medium

Lack of Integration Testing

Insufficient testing of the full cycle (Frontend → Backend → Rust → DB) could lead to undetected bugs in the game state transitions.

Medium

11.2. Technical Debt

Technical Debt Description

Learning Curve: Rust Expertise

The development team has limited prior experience with Rust. This may result in suboptimal memory management or non-idiomatic code that will require future refactoring.

Incomplete Documentation

As the project is still in an active development phase, some sections of the arc42 documentation and code comments are not yet fully completed or updated.

Code Refactoring

Early architectural decisions focused on achieving a functional prototype (MVP) might need to be refactored to improve maintainability and legibility.

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.