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 Application. The game allows players to face bots implementing different difficulties and game strategies. Real-time multiplayer mode is planned as a future feature.

Functional requirements:

The system will allow users to play against bots with different difficulty levels.
(Planned) Real-time multiplayer mode allowing users to play against other players.
The size of the board, as well as the strategies and difficulty of the bots to play against, can be selected by the user.
Users must be able to register and login. Both statistics and results of games will be 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

Quality Goal	Description
Performance (Low Latency)	The architecture must ensure near real-time game interactions by delegating heavy AI computations to a specialized Rust service (`gamey`) and using the lightweight YEN notation to minimize communication overhead between modules.
Interoperability	The system must be designed as an open ecosystem, providing standardized REST APIs and relying on YEN notation as a universal language to allow external, third-party bots to seamlessly integrate and play.
Maintainability & Scalability	A modular microservices architecture (gateway, users, game-manager, gamey) is strictly followed to ensure that independent subsystems can be scaled individually under high concurrent load and updated without affecting the rest of the system.
Security	The system must guarantee data integrity and access control by enforcing stateless JWT authentication at the API Gateway level and protecting sensitive user data (like passwords) through strong cryptographic hashing before reaching the database. Also not allowing the user to access to areas without being authenticated

Performance (Low Latency)

The architecture must ensure near real-time game interactions by delegating heavy AI computations to a specialized Rust service (gamey) and using the lightweight YEN notation to minimize communication overhead between modules.

Interoperability

The system must be designed as an open ecosystem, providing standardized REST APIs and relying on YEN notation as a universal language to allow external, third-party bots to seamlessly integrate and play.

Maintainability & Scalability

A modular microservices architecture (gateway, users, game-manager, gamey) is strictly followed to ensure that independent subsystems can be scaled individually under high concurrent load and updated without affecting the rest of the system.

Security

The system must guarantee data integrity and access control by enforcing stateless JWT authentication at the API Gateway level and protecting sensitive user data (like passwords) through strong cryptographic hashing before reaching the database. Also not allowing the user to access to areas without being authenticated

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 Gateway Service
Gateway Service	- Requests from Frontend - Requests from External Bots	- Forwards requests to Users Service, Game Manager, GameY - Responds back to Frontend and Bots
Users Service	- Registration/Login data from API - Requests from API (stats, history)	- User created / validated - Authentication result - Data from MongoDB
GameY	- Game moves from API - Bot decisions (internal)	- Game state updates - Bot actions - Responses to the API
MongoDB	- Queries from Users Service - Queries from Game Manager	- Returns requested user and game 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 Gateway Service

Gateway Service

- Requests from Frontend
- Requests from External Bots

- Forwards requests to Users Service, Game Manager, GameY
- Responds back to Frontend and Bots

Users Service

- Registration/Login data from API
- Requests from API (stats, history)

- User created / validated
- Authentication result
- Data from MongoDB

GameY

- Game moves from API
- Bot decisions (internal)

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

MongoDB

- Queries from Users Service
- Queries from Game Manager

- Returns requested user and game 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 developing the backend microservices: users (registration, login, stats), game-manager (game orchestration) and gatewayservice (single entry point for all API requests).
Express: Used for developing the REST APIs that allow communication between the Frontend and the backend microservices.
Rust: Used for developing the bots and to be used as the game engine.
Cargo: Used for building and compiling rust proyect.
MongoDB: Used as the database for both users (usersdb) and game-manager (gamesdb). Its document-based model fits naturally with JSON, which is the main communication format in the application, and makes it easier to store and retrieve flexible data structures without the overhead of a relational schema.

4.1.3. Infraestructure

Docker + Docker Compose: Used for containerizing each microservice independently and orchestrating them together, ensuring the stack works the same way across different environments.
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. Also used for the different game modes.
Factory pattern: Used for the different games names that could be created

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 our system, we use a microservices architecture, based on having different independent services that communicate with each other via REST APIs. The system is composed of 5 microservices:

webapp: Frontend layer served via Nginx.
gatewayservice: Single entry point for all external API requests, routing them to the appropriate microservice.
users: Handles user registration, login, statistics and match history.
game-manager: Orchestrates the game flow, applying moves and interacting with gamey for bot decisions.
gamey: The game engine implemented in Rust, responsible for move validation, win detection and bot logic.

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 which follows a microservices architecture consisting of a frontend application, an API Gateway, and specialized backend services that communicate through HTTP REST APIs. The system persists data in a shared MongoDB database.
Contained Building Blocks

Name	Responsibility	Technology
WebApp	Frontend user interface providing player interactions (login, game selection, gameplay, statistics)	React, TypeScript, Vite
Gateway Service	API Gateway that routes all client requests to appropriate microservices, manages JWT authentication and CORS	Node.js
User Service	Manages user registration, authentication, storage of player profiles, statistics, and game history	Node.js, MongoDB, JWT, bcrypt
Game Manager	Orchestrates game sessions, coordinates with Gamey for bot moves	Node.js, MongoDB
Gamey Engine	Implements core game logic, bot strategies , and coordinate calculations	Rust
MongoDB	Persistent data storage for user accounts and game sessions	MongoDB

Name

Responsibility

Technology

WebApp

Frontend user interface providing player interactions (login, game selection, gameplay, statistics)

React, TypeScript, Vite

Gateway Service

API Gateway that routes all client requests to appropriate microservices, manages JWT authentication and CORS

Node.js

User Service

Manages user registration, authentication, storage of player profiles, statistics, and game history

Node.js, MongoDB, JWT, bcrypt

Game Manager

Orchestrates game sessions, coordinates with Gamey for bot moves

Node.js, MongoDB

Gamey Engine

Implements core game logic, bot strategies , and coordinate calculations

Rust

MongoDB

Persistent data storage for user accounts and game sessions

MongoDB

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
Bot Server	Exposes RESTful endpoints for bot move selection and win detection. Accepts game state in YEN format and returns move coordinates or game status
Core Logic	Internal game engine: implements rules, board state, move validation
Bot Registry	Internal bot manager: maintains random/beginner/medium bot implementations

Name

Responsibility

Bot Server

Exposes RESTful endpoints for bot move selection and win detection. Accepts game state in YEN format and returns move coordinates or game status

Core Logic

Internal game engine: implements rules, board state, move validation

Bot Registry

Internal bot manager: maintains random/beginner/medium bot implementations

Important Interfaces

API Endpoints:

GET /status - Health check, returns service status
POST /v1/ybot/choose/{bot_id} - Request bot move
- Input: YEN game state (JSON)
- Output: {api_version, bot_id, coords: {x, y, z}}
POST /v1/ybot/checkWin - Check game status
- Input: YEN game state (JSON)
- Output: {api_version, game_over: boolean, winner: number|null}

…describes the internal structure of building block 1.

5.2.2. White Box WebApp

WebApp Internal Structure and Navigation

Contained Building Blocks

Name	Responsibility
Landing Page	Initial entry point providing game overview and navigation options to login or register
Login Form	User authentication interface, validates credentials and obtains JWT token for session
Register Form	User registration interface for creating new player accounts with profile information
Menu View	Main dashboard after authentication, serves as navigation hub to other features
How To Play	Instructions and tutorials explaining game rules, mechanics, and strategies
Game Selection	Customization interface for game parameters (bot difficulty, board size) before game start
Game UI	Main game interface displaying board state, accepting player moves, and showing bot responses
Stats View	Displays individual player statistics, win/loss records, and performance metrics
Ranking View	Shows leaderboard with top players and their current rankings

Name

Responsibility

Landing Page

Initial entry point providing game overview and navigation options to login or register

User authentication interface, validates credentials and obtains JWT token for session

User registration interface for creating new player accounts with profile information

Menu View

Main dashboard after authentication, serves as navigation hub to other features

How To Play

Instructions and tutorials explaining game rules, mechanics, and strategies

Game Selection

Customization interface for game parameters (bot difficulty, board size) before game start

Game UI

Main game interface displaying board state, accepting player moves, and showing bot responses

Stats View

Displays individual player statistics, win/loss records, and performance metrics

Ranking View

Shows leaderboard with top players and their current rankings

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 8080 and 8000 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`, `gatewayservice`, `users`, `game-manager`, `gamey`, and `mongodb`.

Local Developer PC

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

Azure VM (Ubuntu)

Production containers: webapp, gatewayservice, users, game-manager, 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 (Port 8080)
Container: gatewayservice	Express Proxy / JWT Auth	Node.js 22 (Entry Point, Port 8000)
Container: users	Node.js / Express API	Node.js 22 Runtime
Container: game-manager	Node.js / Orchestrator	Node.js 22 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 (Port 8080)

Container: gatewayservice

Express Proxy / JWT Auth

Node.js 22 (Entry Point, Port 8000)

Container: users

Node.js / Express API

Node.js 22 Runtime

Container: game-manager

Node.js / Orchestrator

Node.js 22 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 8080) 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). Communication with gamey is not a generic proxy — only the specific endpoint POST /api/gamey/play is exposed.

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

The gatewayservice exposes a Swagger UI at /api-docs using swagger-ui-express and a single openapi.yaml that documents all public API endpoints across microservices (/api/users, /api/game-manager, /api/gamey).

8.4.3. Testing Strategy

Node.js microservices (users, game-manager, 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

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 at the 95th percentile under sustained load.
Stimulus	POST `/api/gamey/play` — sustained load of 13 requests/second over 60 seconds across random, beginner and medium bots
Response	95th percentile response time under 1000ms, with over 99% of requests successful
Priority	High
Verified by	`BotAPISimulation` (Gatling)

Scenario

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

Stimulus

POST /api/gamey/play — sustained load of 13 requests/second over 60 seconds across random, beginner and medium bots

Response

95th percentile response time under 1000ms, with over 99% of requests successful

Priority

High

Verified by

BotAPISimulation (Gatling)

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 with a maximum response time of 2000ms under sustained load.
Stimulus	POST `/api/users/login` — sustained load of 2 requests/second over 60 seconds
Response	Maximum response time under 2000ms, with over 95% of requests successful
Priority	High
Verified by	`LoginSimulation` (Gatling)

Scenario

A user sends a login request to the gateway. The gateway proxies the request to the users service and returns a JWT token with a maximum response time of 2000ms under sustained load.

Stimulus

POST /api/users/login — sustained load of 2 requests/second over 60 seconds

Response

Maximum response time under 2000ms, with over 95% of requests successful

Priority

High

Verified by

LoginSimulation (Gatling)

10.2.2. Usability

ID	Q3
Scenario	A new user accesses the webapp for the first time. Without any prior instructions, they are able to register, login and start a game within 3 minutes.
Stimulus	User navigates to the webapp landing page
Response	User completes registration, login and game creation in under 3 minutes
Priority	High

Scenario

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

Stimulus

User navigates to the webapp landing page

Response

User completes registration, login and game creation in under 3 minutes

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	The system handles sustained concurrent load across multiple endpoints simultaneously — bot requests, login and stats — without errors and maintaining response times within defined thresholds.
Stimulus	Simultaneous execution of `BotAPISimulation` (13 req/s), `LoginSimulation` (2 req/s) and `RankingAndStatsSimulation` (5 req/s) over 60 seconds
Response	All requests processed within their respective response time thresholds with over 95% success rate
Priority	Medium
Verified by	`BotAPISimulation`, `LoginSimulation`, `RankingAndStatsSimulation` (Gatling)

Scenario

The system handles sustained concurrent load across multiple endpoints simultaneously — bot requests, login and stats — without errors and maintaining response times within defined thresholds.

Stimulus

Simultaneous execution of BotAPISimulation (13 req/s), LoginSimulation (2 req/s) and RankingAndStatsSimulation (5 req/s) over 60 seconds

Response

All requests processed within their respective response time thresholds with over 95% success rate

Priority

Medium

Verified by

BotAPISimulation, LoginSimulation, RankingAndStatsSimulation (Gatling)

ID	Q6
Scenario	The number of registered users grows from 100 to 200. The system continues to operate normally, with API response times remaining under 2000ms for standard requests.
Stimulus	User database grows from 100 to 200 registered users
Response	No degradation in response time — standard API calls remain under 2000ms
Priority	Low

Scenario

The number of registered users grows from 100 to 200. The system continues to operate normally, with API response times remaining under 2000ms for standard requests.

Stimulus

User database grows from 100 to 200 registered users

Response

No degradation in response time — standard API calls remain under 2000ms

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 within 1000ms at the 95th percentile.
Stimulus	POST `/api/gamey/play` with valid YEN body under sustained load
Response	Bot move coordinates returned in JSON format within 1000ms at the 95th percentile
Priority	High
Verified by	`BotAPISimulation` (Gatling)

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 within 1000ms at the 95th percentile.

Stimulus

POST /api/gamey/play with valid YEN body under sustained load

Response

Bot move coordinates returned in JSON format within 1000ms at the 95th percentile

Priority

High

Verified by

BotAPISimulation (Gatling)

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 using YEN notation
Response	Service communicates successfully using YEN notation without changes to existing services
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 using YEN notation

Response

Service communicates successfully using YEN notation without changes to existing services

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 registers it in docker-compose.yml and adds the corresponding route in the gateway without modifying any existing service.
Stimulus	New microservice added to docker-compose.yml and gateway routing
Response	New service deployed and accessible through the gateway without changes to existing services
Priority	Medium

Q10

Scenario

A new microservice needs to be added to the system. The developer registers it in docker-compose.yml and adds the corresponding route in the gateway without modifying any existing service.

Stimulus

New microservice added to docker-compose.yml and gateway routing

Response

New service deployed and accessible through the gateway without changes to existing services

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
Verified by	E2E / Integration Tests

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

Verified by

E2E / Integration Tests

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
Verified by	E2E / Integration Tests

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

Verified by

E2E / Integration Tests

ID Q15

ID	Q15
Scenario	A malicious user or script attempts to register an account using an email or username that already exists in the system.
Stimulus	POST `/api/users/register` with duplicate credentials
Response	Registration is rejected by the system with a 409 Conflict status code, protecting data integrity.
Priority	High
Verified by	`RegisterSimulation` (Gatling) & E2E / Integration Tests

Scenario

A malicious user or script attempts to register an account using an email or username that already exists in the system.

Stimulus

POST /api/users/register with duplicate credentials

Response

Registration is rejected by the system with a 409 Conflict status code, protecting data integrity.

Priority

High

Verified by

RegisterSimulation (Gatling) & E2E / Integration Tests

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 on GitHub or a push is made to master. The CI/CD pipeline automatically runs all tests and coverage for all services and blocks the merge if any test fails.
Stimulus	Pull request opened on GitHub (any branch) or push to master
Response	GitHub Actions runs all tests and SonarQube analysis reporting results within 5 minutes
Priority	High

Q14

Scenario

A pull request is opened on GitHub or a push is made to master. The CI/CD pipeline automatically runs all tests and coverage for all services and blocks the merge if any test fails.

Stimulus

Pull request opened on GitHub (any branch) or push to master

Response

GitHub Actions runs all tests and SonarQube analysis 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.

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

Debt	Description	Possible Solution
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	The `gatewayservice` exposes a Swagger UI with an `openapi.yaml` that centralises all public API documentation. However, some endpoints are not yet documented (e.g. `/api/users/history`), leaving gaps for external developers and bot integrators.	Complete the gateway’s `openapi.yaml` to cover all public endpoints, including request/response schemas, authentication requirements and error codes.

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

The gatewayservice exposes a Swagger UI with an openapi.yaml that centralises all public API documentation. However, some endpoints are not yet documented (e.g. /api/users/history), leaving gaps for external developers and bot integrators.

Complete the gateway’s openapi.yaml to cover all public endpoints, including request/response schemas, authentication requirements and error codes.

12. Testing

This section describes the testing strategy applied across the system, covering unit and integration tests for each microservice, end-to-end tests for the full application flow, and load testing results for performance validation.

12.1. Unit and Integration Tests

12.1.1. users-service

The users-service test suite uses Vitest with mocked MongoDB models (MockUser, MockStats, MockHistory) and a mocked bcrypt dependency, allowing tests to run without a real database.

Endpoint	Tested
POST /register	Successful creation with valid data; optional fields (age, country); 409 on duplicate username/email; 400 on missing, too short, or invalid username; 400 on invalid email; 400 on weak password (too short, no numbers, no letters)
POST /login	Successful login returning JWT; 401 on wrong password; 404 on unknown user
POST /stats/update	Stats updated correctly; 404 on unknown user; 400 on invalid payload
GET /stats/:userId	Returns stats for existing user; 404 on unknown user
GET /stats/ranking	Returns ranked list; correct ordering by wins and win rate
POST /history/add	Game history entry added; 404 on unknown user
GET /history/:userId	Returns game history; 404 on unknown user

Endpoint

Tested

POST /register

Successful creation with valid data; optional fields (age, country); 409 on duplicate username/email; 400 on missing, too short, or invalid username; 400 on invalid email; 400 on weak password (too short, no numbers, no letters)

POST /login

Successful login returning JWT; 401 on wrong password; 404 on unknown user

POST /stats/update

Stats updated correctly; 404 on unknown user; 400 on invalid payload

GET /stats/:userId

Returns stats for existing user; 404 on unknown user

GET /stats/ranking

Returns ranked list; correct ordering by wins and win rate

POST /history/add

Game history entry added; 404 on unknown user

GET /history/:userId

Returns game history; 404 on unknown user

12.1.2. game-manager

The game-manager test suite uses Vitest with MongoMemoryServer for an in-memory MongoDB instance and nock to intercept HTTP calls to the bot server (gamey) and users service, ensuring full isolation.

Endpoint	Tested
GET /health	Returns service status
POST /create/:gameName	Creates game successfully; 400 on missing userId, invalid userId, or unknown game type
GET /state/:id	Returns current game state; 404 on unknown game
GET /list	Returns list of games for the authenticated user
POST /game/:id/resign	Marks game as resigned; 404 on unknown game
POST /game/:id/move/player	Accepts valid player move; 400 on occupied cell; 400 on out-of-bounds coordinates; detects win condition
POST /game/:id/move/bot	Calls gamey and applies bot move; handles gamey errors gracefully
500 errors	Database failure scenarios return 500 with error body

Endpoint

Tested

GET /health

Returns service status

POST /create/:gameName

Creates game successfully; 400 on missing userId, invalid userId, or unknown game type

GET /state/:id

Returns current game state; 404 on unknown game

GET /list

Returns list of games for the authenticated user

POST /game/:id/resign

Marks game as resigned; 404 on unknown game

POST /game/:id/move/player

Accepts valid player move; 400 on occupied cell; 400 on out-of-bounds coordinates; detects win condition

POST /game/:id/move/bot

Calls gamey and applies bot move; handles gamey errors gracefully

500 errors

Database failure scenarios return 500 with error body

12.1.3. gateway-service

The gateway-service test suite uses Vitest and supertest and focuses on the service’s own status endpoint.

Endpoint	Tested
GET /status	Returns { status: "ok", service: "gatewayservice" }

Endpoint

Tested

GET /status

Returns { status: "ok", service: "gatewayservice" }

12.1.4. gamey (bot server — Rust)

The gamey service is written in Rust and tested with the built-in cargo test framework. Tests are split into two files.

bot_server_tests.rs — HTTP layer tests using Axum’s *tower::ServiceExt:

Test	Tested
test_status_endpoint_returns_ok	GET /status returns 200 with body "OK"
test_choose_endpoint_with_valid_request	POST /v1/ybot/choose/random_bot with valid YEN returns a valid move response
test_choose_endpoint_with_partially_filled_board	Bot chooses a cell from the remaining available ones
test_choose_endpoint_with_invalid_api_version	Unknown API version returns 404
test_choose_endpoint_with_unknown_bot	Unknown bot ID returns 404
test_choose_endpoint_with_invalid_json	Malformed JSON body returns 422
test_choose_endpoint_with_missing_content_type	Missing Content-Type header returns 415
test_choose_with_custom_bot_registry	Custom bot registry is used correctly
test_choose_with_empty_bot_registry	Empty registry returns 404
test_unknown_route_returns_404	Unknown routes return 404
test_wrong_method_on_status_endpoint	Wrong HTTP method returns 405
test_get_on_choose_endpoint_returns_method_not_allowed	GET on choose endpoint returns 405

Test

Tested

test_status_endpoint_returns_ok

GET /status returns 200 with body "OK"

test_choose_endpoint_with_valid_request

POST /v1/ybot/choose/random_bot with valid YEN returns a valid move response

test_choose_endpoint_with_partially_filled_board

Bot chooses a cell from the remaining available ones

test_choose_endpoint_with_invalid_api_version

Unknown API version returns 404

test_choose_endpoint_with_unknown_bot

Unknown bot ID returns 404

test_choose_endpoint_with_invalid_json

Malformed JSON body returns 422

test_choose_endpoint_with_missing_content_type

Missing Content-Type header returns 415

test_choose_with_custom_bot_registry

Custom bot registry is used correctly

test_choose_with_empty_bot_registry

Empty registry returns 404

test_unknown_route_returns_404

Unknown routes return 404

test_wrong_method_on_status_endpoint

Wrong HTTP method returns 405

test_get_on_choose_endpoint_returns_method_not_allowed

GET on choose endpoint returns 405

core_tests.rs — Game logic unit tests for GameY;

Test group	Tested
Initialization	Correct board size, starting player, cell count, and available cells for various board sizes
Basic moves	Player alternation, available cell count decreasing after moves, move tracking
Win detection	Player 0 and Player 1 win by connecting all three sides; no false positives; edge cases (size 1 and size 2 boards)
YEN serialization	Game state correctly serialised and deserialised using YEN notation
CLI	Command-line interface arguments parsed correctly

Test group

Tested

Initialization

Correct board size, starting player, cell count, and available cells for various board sizes

Basic moves

Player alternation, available cell count decreasing after moves, move tracking

Win detection

Player 0 and Player 1 win by connecting all three sides; no false positives; edge cases (size 1 and size 2 boards)

YEN serialization

Game state correctly serialised and deserialised using YEN notation

CLI

Command-line interface arguments parsed correctly

12.2. End-to-End Tests

The E2E suite uses Cucumber.js with Playwright to test the full application through the browser. Each feature file corresponds to a user-facing flow.

Feature	Scenarios covered
Register	Successful registration with valid data; error shown on duplicate username
Login	Successful login redirects to menu; wrong credentials show error message
Menu	"How to Play" page accessible; logout redirects to landing page
Game	Game board visible after selecting Standard mode; exit game redirects to menu; complete game ends with game-over screen and back-to-menu navigation
Stats & Ranking	Personal stats page accessible; global ranking page accessible
Security	Unauthenticated users are redirected to login when accessing /menu, /select, /stats, and /ranking

Feature

Scenarios covered

Register

Successful registration with valid data; error shown on duplicate username

Login

Successful login redirects to menu; wrong credentials show error message

Menu

"How to Play" page accessible; logout redirects to landing page

Game

Game board visible after selecting Standard mode; exit game redirects to menu; complete game ends with game-over screen and back-to-menu navigation

Stats & Ranking

Personal stats page accessible; global ranking page accessible

Security

Unauthenticated users are redirected to login when accessing /menu, /select, /stats, and /ranking

12.3. Load Testing

Load tests are written in Gatling and validate system performance under sustained concurrent load. Results are linked below.

Simulation	Description	Report
RegisterSimulation	20 users ramped over 30s (register flow including duplicate check)	View report
LoginSimulation	2 users/sec over 60s (login flow)	View report
RankingAndStatsSimulation	3 and 2 users/sec over 60s (ranking and personal stats endpoints)	View report
BotAPISimulation	13 users/sec over 60s (all three bot types in parallel)	View report

Simulation

Description

Report

RegisterSimulation

20 users ramped over 30s (register flow including duplicate check)

View report

LoginSimulation

2 users/sec over 60s (login flow)

View report

RankingAndStatsSimulation

3 and 2 users/sec over 60s (ranking and personal stats endpoints)

View report

BotAPISimulation

13 users/sec over 60s (all three bot types in parallel)

View report

13. 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

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, game-manager 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 five main microservices: webapp, gatewayservice, 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. In YOVI, the `gatewayservice` exposes a Swagger UI at `/api-docs` with a single `openapi.yaml` that centralises the documentation of all public API endpoints.
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").

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, game-manager 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 five main microservices: webapp, gatewayservice, 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. In YOVI, the gatewayservice exposes a Swagger UI at /api-docs with a single openapi.yaml that centralises the documentation of all public API endpoints.

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").