yovi_en3a

About arc42

arc42, the template for documentation of software and system architecture.

Template Version 8.2 EN. (based upon AsciiDoc version), January 2023

Created, maintained and © by Dr. Peter Hruschka, Dr. Gernot Starke and contributors. See https://arc42.org.

Note	This version of the template contains some help and explanations. It is used for familiarization with arc42 and the understanding of the concepts. For documentation of your own system you use better the plain version.

1. Introduction and Goals

Describes the relevant requirements and the driving forces that software architects and development team must consider. These include

underlying business goals,
essential features,
essential functional requirements,
quality goals for the architecture and
relevant stakeholders and their expectations

1.1. Requirements Overview

The main goal of this project is the development of YOVI, an implementation of the "Game Y" board game for the game development company "Micrati". The system must be a robust and scalable solution that combines modern web development technologies along with Rust’s efficient computational logic, which will use YEN notation to communicate with the Web Applcation. The game will contain several innovative features such as the possibility to face several bots implementing different difficulties and game strategies, as well as multiplayer mode in which you can play real time against other player.

Functional requirements:

The system will allow users to play against players or bots
The size of the board, as well as the strategies and difficulty of the bots to play against can be selected by the user
User must be able to register and login and both statistics and results of games will be also recorded
The application must be deployed and publicly accessible via the Web
The system will contain a Rust module for verifying win conditions and suggesting a "next move"

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

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

Motivation

You should know the quality goals of your most important stakeholders, since they will influence fundamental architectural decisions. Make sure to be very concrete about these qualities, avoid buzzwords. If you as an architect do not know how the quality of your work will be judged…

Form

A table with quality goals and concrete scenarios, ordered by priorities

Quality Goal	Description
Performance	The system must ensure low-latency interactions by using Rust for heavy computations and YEN notation for high-speed communication between modules.
Usability	The application must provide an intuitive and easy to use interface for seamless board interaction and strategy selection.
Scalability	The system should handle a growing number of players and concurrent bot requests without slowing down.
Interoperability	The application must allow external bots to interact with both the system and players.
Maintainability	The system is designed to be easy to fix and update due to its modular structure, allowing us to modify different subsystems separately.
Security	User data must be securely stored and will be protected against unauthorized access.
Testability	The system will have appropiate testing to ensure software correctness.

Quality Goal

Description

Performance

The system must ensure low-latency interactions by using Rust for heavy computations and YEN notation for high-speed communication between modules.

Usability

The application must provide an intuitive and easy to use interface for seamless board interaction and strategy selection.

Scalability

The system should handle a growing number of players and concurrent bot requests without slowing down.

Interoperability

The application must allow external bots to interact with both the system and players.

Maintainability

The system is designed to be easy to fix and update due to its modular structure, allowing us to modify different subsystems separately.

Security

User data must be securely stored and will be protected against unauthorized access.

Testability

The system will have appropiate testing to ensure software correctness.

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
Micrati	Project Owner	A scalable game suite that showcases high performance and supports future variants of Game Y.
Users	Users of the Game	A smooth and engaging game experience with a user-friendly interface.
Evaluators	Professors	Adherence to arc42 standards, correct use of YEN notation, and high quality in both Rust and TypeScript.

Role/Name

Contact

Expectations

Micrati

Project Owner

A scalable game suite that showcases high performance and supports future variants of Game Y.

Users

Users of the Game

A smooth and engaging game experience with a user-friendly interface.

Evaluators

Professors

Adherence to arc42 standards, correct use of YEN notation, and high quality in both Rust and TypeScript.

2. Architecture Constraints

The following constraints are the "boundary conditions" that limit the freedom of design decisions for the gamey project. They are derived from the lab assignment requirements.

2.1. Technical Constraints

Constraint	Description
Frontend Implementation	The Web application and user interface must be implemented using TypeScript.
Logic Module	The move suggestion and win verification engine must be implemented in Rust.
Data Exchange Format	All game state communication must utilize JSON following the YEN notation.
Deployment & CI/CD	The application must be publicly accessible via the Web.

Constraint

Description

Frontend Implementation

The Web application and user interface must be implemented using TypeScript.

Logic Module

The move suggestion and win verification engine must be implemented in Rust.

Data Exchange Format

All game state communication must utilize JSON following the YEN notation.

Deployment & CI/CD

The application must be publicly accessible via the Web.

2.2. Organizational Constraints

Constraint	Description
Documentation Standard	Documentation must follow the arc42 template and include Architectural Decision Records (ADRs).
Testing Requirements	Mandatory coverage for Unit, Integration, End-to-End (e2e), and Load testing.
Project Management	A github repository tracking Issue Tracking, Meeting Minutes, and Code Reviews must be used.

Constraint

Description

Documentation Standard

Documentation must follow the arc42 template and include Architectural Decision Records (ADRs).

Testing Requirements

Mandatory coverage for Unit, Integration, End-to-End (e2e), and Load testing.

Project Management

A github repository tracking Issue Tracking, Meeting Minutes, and Code Reviews must be used.

2.3. Conventions

Constraint Description

Constraint	Description
YEN Notation	Mandatory string format for representing board layouts (e.g., `"layout": "B/.B/RB./B..R"`).
AI Strategy Pattern	The computer opponent must implement multiple selectable strategies and support varying difficulty levels.
Bot Compatibility	The application must provide a documented External API with a `play` method for bot interaction.

YEN Notation

Mandatory string format for representing board layouts (e.g., "layout": "B/.B/RB./B..R").

AI Strategy Pattern

The computer opponent must implement multiple selectable strategies and support varying difficulty levels.

Bot Compatibility

The application must provide a documented External API with a play method for bot interaction.

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

Table 1. YOVI
Communication Partner	Input	Output
User	- Login credentials - Game decisions - Data requests	- Authentication result - Game state - Statistics / History
External Bots	- API requests	- Game data - Game actions

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.

3.2. Technical Context

Communication Partner	Input	Output
User	- Login credentials - Game moves / Strategy selection - Data requests	- Authentication result - Game state - Statistics / History
Web Frontend	- Requests from the user (login, moves, strategy)	- Forwards requests to API
API	- Requests from Frontend - Requests from External Bots	- Forwards requests to User Registration, User Service, GameY - Responds back to Frontend and Bots
User Registration	- Registration/Login data from API	- User created / validated - Authentication result
User Service	- Requests from API (stats, history)	- Data from MongoDB
GameY	- Game moves from API - Bot decisions (internal)	- Game state updates - Bot actions - Responses to the API
Bot (internal)	- Game state	- Next action
MongoDB	- Queries from User Service	- Returns requested user data

Communication Partner

Input

Output

User

- Login credentials
- Game moves / Strategy selection - Data requests

- Authentication result
- Game state
- Statistics / History

Web Frontend

- Requests from the user (login, moves, strategy)

- Forwards requests to API

API

- Requests from Frontend
- Requests from External Bots

- Forwards requests to User Registration, User Service, GameY
- Responds back to Frontend and Bots

User Registration

- Registration/Login data from API

- User created / validated
- Authentication result

User Service

- Requests from API (stats, history)

- Data from MongoDB

GameY

- Game moves from API
- Bot decisions (internal)

- Game state updates
- Bot actions
- Responses to the API

Bot (internal)

- Game state

- Next action

MongoDB

- Queries from User Service

- Returns requested user data

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.

4. Solution Strategy

4.1. Technologies used

4.1.1. FrontEnd

React + Typescript: Used for the principal face of the proyect, for the game interface and for the users registry.
Vite: Used for constructing the FrontEnd.

4.1.2. BackEnd

Node.js: Used for managing the users registration in the server.
Express: Used for develop the API rest that allows to communicate between FrontEnd and BackEnd.
Rust: Used for developing the bots and to be used as the game engine.
Cargo: Used for building and compiling rust proyect.
MongoDB: We are using MongoDB as the database for the users because it gives support for JSON, being it the main communication file in our application. Also because in case we need to keep the state of something in a JSON file at some point, it would be easier having a document based databes instead of having an SQL one.

4.1.3. Infraestructure

Docker: Used for having just one container that works the same way in different computers.
Github Actions: Used for automatizing tasks such as passing the test, compiling code before we push something into the repository
SonarCloud: Used for verifying the quality of the code.
Gitflow for branch strategy: We are using gitflow as branching strategy as we need keep a record of the changes, and because we are having different versions being coded at the same time so we need to keep them save.

4.2. Top-Level decomposition decisions

Strategy pattern: Used for the bots, having the YBot trait as an interface used for the different bots implemented.

4.3. How to achieve key quality goals

Performance: The game and the bots are developed in Rust, making the time responses lower than any other programming language.
Usability: The application must be user friendly, making the user feel comfortable while going through the application.
Maintability: The application must persist over time.
Security: The application must protect the users data by validating into the server all the movements by any user.
Testability: The application must be tested, using github actions to perform that tests before each push.

4.4. Organizational decisions

The use of GitHub for communicating beween members of the team.
A weekly meeting to clarify doubts about the project and decide what will be done during the week.
A record of these meetings will be kept in the repository’s wiki on GitHub.
Pull requests will be used to prevent problems with overwriting code.
Wiki in GitHub will be used for publishing information about the different modules so everyone in the team could see and understand the most critical parts of the proyect in case we need it.

4.5. Arquitecture Pattern Used

For developing out system, we will use a microservices arquitecture, that is based on having different independent services that communicate each other via APIs. For now, we will have at least 3 microservices: GameY that is the engine of the game, Users for managing the users verification and validation and WebApp for being the front layer of the system.

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.

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.

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.

Motivation: This is a high-level view of the project, with the three main components that make it up.
Contained Building Blocks

Name	Responsibility
WebApp	Web visual interface for the player to interact with the program
Users	REST API to manage registration and storage of players
Gamey	Main game logic and bots for the player to play against

Name

Responsibility

WebApp

Web visual interface for the player to interact with the program

Users

REST API to manage registration and storage of players

Gamey

Main game logic and bots for the player to play against

Important Interfaces: <Description of important interfaces>

Insert your explanations of black boxes from level 1:

If you use tabular form you will only describe your black boxes with name and responsibility according to the following schema:

Name	Responsibility
<black box 1>	<Text>
<black box 2>	<Text>

Name

Responsibility

<black box 1>

<Text>

<black box 2>

<Text>

If you use a list of black box descriptions then you fill in a separate black box template for every important building block . Its headline is the name of the black box.

Here you describe <black box 1> according the the following black box template:

Purpose/Responsibility
Interface(s), when they are not extracted as separate paragraphs. This interfaces may include qualities and performance characteristics.
(Optional) Quality-/Performance characteristics of the black box, e.g.availability, run time behavior, ….
(Optional) directory/file location
(Optional) Fulfilled requirements (if you need traceability to requirements).
(Optional) Open issues/problems/risks

5.2. Level 2

Here you can specify the inner structure of (some) building blocks from level 1 as white boxes.

You have to decide which building blocks of your system are important enough to justify such a detailed description. Please prefer relevance over completeness. Specify important, surprising, risky, complex or volatile building blocks. Leave out normal, simple, boring or standardized parts of your system

5.2.1. White Box Gamey

Contained Building Blocks

Name	Responsibility
Core	Core of the game, including the main game logic,coordinates,game_state , …
Bot	Registry of bots that the player can play against, can be accessed by the core to get the next move of a bot and through the Bot Server API.
CLI	The gamme can also be played through a command line interface, this is omly used for testing and debugging purposes.

Name

Responsibility

Core

Core of the game, including the main game logic,coordinates,game_state , …

Bot

Registry of bots that the player can play against, can be accessed by the core to get the next move of a bot and through the Bot Server API.

CLI

The gamme can also be played through a command line interface, this is omly used for testing and debugging purposes.

…describes the internal structure of building block 1.

5.2.2. White Box WebApp

Contained Building Blocks

Name	Responsibility
Login Page	Web page for user authentication and login, accesses the Users API to store users
Game Selection	After login, the user can customize his game settings, sucha as the bot he wants to play against, the board size, …
Game UI	The user can see the board and click on cells to make a move.

Name

Responsibility

Web page for user authentication and login, accesses the Users API to store users

Game Selection

After login, the user can customize his game settings, sucha as the bot he wants to play against, the board size, …

Game UI

The user can see the board and click on cells to make a move.

5.2.3. White Box <building block m>

<white box template>

5.3. Level 3

Here you can specify the inner structure of (some) building blocks from level 2 as white boxes.

When you need more detailed levels of your architecture please copy this part of arc42 for additional levels.

5.3.1. White Box <_building block x.1_>

Specifies the internal structure of building block x.1.

<white box template>

5.3.2. White Box <_building block x.2_>

<white box template>

5.3.3. White Box <_building block y.1_>

<white box template>

6. Runtime View

This section illustrates key runtime operations and interactions among the system’s components.

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. User registration

This scenario shows how a user registers in the system, including how the frontend and backend communicate.

6.2. User Login

This scenario shows how a user logs into the system, including how the frontend and backend communicate.

6.3. Game loop

This scenario shows how a user plays a game, including interactions with the web app, game core, and bot service.

7. Deployment View

7.1. Infrastructure Level 1

This level describes the distribution of the system across the environments used during the development and production phases of the YOVI_en3a project.

Motivation The project is designed to be highly portable. By using a Virtual Machine on Azure, we ensure that the application is accessible via a public IP/DNS for grading and testing, while the local environment is used for rapid development.

Quality and/or Performance Features * Availability: The Azure VM provides a stable 24/7 uptime. * Security: Management access is restricted via SSH (Port 22). Public access is strictly limited to Ports 80, 3000, and 4000 via Azure Network Security Groups. * Portability: The entire stack is containerized, allowing the team to switch from Azure to any other cloud provider with minimal configuration changes.

Mapping

Element Software Artifacts (Building Blocks)

Element	Software Artifacts (Building Blocks)
Local Developer PC	Source code, Node.js environment, Rust toolchain, and local Docker Desktop.
Azure VM (Ubuntu)	Production containers: `webapp`, `users`, `gamey`, and `mongodb`.

Local Developer PC

Source code, Node.js environment, Rust toolchain, and local Docker Desktop.

Azure VM (Ubuntu)

Production containers: webapp, users, gamey, and mongodb.

7.2. Infrastructure Level 2

This level zooms into the internal structure of the production environment hosted on Azure.

7.2.1. Azure Virtual Machine (Docker Host)

The system is orchestrated using Docker Compose within a single Ubuntu-based Virtual Machine.

Motivation Using a single VM with Docker Compose reduces architectural complexity and costs for the University project while maintaining complete isolation between the microservices.

Quality and/or Performance Features

Resource Efficiency: The gamey engine uses a multi-stage Docker build (based on debian:bookworm-slim). This ensures the VM does not waste RAM or Disk space on the Rust compiler during execution.
Orchestration & Decoupling: The game-manager acts as a central orchestrator, ensuring that only one service depends on the gamey engine. This isolates the complex Rust logic, simplifying maintenance and decoupling game state from raw calculations.
Persistence: A Docker Volume is used for the MongoDB container, ensuring data remains intact even if the container is recreated.
Isolation: All containers communicate through a private bridge network (monitor-net).

Mapping

Infrastructure Element	Artifact	Execution Environment
Container: webapp	React/Vite SPA	Nginx / Static HTTP Server
Container: gatewayservice	Express Proxy / Helmet	Node.js 20+ (Entry Point)
Container: users	Node.js / Express API	Node.js 20+ Runtime
Container: game-manager	Node.js / Orchestrator	Node.js 20+ Runtime
Container: gamey	Rust Server Binary	Debian Slim (No compiler)
Container: mongodb	MongoDB Image	Mongo 6.0+ Engine
Storage Volume	User Database Files	Persistent Host File System

Infrastructure Element

Artifact

Execution Environment

Container: webapp

React/Vite SPA

Nginx / Static HTTP Server

Container: gatewayservice

Express Proxy / Helmet

Node.js 20+ (Entry Point)

Container: users

Node.js / Express API

Node.js 20+ Runtime

Container: game-manager

Node.js / Orchestrator

Node.js 20+ Runtime

Container: gamey

Rust Server Binary

Debian Slim (No compiler)

Container: mongodb

MongoDB Image

Mongo 6.0+ Engine

Storage Volume

User Database Files

Persistent Host File System

Azure connections

7.2.2. Communication Channels

The following channels facilitate data exchange between the infrastructure nodes:

HTTP (Port 80): Used by the end-user’s browser to download the webapp assets.
REST/JSON (Port 8000): The single entry point for all API communication. The gatewayservice receives requests from the frontend and routes them to users, game-manager, or gamey based on the URL path.
Internal Microservice Communication: Services communicate within the monitor-net Docker network. The game-manager requests move validations from gamey via internal REST calls.
Database Access (Port 27017): Internal connection using the MongoDB Wire Protocol. Used by users for profile management and game-manager for persistent board state storage.
SSH (Port 22): Secure management channel for developers to perform git pull and docker-compose up operations.

8. Cross-cutting Concepts

8.1. Domain Concepts

8.1.1. User Management

Users are identified by a unique username and email. Each user has an associated statistics document (userstats) that tracks game performance. The relationship between users and their stats is maintained via MongoDB ObjectId references.

8.1.2. Game Representation (YEN Notation)

All game states are represented using YEN notation, a custom format that encodes the board layout, current turn, players and board size. This notation is used across the microservices as the common language for game state communication.

8.1.3. Game Flow

A game is played between a player and a bot:

The player can be either a human(turn 0) or an external bot communicating through the gateway API.
The internal bot (turn 1) is managed by gamey.

The game-manager orchestrates the flow:

Receives the player move
Applies the move
Requests the bot move from gamey
Returns the updated state of the board

8.2. Security Concepts

8.2.1. Authentication with JWT

All authenticated endpoints use JSON Web Tokens (JWT). Tokens are generated at login with a 24-hour expiration and must be included in subsequent requests. The JWT secret is stored as an environment variable and injected via docker-compose.

8.2.2. Password Encryption

All user passwords are hashed using bcrypt with a salt factor of 10 before being stored in MongoDB`. Plain text passwords are never persisted.

8.2.3. MongoDB Authentication

MongoDB requires username and password authentication via SCRAM-SHA-256. Credentials are stored in a .env file on the server and injected as environment variables. The authSource=admin parameter is required for all connections.

8.2.4. Internal Network Isolation

All microservices communicate through an internal Docker network (monitor-net). Only the gateway (port 8000) and webapp (port 80) are exposed externally. Direct access to users, game-manager, gamey and MongoDB is restricted to internal container communication.

8.3. Architecture and Design Patterns

8.3.1. Gateway Pattern

All external requests enter the system through a single gateway service running on port 8000. The gateway proxies requests to the appropriate microservice based on the URL prefix (/api/users, /api/game-manager, /api/gamey).

8.3.2. Proxy Request Pattern

The gateway uses a generic proxyRequest function that forwards any HTTP method, body, headers and query parameters to the target service. This allows adding new microservices without changing the proxy logic.

8.3.3. Database per Microservice

Only the microservices that require persistence have their own MongoDB database:

users connects to usersdb
game-manager connects to gamesdb

Both communication are made with a shared MongoDB container. This ensures data isolation while reducing infrastructure overhead.

8.4. Development Concepts

8.4.1. Environment Variables

All sensitive configuration (MongoDB credentials, JWT secret, service URLs) is managed through environment variables. Local development uses a .env file, while production injects them via docker-compose` on the server.

8.4.2. API Documentation

Each microservice exposes a Swagger UI at /api-docs using swagger-ui-express and openapi.yaml.

8.4.3. Testing Strategy

Node.js microservices (users, gateway) use Vitest and Supertest for unit and integration testing. Each Node.js service has a test:coverage script that generates coverage reports. The gamey service uses cargo test for unit testing and cargo llvm-cov for coverage reporting. The CI/CD pipeline runs all tests on every push and pull request before building and deploying.

8.5. Operational Concepts

8.5.1. Containerization

All microservices run as Docker containers managed by a single docker-compose.yml. Each service has its own Dockerfile based on lightweight base images (node:22-alpine, nginx:stable-alpine, debian:bookworm-slim for Rust).

8.5.2. CI/CD Pipeline

Two GitHub Actions workflows manage the pipeline:

build.yml: runs on every push and pull request, executes tests and SonarQube analysis.
release-deploy.yml: triggered on release, builds and publishes Docker images to GitHub Container Registry (ghcr.io), then deploys to the Azure VM via SSH.

8.5.3. Memory Management

The Azure VM has limited RAM (848MB). Swap (2GB) is configured with swappiness=10 to prioritize RAM usage and avoid performance degradation.

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

The detailed Architectural Decisions are documented in the project Wiki: Architectural Decisions

Contents

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

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

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

Motivation

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

Form

Various options:

ADR (Documenting Architecture Decisions) for every important decision
List or table, ordered by importance and consequences or:
more detailed in form of separate sections per decision

Further Information

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

10. Quality Requirements

Content

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

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

Motivation

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

Further Information

See Quality Requirements in the arc42 documentation.

10.1. Quality Tree

Content

The quality tree (as defined in ATAM – Architecture Tradeoff Analysis Method) with quality/evaluation scenarios as leafs.

Motivation

The tree structure with priorities provides an overview for a sometimes large number of quality requirements.

Form

The quality tree is a high-level overview of the quality goals and requirements:

tree-like refinement of the term "quality". Use "quality" or "usefulness" as a root
a mind map with quality categories as main branches

In any case the tree should include links to the scenarios of the following section.

10.2. Quality Scenarios

10.2.1. Performance

ID Q1

ID	Q1
Scenario	A player requests a bot move during a game. The bot (gamey, written in Rust) computes and returns the move coordinates within 1000ms under normal load.
Stimulus	POST `/api/game-manager/game/:id/move` request
Response	Bot move computed and game state updated in under 1000ms
Priority	High

Scenario

A player requests a bot move during a game. The bot (gamey, written in Rust) computes and returns the move coordinates within 1000ms under normal load.

Stimulus

POST /api/game-manager/game/:id/move request

Response

Bot move computed and game state updated in under 1000ms

Priority

High

ID Q2

ID	Q2
Scenario	A user sends a login request to the gateway. The gateway proxies the request to the users service and returns a JWT token within 1000ms.
Stimulus	POST `/api/users/login` request
Response	JWT token returned in under 1000ms
Priority	High

Scenario

A user sends a login request to the gateway. The gateway proxies the request to the users service and returns a JWT token within 1000ms.

Stimulus

POST /api/users/login request

Response

JWT token returned in under 1000ms

Priority

High

10.2.2. Usability

ID	Q3
Scenario	A new user accesses the webapp for the first time. Without any instructions they are able to register, login and start a game within 5 minutes.
Stimulus	User navigates to the webapp landing page
Response	User completes registration, login and game creation without taking a long time thinking how to achieve it
Priority	High

Scenario

A new user accesses the webapp for the first time. Without any instructions they are able to register, login and start a game within 5 minutes.

Stimulus

User navigates to the webapp landing page

Response

User completes registration, login and game creation without taking a long time thinking how to achieve it

Priority

High

ID Q4

ID	Q4
Scenario	A user attempts to register with an invalid email. The system displays a clear and descriptive error message without reloading the page.
Stimulus	POST `/api/users/register` with invalid email
Response	Error message displayed inline within 1000ms
Priority	Medium

Scenario

A user attempts to register with an invalid email. The system displays a clear and descriptive error message without reloading the page.

Stimulus

POST /api/users/register with invalid email

Response

Error message displayed inline within 1000ms

Priority

Medium

10.2.3. Scalability

ID Q5

ID	Q5
Scenario	50 concurrent players request bot moves simultaneously. The system processes all requests without errors and response time does not exceed 2 seconds.
Stimulus	50 simultaneous POST `/api/game-manager/game/:id/move` requests
Response	All requests processed successfully within 2 seconds
Priority	Medium

Scenario

50 concurrent players request bot moves simultaneously. The system processes all requests without errors and response time does not exceed 2 seconds.

Stimulus

50 simultaneous POST /api/game-manager/game/:id/move requests

Response

All requests processed successfully within 2 seconds

Priority

Medium

ID	Q6
Scenario	The number of registered users doubles. The system continues to operate normally without requiring architectural changes.
Stimulus	User database grows significantly
Response	No degradation in performance or availability
Priority	Low

Scenario

The number of registered users doubles. The system continues to operate normally without requiring architectural changes.

Stimulus

User database grows significantly

Response

No degradation in performance or availability

Priority

Low

10.2.4. Interoperability

ID Q7

ID	Q7
Scenario	An external bot sends a POST request to `/api/gamey/play` with a valid YEN game state. The gateway proxies the request to gamey and returns the bot move coordinates.
Stimulus	POST `/api/gamey/play` with valid YEN body
Response	Bot move coordinates returned in JSON format
Priority	High

Scenario

An external bot sends a POST request to /api/gamey/play with a valid YEN game state. The gateway proxies the request to gamey and returns the bot move coordinates.

Stimulus

POST /api/gamey/play with valid YEN body

Response

Bot move coordinates returned in JSON format

Priority

High

ID	Q8
Scenario	A new microservice needs to communicate game state with game-manager. The developer uses YEN notation as the common format and integration is completed without modifying existing services.
Stimulus	New service integrated into the system
Response	Service communicates successfully using YEN notation
Priority	Medium

Scenario

A new microservice needs to communicate game state with game-manager. The developer uses YEN notation as the common format and integration is completed without modifying existing services.

Stimulus

New service integrated into the system

Response

Service communicates successfully using YEN notation

Priority

Medium

10.2.5. Maintainability

ID	Q9
Scenario	A developer needs to update the game logic in game-manager. The change is made, tested and deployed without modifying users, gamey or the gateway.
Stimulus	Change request for game-manager logic
Response	Change deployed independently without affecting other services
Priority	High

Scenario

A developer needs to update the game logic in game-manager. The change is made, tested and deployed without modifying users, gamey or the gateway.

Stimulus

Change request for game-manager logic

Response

Change deployed independently without affecting other services

Priority

High

ID	Q10
Scenario	A new microservice needs to be added to the system. The developer adds it to docker-compose.yml and the gateway without modifying existing services.
Stimulus	New microservice added to the system
Response	New service deployed and accessible through the gateway within one day
Priority	Medium

Q10

Scenario

A new microservice needs to be added to the system. The developer adds it to docker-compose.yml and the gateway without modifying existing services.

Stimulus

New microservice added to the system

Response

New service deployed and accessible through the gateway within one day

Priority

Medium

10.2.6. Security

ID Q11

ID	Q11
Scenario	A user attempts to access `/api/game-manager` endpoints without a valid JWT token. The gateway rejects the request with a 401 Unauthorized response before it reaches game-manager.
Stimulus	Request to `/api/game-manager` without Authorization header
Response	401 Unauthorized returned by the gateway
Priority	High

Scenario

A user attempts to access /api/game-manager endpoints without a valid JWT token. The gateway rejects the request with a 401 Unauthorized response before it reaches game-manager.

Stimulus

Request to /api/game-manager without Authorization header

Response

401 Unauthorized returned by the gateway

Priority

High

ID	Q12
Scenario	An attacker gains read access to the MongoDB database. User passwords are not recoverable because they are stored as bcrypt hashes with a salt factor of 10.
Stimulus	Unauthorized database access
Response	Passwords remain unrecoverable due to bcrypt hashing
Priority	High

Q12

Scenario

An attacker gains read access to the MongoDB database. User passwords are not recoverable because they are stored as bcrypt hashes with a salt factor of 10.

Stimulus

Unauthorized database access

Response

Passwords remain unrecoverable due to bcrypt hashing

Priority

High

10.2.7. Testability

ID	Q13
Scenario	A developer modifies an endpoint in game-manager. The existing integration test suite detects any regression and reports it within 1 minute of running npm test.
Stimulus	Code change in game-manager
Response	Test suite runs and reports pass or failure within 1 minute
Priority	High

Q13

Scenario

A developer modifies an endpoint in game-manager. The existing integration test suite detects any regression and reports it within 1 minute of running npm test.

Stimulus

Code change in game-manager

Response

Test suite runs and reports pass or failure within 1 minute

Priority

High

ID	Q14
Scenario	A pull request is opened against the develop branch. The CI/CD pipeline automatically runs all tests and coverages for all services and blocks the merge if any test fails.
Stimulus	Pull request opened on GitHub
Response	GitHub Actions runs all tests and SonarQube checks coverage reporting results within 5 minutes
Priority	High

Q14

Scenario

A pull request is opened against the develop branch. The CI/CD pipeline automatically runs all tests and coverages for all services and blocks the merge if any test fails.

Stimulus

Pull request opened on GitHub

Response

GitHub Actions runs all tests and SonarQube checks coverage reporting results within 5 minutes

Priority

High

Contents

Concretization of (sometimes vague or implicit) quality requirements using (quality) scenarios.

These scenarios describe what should happen when a stimulus arrives at the system.

For architects, two kinds of scenarios are important:

Usage scenarios (also called application scenarios or use case scenarios) describe the system’s runtime reaction to a certain stimulus. This also includes scenarios that describe the system’s efficiency or performance. Example: The system reacts to a user’s request within one second.
Change scenarios describe a modification of the system or of its immediate environment. Example: Additional functionality is implemented or requirements for a quality attribute change.

Motivation

Scenarios make quality requirements concrete and allow to more easily measure or decide whether they are fulfilled.

Especially when you want to assess your architecture using methods like ATAM you need to describe your quality goals (from section 1.2) more precisely down to a level of scenarios that can be discussed and evaluated.

Form

Tabular or free form text.

11. Risks and Technical Debts

Contents

A list of identified technical risks or technical debts, ordered by priority

Motivation

“Risk management is project management for grown-ups” (Tim Lister, Atlantic Systems Guild.)

This should be your motto for systematic detection and evaluation of risks and technical debts in the architecture, which will be needed by management stakeholders (e.g. project managers, product owners) as part of the overall risk analysis and measurement planning.

Form

List of risks and/or technical debts, probably including suggested measures to minimize, mitigate or avoid risks or reduce technical debts.

Further Information

See Risks and Technical Debt in the arc42 documentation.

11.1. Technical Risks

Risk	Description	Possible Mitigation
Single Point of Failure at Gateway	All external traffic is routed through a single gateway service on port 8000. If the service crashes or overloads, the entire application becomes unreachable, despite the availability of the microservices.	Implement health checks and automatic container restart policies in docker-compose.
JWT Secret Exposure Risk	The JWT secret used to sign authentication tokens is stored in a .env file on the Azure server and injected via docker-compose. If the server is compromised or the file is accidentally committed to the repository, all user sessions could be forged.	Use a secrets manager (GitHub Secrets or Azure Key Vault) for production credentials. Rotate the JWT secret periodically.
MongoDB Single Container	Both usersdb and gamesdb share a single MongoDB container. A failure in this container would cause data loss for both users and game records, with no replication or backup strategy.	Implement automated database backups.
Rust / Node.js Communications via HTTP	The game Rust service communicates with Node.js microservices through HTTP calls. Network latency and serialization overhead between these services could degrade perceived game performance, especially for bot move requests.
Lack of External Bot Limitations	The public play API endpoint exposed for external bots has no rate limiting or authentication. A malicious attack could flood the game with requests, consuming all available Rust processing capacity.	Add rate limiting middleware to the gateway for the /api/gamey route. Require an API key for external bot access.

Risk

Description

Possible Mitigation

Single Point of Failure at Gateway

All external traffic is routed through a single gateway service on port 8000. If the service crashes or overloads, the entire application becomes unreachable, despite the availability of the microservices.

Implement health checks and automatic container restart policies in docker-compose.

JWT Secret Exposure Risk

The JWT secret used to sign authentication tokens is stored in a .env file on the Azure server and injected via docker-compose. If the server is compromised or the file is accidentally committed to the repository, all user sessions could be forged.

Use a secrets manager (GitHub Secrets or Azure Key Vault) for production credentials. Rotate the JWT secret periodically.

MongoDB Single Container

Both usersdb and gamesdb share a single MongoDB container. A failure in this container would cause data loss for both users and game records, with no replication or backup strategy.

Implement automated database backups.

Rust / Node.js Communications via HTTP

The game Rust service communicates with Node.js microservices through HTTP calls. Network latency and serialization overhead between these services could degrade perceived game performance, especially for bot move requests.

Lack of External Bot Limitations

The public play API endpoint exposed for external bots has no rate limiting or authentication. A malicious attack could flood the game with requests, consuming all available Rust processing capacity.

Add rate limiting middleware to the gateway for the /api/gamey route. Require an API key for external bot access.

11.2. Technical Debts

Debt	Description	Possible Solution
No Persistent Game State Recovery	If the game-manager container crashes mid-game, the current game state is lost. Games are not saved to the gamesdb during play, only at completion.	Persist game state to gamesdb after each move. On reconnection, allow the player to resume an interrupted game by querying the last saved state.
Hardcoded Service URLs in Gateway	The gateway resolves microservice addresses using hardcoded service names from docker-compose (for example http://users:3001).	Extract service URLs into environment variables. This would allow reconfiguration without code changes.
Missing API Versioning	All REST endpoints in the gateway and microservices are exposed without versioning (/api/users/login instead of /api/v1/users/login). Any breaking API change will require coordinated updates across all consumers simultaneously.	Introduce API versioning.
No Structured Logging	Microservices output logs to stdout using console.log without formatting.	Adopt a structured logging library that outputs JSON logs.
Swagger Documentation Incomplete	Each microservice is configured to expose a Swagger UI via openapi.yaml, but the actual files may not fully document all endpoints, request schemas, and error responses.	Ensure all request/response schemas, authentication requirements and error codes are documented.

Debt

Description

Possible Solution

No Persistent Game State Recovery

If the game-manager container crashes mid-game, the current game state is lost. Games are not saved to the gamesdb during play, only at completion.

Persist game state to gamesdb after each move. On reconnection, allow the player to resume an interrupted game by querying the last saved state.

Hardcoded Service URLs in Gateway

The gateway resolves microservice addresses using hardcoded service names from docker-compose (for example http://users:3001).

Extract service URLs into environment variables. This would allow reconfiguration without code changes.

Missing API Versioning

All REST endpoints in the gateway and microservices are exposed without versioning (/api/users/login instead of /api/v1/users/login). Any breaking API change will require coordinated updates across all consumers simultaneously.

Introduce API versioning.

No Structured Logging

Microservices output logs to stdout using console.log without formatting.

Adopt a structured logging library that outputs JSON logs.

Swagger Documentation Incomplete

Each microservice is configured to expose a Swagger UI via openapi.yaml, but the actual files may not fully document all endpoints, request schemas, and error responses.

Ensure all request/response schemas, authentication requirements and error codes are documented.

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
ADR (Architectural Decision Record)	A document that captures an important architectural decision made during the project, including its context and its consequences/responsabilities. ADRs for this project are located in the GitHub Wiki.
Azure VM	The Virtual Machine hosted on Microsoft Azure where the YOVI application is deployed in production.
bcrypt	A password-hashing function used to securely store user passwords, which is used in this project.
Bot	An artificial intelligence opponent in YOVI. Internal bots are implemented in Rust. External bots can also interact with the system through the public bot API.
Cargo	The build system and package manager for Rust. Used to compile, test, and run the gamey microservice.
CI/CD (Continuous Integration / Continuous Deployment)	The automated pipeline implemented via GitHub Actions that runs tests and code quality checks on every push and deploys the application to the Azure VM on each release.
Docker	A platform for packaging and running applications in isolated containers. All YOVI microservices are put in containers using Docker and managed with docker-compose.
docker-compose	A tool for defining and running multi-container Docker applications via a single docker-compose.yml configuration file. Used to manage the full YOVI application, including all microservices, MongoDB, Grafana…
Express	A minimal and flexible Node.js web framework used in the users and gateway microservices to define REST API routes.
Gateway	A microservice that acts as the single entry point for all external HTTP requests. It guides requests to the appropriate internal microservice based on the URL prefix (for example: /api/users, /api/gamey`).
GitHub Actions	The CI/CD platform integrated with the YOVI GitHub repository. It automates testing, code quality analysis, Docker image builds, and production deployments.
Gitflow	The branching strategy chosen by the YOVI team. It organizes work into feature branches, a develop branch for integration, and a master branch for stable releases.
JWT (JSON Web Token)	A compact, URL-safe token format used for authenticating users in YOVI. Tokens are issued at login and expire after 24 hours.
Microservice	An independently deployable service that handles a specific business capability. YOVI is composed of four main microservices: webapp, users, game-manager and gamey.
MongoDB	A document-oriented NoSQL database used for data persistence. A single shared MongoDB container hosts both usersdb and gamesdb.
React	A JavaScript library for building user interfaces. Used together with TypeScript to implement the YOVI webapp frontend.
Rust	A programming language focused on performance and memory safety. Used in YOVI to implement the gamey microservice (game engine and bots) due to its high computational efficiency.
SonarCloud	A cloud-based code quality and security analysis service integrated into the YOVI CI pipeline. It checks for bugs, vulnerabilities, and test coverage.
Swagger / OpenAPI	An open standard and toolset for describing REST APIs. Each YOVI microservice exposes a Swagger UI.
Strategy Pattern	A behavioral design pattern used for the YOVI bots. Each bot implementation provides a different strategy and difficulty level.
TypeScript	A strongly-typed superset of JavaScript. Used mainly in the frontend development of webapp microservice.
Vite	A fast build tool and development server used to bundle and serve the YOVI React/TypeScript frontend application.
Vitest	A Vite-native unit testing framework used to write and run tests for the Node.js microservices.
YEN Notation	A string format used as the common language for representing game states across all YOVI microservices. It encodes the board layout, current turn, players, and board size (example: "layout": "B/.B/RB./B..R").

Term

Definition

ADR (Architectural Decision Record)

A document that captures an important architectural decision made during the project, including its context and its consequences/responsabilities. ADRs for this project are located in the GitHub Wiki.

Azure VM

The Virtual Machine hosted on Microsoft Azure where the YOVI application is deployed in production.

bcrypt

A password-hashing function used to securely store user passwords, which is used in this project.

Bot

An artificial intelligence opponent in YOVI. Internal bots are implemented in Rust. External bots can also interact with the system through the public bot API.

Cargo

The build system and package manager for Rust. Used to compile, test, and run the gamey microservice.

CI/CD (Continuous Integration / Continuous Deployment)

The automated pipeline implemented via GitHub Actions that runs tests and code quality checks on every push and deploys the application to the Azure VM on each release.

Docker

A platform for packaging and running applications in isolated containers. All YOVI microservices are put in containers using Docker and managed with docker-compose.

docker-compose

A tool for defining and running multi-container Docker applications via a single docker-compose.yml configuration file. Used to manage the full YOVI application, including all microservices, MongoDB, Grafana…

Express

A minimal and flexible Node.js web framework used in the users and gateway microservices to define REST API routes.

Gateway

A microservice that acts as the single entry point for all external HTTP requests. It guides requests to the appropriate internal microservice based on the URL prefix (for example: /api/users, /api/gamey`).

GitHub Actions

The CI/CD platform integrated with the YOVI GitHub repository. It automates testing, code quality analysis, Docker image builds, and production deployments.

Gitflow

The branching strategy chosen by the YOVI team. It organizes work into feature branches, a develop branch for integration, and a master branch for stable releases.

JWT (JSON Web Token)

A compact, URL-safe token format used for authenticating users in YOVI. Tokens are issued at login and expire after 24 hours.

Microservice

An independently deployable service that handles a specific business capability. YOVI is composed of four main microservices: webapp, users, game-manager and gamey.

MongoDB

A document-oriented NoSQL database used for data persistence. A single shared MongoDB container hosts both usersdb and gamesdb.

React

A JavaScript library for building user interfaces. Used together with TypeScript to implement the YOVI webapp frontend.

Rust

A programming language focused on performance and memory safety. Used in YOVI to implement the gamey microservice (game engine and bots) due to its high computational efficiency.

SonarCloud

A cloud-based code quality and security analysis service integrated into the YOVI CI pipeline. It checks for bugs, vulnerabilities, and test coverage.

Swagger / OpenAPI

An open standard and toolset for describing REST APIs. Each YOVI microservice exposes a Swagger UI.

Strategy Pattern

A behavioral design pattern used for the YOVI bots. Each bot implementation provides a different strategy and difficulty level.

TypeScript

A strongly-typed superset of JavaScript. Used mainly in the frontend development of webapp microservice.

Vite

A fast build tool and development server used to bundle and serve the YOVI React/TypeScript frontend application.

Vitest

A Vite-native unit testing framework used to write and run tests for the Node.js microservices.

YEN Notation

A string format used as the common language for representing game states across all YOVI microservices. It encodes the board layout, current turn, players, and board size (example: "layout": "B/.B/RB./B..R").