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

The game development company Micrati has decided to begin developing a web-based system where users can play different variations of Game Y, an existing strategic board game. The initial idea is to offer an entertaining and intuitive experience to users. It will also provide several different strategies with different difficulty levels to attract user interest.

1.1. Requirements Overview

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.

The main requirements of the system are:

  • Provide a usable and functional version of the game with a variable board.

  • Available on the web.

  • Offer different strategies for playing the game with different difficulty levels selectable by the player.

  • Allow users to register on the system.

  • Allow users to view their game history (statistical data such as the number of games played, win/loss statistics, etc.).

  • Offer the option to play against a computer or a bot with an API.

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

Categories of Quality Requirements
Motivation

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

Form

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

Quality goal Description

Usability

The system should be easy for users to use and learn how to use correctly. This will encourage them to use the application again and enjoy the experience.

Functionality

The system must consider and implement the requirements correctly, allowing users to play the game Y with different strategies, register in the application, consult their statistics…​

Accessibility

The application must be available from the Web.

Performance

The app should respond to user requests within a reasonable timeframe. This prevents users from abandoning the app and ensures a positive experience that encourages them to return.

Maintainability

The system should be easy to maintain and extend. This is achieved by following good programming practices, maintaining excellent communication within the development team…​

Security

The private data of registered users must be kept safe.

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

Development team

José Iván Díaz Potenciano uo302531@uniovi.es - Adrián Gutiérrez García uo300627@uniovi.es - Fernando Remis Figueroa uo302109@uniovi.es - Hugo Carbajales Quintana uo300051@uniovi.es - Sergio Argüelles Huerta uo299741@uniovi.es

Responsible for developing the assigned application using good techniques, working properly as a team, and achieving a solution that is as maintainable and usable as possible.

Users

Application users

Having a good experience using the application, where they can play the game using different strategies and check their statistics.

Micrati

Micrati company

Expects to obtain an application that aligns with its ideas and objectives.

Professor of the ASW subject

Jose Emilio Labra Gayo - labra@uniovi.es

Assume the role of Product Owner, defining high-level requirements, providing feedback to the development team, and evaluating the developed product.

2. Architecture Constraints

Contents

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

2.1. Technical Constraints

Constraint Explanation

React & TypeScript

The frontend must be developed using React and TypeScript.

Node.js & Express

The user management service will be implemented using Node.js and Express.

Rust Game Engine

The core logic for the "Game of Y" must be implemented in Rust to ensure performance.

Docker

The system must be containerized using Docker and orchestrated with Docker Compose.

GitHub Actions

CI/CD pipelines must be managed using GitHub Actions for automated testing and deployment.

YEN Notation

Game moves and state must follow the standard YEN (Y-Game Extended Notation).

2.2. Organizational Constraints

Constraint Explanation

Team Size

The team consists of 5 members: José Iván, Adrián, Fernando, Hugo, and Sergio.

Timeframe

The project must be tested, code completed and discussed before the final submission.

Meetings

Weekly meetings will be held during laboratory sessions to track progress, besides possible meetings to discuss some issues or problems throught the week.

Version Control

GitHub is the chosen platform for repository hosting and version control.

2.3. Political and Convention Constraints

Constraint Explanation

Arc42

The documentation must follow the Arc42 template structure.

Language

The documentation and code comments must be written in English, as it’s the standard.

3. Context and Scope

Contents

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

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

Motivation

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

Form

Various options:

  • Context diagrams

  • Lists of communication partners and their interfaces.

Further Information

See Context and Scope in the arc42 documentation.

3.1. Business Context

Contents

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

Motivation

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

Form

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

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

diagram

Diagram elements:

  • User: Represents the end-user who interacts with the web application to play games and manage their profile.

  • Admin: Represents the technical user responsible for overseeing the system’s stability and performance via the internal monitoring dashboards.

  • Yovi: Represents the complete system boundary (the scope of this project). It acts as a unified solution that encapsulates the game engine, user management, data persistence, and the observability infrastructure (Prometheus & Grafana).

3.2. Technical Context

Contents

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

Motivation

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

Form

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

diagram

The Yovi system uses a set of HTTP interfaces for communication between microservices and to expose data to the actors (Player and Administrator). The communication channels represented in the architecture diagram are detailed below:

  • External access interfaces:

    • Frontend Delivery Interface: The Player’s browser connects to the WebApp service via port 80 to download the static files (HTML, CSS, JavaScript) needed to run the Single Page Application (React).

    • User management API and game logic: The React App (SPA) running in the browser interacts with the Users Service (port 3000) and the Game Service (port 4000), sending and receiving data exclusively in JSON format. These interfaces manage authentication and game mechanics using the HTTP protocol.

    • Display Interface: This connection delivers the Grafana graphical interface to the Administrator via port 9091. It uses standard HTTP to serve the control panels for system monitoring.

  • Internal interfaces:

    • Collection and consultation channel within the private network: Prometheus makes periodic HTTP GET requests to the Users Service’s internal port 3000 to collect technical health metrics. Simultaneously, Grafana queries the Prometheus database on port 9090 to retrieve historical data and generate graphs.

    • Data Persistence Interface: Both the Users Service and the Gamey Service communicate directly with the internal MongoDB database. The Users Service manages user profiles and authentication, while the Gamey Service persists game logs and match history. These connections are strictly internal to the backend environment.

4. Solution Strategy

Contents

A short summary and explanation of the fundamental decisions and solution strategies, that shape system architecture. It includes

  • technology decisions

  • decisions about the top-level decomposition of the system, e.g. usage of an architectural pattern or design pattern

  • decisions on how to achieve key quality goals

  • relevant organizational decisions, e.g. selecting a development process or delegating certain tasks to third parties.

Motivation

These decisions form the cornerstones for your architecture. They are the foundation for many other detailed decisions or implementation rules.

Form

Keep the explanations of such key decisions short.

Motivate what was decided and why it was decided that way, based upon problem statement, quality goals and key constraints. Refer to details in the following sections.

Further Information

See Solution Strategy in the arc42 documentation.

4.1. Technology Decisions

4.1.1. Frontend

We chose React combined with TypeScript for the user interface development. React’s component-based architecture is ideal for modularizing the complex visualization of the game board and managing the reactive state of the match. The adoption of TypeScript adds a static typing system that drastically reduces compile-time errors, especially when manipulating game data structures, guaranteeing more robust and self-documenting code.

Quality goals: usability, maintainability, robustness.

Key constraints: The system must be accessible from any modern web browser, managing communication with the backend asynchronously via JSON.

4.1.2. Backend

For the backend, on one hand, we chose Rust as it offers native performance, utilizing 100% of the CPU power, which guarantees low and predictable response times. Additionally, it prevents common errors such as null pointers or race conditions at compile time. This is crucial for a server that must be robust and not crash in the middle of a match. Rust’s type system allows invalid game states to be represented as compilation errors or controlled errors, rather than runtime exceptions. On the other hand, we also use Node.js for user management and standard web APIs. Node.js is excellent for creating fast REST APIs (such as user registration), while Rust is superior for the algorithmic logic of the game.

Quality goals: interoperability, scalability, and robustness.

Key constraints: The system is restricted to using the YEN string format to represent the game state. This is the strict contract between client and server.

4.1.3. Database

We chose MongoDB as our primary database because of its flexibility. Unlike traditional databases that use rigid tables, MongoDB stores information in "documents," a format that perfectly complements our coding technologies (Node.js and React). This choice allows us to achieve two key things: first, agility, as we can change what data we store about users or games without having to restructure the entire system each time. And second, speed, ensuring that saving game histories is fast and doesn’t interrupt the player experience.

Quality goals: Agility in development and speed of response.

Key constraints: The system must be able to store varied game data without a fixed structure, while maintaining security for user account data. ==== Containers Docker was selected for service containerization as it combines both Node.js and Rust. Furthermore, Docker guarantees absolute consistency of the environment between development machines and the production server. It also greatly facilitates the coordination of the microservices architecture, isolating the specific dependencies of each language to avoid conflicts and simplify joint deployment.

Quality goals: portability, deployability, scalability, reproducibility.

Key constraints: The host environment must have a compatible container runtime capable of coordinating multiple containers simultaneously.

4.1.4. Monitoring

We chose the combination of Prometheus and Grafana to implement the system’s monitoring and observability strategy. Prometheus acts as a time-series database, responsible for collecting technical metrics from the backend. Grafana connects to this data to visualize it on graphical dashboards in real-time. This decision is critical to quantitatively validate our performance requirements and detect what is slowing down the microservices architecture.

Quality goals: observability, performance, availability.

Key constraints: The services (both the Node.js one and the Rust engine) must be programmed to expose their metrics at a web address with a standard format that Prometheus can read periodically.

4.1.5. Modeling Tools

PlantUML was selected to ensure agility in creating UML diagrams (Sequence, Class, Component). Unlike "drag and drop" visual tools, PlantUML ensures consistent and standardized aesthetics for all project diagrams, regardless of who creates them, allowing developers to focus on logical content rather than graphic design.

Quality goals: consistency, efficiency, clarity.

Key constraints: The source format must be plain text editable with any standard IDE and renderable without proprietary software licenses.

4.1.6. Version Control

We use GitHub to centralize code and facilitate teamwork. It allows us to develop new features in parallel using branches, avoiding conflicts between colleagues. Additionally, it protects project quality through the use of Pull Requests, ensuring that all new code is reviewed and approved by another colleague before being integrated into the main version.

Quality goals: collaboration, code integrity, maintainability.

Key constraints: Every change must undergo a mandatory review (Pull Request) and have passing tests (green tests) before it can be merged.

4.2. High-level Decomposition

The following describes the fundamental architectural patterns that structure the communication and organization of the system.

4.2.1. Microservices Architecture

We opted to divide the backend system into autonomous services (Users Service and Gamey Service) instead of using a monolith. This decision allows decoupling the user management logic from the game logic, facilitating the use of specialized technologies for each task. Furthermore, it improves fault tolerance: if the user service goes down, the game could continue functioning (and vice versa).

Quality goals: modifiability, scalability, technological independence.

Key constraints: Each microservice must own its own data and run in an isolated container, communicating with others solely over the network.

4.2.2. Single Page Application (SPA)

The frontend has been designed following the SPA pattern using React. This completely separates the presentation layer from the business logic. By loading the application once and updating content dynamically, we offer a much more fluid and fast user experience, similar to a desktop application, avoiding constant page reloads.

Quality goals: usability, interoperability, performance.

Key constraints: The client is responsible for managing routing and view state, offloading the task of rendering HTML from the server.

4.2.3. REST Architectural Style

To connect the Frontend with the Microservices, we use a REST architecture. The use of the standard HTTP protocol and JSON format ensures the system is easy to understand and test. As a universal standard, it allows our TypeScript frontend to communicate seamlessly with a Rust backend and a Node.js backend without the need for complex adapters.

Quality goals: simplicity, interoperability, decoupling.

Key constraints: Communication must be stateless. This means the server does not save information about the previous request; each message from the client must contain all necessary information to be processed.

4.3. Strategies for Quality Goals

The following table relates our quality goals to specific scenarios and the architectural strategies implemented to resolve them.

Quality Goal Scenario Solution Strategy

Performance

The game requires complex AI calculations to develop the match without freezing the server or increasing latency.

Rust Engine: We use Rust to process complex moves instantly.

Interoperability

The Frontend (TypeScript), User Service (Node.js), and Game Engine (Rust) must exchange data without friction.

REST & JSON Standard: Strict use of standard HTTP protocols. The YEN notation acts as a universal data contract, avoiding language-specific binary formats.

Modifiability

The team needs to update the AI strategy without the risk of introducing errors into the User Login system.

Microservices: Strict separation of concerns. The Engine and User Service are isolated containers; changing one does not require recompiling or redeploying the other.

Usability

Players expect a fluid experience, similar to a native app, without page reloads during the game.

React SPA (Single Page Application): The interface loads once and updates dynamically. TypeScript ensures type safety, preventing runtime errors.

Robustness

A specific match causes a critical error due to an illegal state or server failure.

Stateless Design & Docker: Since the Rust engine saves no state, a request failure does not corrupt server memory. Docker allows immediate restarts without data loss (persistence is handled by Node.js).

Observability

Developers need to identify why a specific move took longer than expected or failed.

Prometheus & Grafana: Services expose technical metrics (e.g., calculation time). Grafana dashboards visualize this data in real-time to detect problems.

Portability

New developers need to spin up the project on different operating systems.

Docker Compose: All infrastructure is defined as code. A single command ("docker-compose up") replicates the production environment locally.

4.4. Organizational Decisions

To organize ourselves well and ensure work proceeds without issues, we have agreed upon the following team rules.

4.4.1. Code and Task Management (GitHub)

  • Main Branch (master): The master branch always contains the definitive and functional version of the project. We only add changes here when we are sure they work well.

  • Work Organization: We use GitHub Projects tools to assign work and see what remains to be done. This way, we all know what everyone is working on.

  • Meeting Documentation: We use the GitHub Wiki to store the minutes of our meetings. This creates a record of what we decide each week.

4.4.2. Quality Control

  • Code Reviews: To avoid errors, we have decided that no one can upload code to the main branch without another colleague reviewing it first.

  • Goal: This serves two purposes: avoiding silly mistakes and ensuring everyone understands everyone else’s code, so that no one becomes indispensable in a specific part of the application.

4.4.3. Communication

  • Weekly Meetings: We meet once a week (in person during laboratory classes) to see what progress we have made and plan the following week’s tasks. This is when we discuss important design decisions.

  • WhatsApp and Discord: We use these groups for quick day-to-day questions. If someone gets stuck programming, they ask for help here to solve it quickly without having to wait for the weekly meeting.

5. Building Block View

Content

The building block view shows the static decomposition of the system into building blocks…​

5.1. Whitebox Overall System (Level 1)

The following diagram shows the main interaction between the user and the system.

diagram
Motivation

Yovi (refering to our group game) is a web application that allows users to play the "Game of Y". The system acts as a single unit for the end user, providing registration, game logic, and history tracking.

Contained Building Blocks
Name Responsibility

User

End-user interacting with the application via a web browser.

Yovi System

The complete software solution handling the game logic and user data.

5.2. Level 2

This level shows the decomposition of the system into the three main services defined in the project structure.

diagram
Motivation

The system follows a modular architecture to separate the user interface from the logic services.

  • WebApp: Handles UI and client-side logic.

  • Users Service: Manages user registration and data.

  • GameY Engine: Handles the specific rules and logic of the board game.

Contained Building Blocks

Building Block Description

WebApp

Responsibility: Provides the graphical interface for the user. It communicates with the backend services to perform actions.
Technology: React, Vite, TypeScript.
Location: /webapp directory.

Users Service

Responsibility: Manages user registration and stores user information. It exposes a REST API.
Technology: Node.js, Express.
Location: /users directory.

GameY Engine

Responsibility: Implements the core logic of the Game of Y, including move validation and bot strategies using Rust for performance.
Technology: Rust.
Location: /gamey directory.

MongoDB

Responsibility: Database used to persist user data and game history.
Technology: MongoDB.

6. Runtime View

Contents

The runtime view describes concrete behavior and interactions of the system’s building blocks in form of scenarios from the following areas:

  • important use cases or features: how do building blocks execute them?

  • interactions at critical external interfaces: how do building blocks cooperate with users and neighboring systems?

  • operation and administration: launch, start-up, stop

  • error and exception scenarios

Remark: The main criterion for the choice of possible scenarios (sequences, workflows) is their architectural relevance. It is not important to describe a large number of scenarios. You should rather document a representative selection.

Motivation

You should understand how (instances of) building blocks of your system perform their job and communicate at runtime. You will mainly capture scenarios in your documentation to communicate your architecture to stakeholders that are less willing or able to read and understand the static models (building block view, deployment view).

Form

There are many notations for describing scenarios, e.g.

  • numbered list of steps (in natural language)

  • activity diagrams or flow charts

  • sequence diagrams

  • BPMN or EPCs (event process chains)

  • state machines

  • …​

Further Information

See Runtime View in the arc42 documentation.

This section displays sequence diagrams. These show the interaction of objects in different scenarios.

6.1. Game lifecycle against the computer

This diagram shows the game life cycle in its standard form (playing against the machine).

diagram

6.2. Bot against Application

This diagram shows the life cycle of the game in which a bot participates against the machine.

diagram

6.3. User registration

This diagram shows the different interactions that take place when a user registers.

diagram

7. Deployment View

Content

The deployment view describes:

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

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

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

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

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

Motivation

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

Form

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

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

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

Further Information

See Deployment View in the arc42 documentation.

7.1. Infrastructure Level 1

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

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

  • important justifications or motivations for this deployment structure

  • quality and/or performance features of this infrastructure

  • mapping of software artifacts to elements of this infrastructure

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

Overview Diagram

diagram
Motivation

Yovi is executed locally on a single host machine using Docker and Docker Compose. The system is deployed as a set of containers connected through a private Docker network ("monitor-net"). This deployment shows where each container runs and the main communication paths between them, including the monitoring stack (Prometheus and Grafana).

Quality and/or Performance Features

  • Modularity: each service is deployed as an independent container, allowing isolated development and replacement.

  • Portability: the deployment can be reproduced consistently on different machines that support Docker.

  • Observability: Prometheus and Grafana enable basic monitoring of the backend services.

  • Maintainability: the separation of responsibilities across containers simplifies troubleshooting and updates.

Mapping of Building Blocks to Infrastructure
Building Block Infrastructure Element

Terminal (User agent)

Runs on the client side and is used to execute commands that interact with the system.

WebApp

Container deployed on the Docker Host, connected to the internal Docker network.

Users Service

Container deployed on the Docker Host, connected to the internal Docker network.

GameY Service

Container deployed on the Docker Host, connected to the internal Docker network.

MongoDB

Container deployed on the Docker Host, connected to the internal Docker network.

Prometheus

Container deployed on the Docker Host, connected to the internal Docker network. Collects metrics from the services.

Grafana

Container deployed on the Docker Host, connected to the internal Docker network. Visualizes metrics queried from Prometheus.

7.2. Infrastructure Level 2

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

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

7.2.1. Docker Host (Localhost)

diagram

This diagram zooms into the Docker Host and the internal Docker network. All components are deployed as containers within the same private network, allowing direct communication between services. WebApp interacts with backend services (Users Service and GameY Service) using JSON messages. MongoDB stores persistent data. Prometheus and Grafana run alongside the services to provide basic monitoring and visualization.

7.2.2. Client (Terminal)

diagram

This diagram isolates the client-side element used during development/testing. The user executes commands via a terminal. Those commands generate requests toward the WebApp, which acts as the entry point to the deployed system.

7.2.3. Monitoring Stack (Prometheus + Grafana)

diagram

This diagram focuses on observability. Prometheus collects technical metrics exposed by the backend services. and stores them internally. Grafana queries Prometheus to display dashboards. This setup supports troubleshooting and performance monitoring during development.

8. Cross-cutting Concepts

Content

This section describes overall, principal regulations and solution ideas that are relevant in multiple parts (= cross-cutting) of your system. Such concepts are often related to multiple building blocks. They can include many different topics, such as

  • models, especially domain models

  • architecture or design patterns

  • rules for using specific technology

  • principal, often technical decisions of an overarching (= cross-cutting) nature

  • implementation rules

Motivation

Concepts form the basis for conceptual integrity (consistency, homogeneity) of the architecture. Thus, they are an important contribution to achieve inner qualities of your system.

Some of these concepts cannot be assigned to individual building blocks, e.g. security or safety.

Form

The form can be varied:

  • concept papers with any kind of structure

  • cross-cutting model excerpts or scenarios using notations of the architecture views

  • sample implementations, especially for technical concepts

  • reference to typical usage of standard frameworks (e.g. using Hibernate for object/relational mapping)

Structure

A potential (but not mandatory) structure for this section could be:

  • Domain concepts

  • User Experience concepts (UX)

  • Safety and security concepts

  • Architecture and design patterns

  • "Under-the-hood"

  • development concepts

  • operational concepts

Note: it might be difficult to assign individual concepts to one specific topic on this list.

Possible topics for crosscutting concepts
Further Information

See Concepts in the arc42 documentation.

8.1. Domain concepts

The domain model revolves around the game of Y, a connection strategy game.

  • GameY: The central entity representing a game session. It holds the state of the triangular board, tracks the current player, and validates rules. It uses a Union-Find data structure to efficiently detect winning paths (connected components touching all three sides) in real-time.

  • Player: A participant in the game. In this system, a player can be a human (via CLI) or an automated agent (Bot/LLM).

  • Board: A triangular grid where the game takes place.

  • Coordinates: A 3-dimensional coordinate system used to uniquely identify cells on the triangular grid.

  • Movement: Represents a player’s turn, which can be placing a piece at a specific point or performing a game action (for example, leaving).

  • Bot: An AI opponent. The architecture supports pluggable bot strategies, including random moves or integration with Large Language Models (LLMs).

8.2. Security

  • Input validation and sanitization: Since the main logic receives external data (via API or CLI), all inputs, especially coordinates and YEN notation strings, are strictly validated before processing to prevent invalid game states.

  • Server authoritativeness: The frontend (web or CLI) is simply a display layer, and the backend is the game engine. All checks for the legality of moves are applied by the backend to prevent cheating by modified clients.

8.3. Data persistence and exchange

The system uses a standardized text format for both transporting and storing game data. For persistent storage of application user data, MongoDB is used.

  • YEN Notation (Y Notation): The primary format for persisting game state and exchanging messages between subsystems (Web <→ Rust). It uses JSON to represent board size, player turns, and board layout.

  • Serialization/Deserialization: The system uses serde (in Rust) to strictly map the YEN JSON format to internal memory structures. This ensures that any saved game or network message can be reconstructed into a valid object at runtime.

  • Users Storage: MongoDB is employed to store user credentials and metadata. The system uses Mongoose schemas to define strict data types and validation rules, ensuring that invalid user data is rejected before reaching the database.

8.4. Architecture and Design Patterns

The core of the system uses established software engineering patterns to separate the logic from the implementation:

  • Strategy Pattern: Used for the AI ​​system. The YBot trait acts as a strategy interface, allowing different algorithms (Random, LLM) to be swapped at runtime via YBotRegistry without modifying the game logic.

  • State Machine: The game flow is modeled as a finite state machine represented by the GameStatus enumeration (e.g., Ongoing, Finished). Transitions are strictly controlled by the results of the moves.

  • Result Pattern: The system adopts a design where operations do not throw exceptions but rather return success or failure values as part of the normal flow. This forces the architecture to explicitly handle every possible outcome, eliminating "silent failures" and ensuring high reliability.

8.5. Error Handling and Logging

To ensure maintainability and a transparent user experience, the architecture includes a comprehensive monitoring layer:

  • Semantic Error Handling: Instead of generic server faults, the system maps internal exceptions to specific, domain-relevant categories (e.g., "Rule Violation," "Resource Unavailable"). This allows client applications to receive meaningful feedback and guide the user towards a solution.

8.6. User Interface and UX Concepts

  • Internal Logic: Uses 3D barycentric coordinates (x, y, z) to calculate adjacency and winning paths.

  • Visual/Input: Uses a linear index (0 to N) or a visual grid mapping for user interactions, simplifying the input process for humans while the backend converts them to 3D coordinates.

  • Feedback Loop: The user interface provides immediate feedback on the validity of the move based on the results returned by the core logic, ensuring that users understand why a move might be rejected (e.g., "Cell Occupied").

9. Architecture Decisions

Contents

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

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

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

Motivation

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

Form

Various options:

  • ADR (Documenting Architecture Decisions) for every important decision

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

  • more detailed in form of separate sections per decision

Further Information

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

Decision Reason

Microservices Architecture

We separated the application into decoupled services (users, gamey, webapp). This allows us to use the best technology for each specific problem (Rust for performance, Node.js for I/O) and enables independent development and deployment cycles.

React

We use React for the webapp frontend because it allows us to build fast, scalable, and easy-to-maintain interfaces using a component-based architecture.

TypeScript

Applied in the webapp to provide static typing. This reduces runtime errors, improves code readability, and enhances developer tooling compared to standard JavaScript.

Vite

Selected as the frontend build tool instead of Create React App (CRA) due to its superior performance in development server startup and Hot Module Replacement (HMR).

Node.js & Express

The users service handles I/O-heavy operations (REST API, database access). Node.js is ideal for this due to its non-blocking event-driven model, and Express provides a minimal and flexible framework.

Rust

The gamey engine requires high performance for game logic and bot calculations. Rust provides memory safety without a garbage collector and meets the project’s core requirements.

MongoDB & Mongoose

MongoDB is the persistence layer, deployed as an independent container. We use Mongoose (in users/src/database.js) to manage connections and schemas. The connection string is decoupled using the MONGODB_URI environment variable in .env, following the 12-Factor App methodology for config.

Docker & Docker Compose

Used to orchestrate the entire system. It defines independent containers for webapp, users, gamey, and the mongo database, linking them via an internal network. This ensures the environment is reproducible and eliminates configuration issues between development and production.

GitHub Actions

We use it for CI/CD pipelines to automatically build, test, and check the quality of the code on every push, ensuring continuous integration and early error detection.

SonarCloud & CodeScene

Integrated to monitor code quality, test coverage, and code health. This helps us manage technical debt and maintain architectural integrity over time.

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

diagram
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

Ref Attribute Source Stimulus Artifact Environment Response Measure Priority (Imp, Diff)

SC-01

Interoperability

Backend

Sends a move request in YEN format

Rust game engine

Normal operation (runtime)

The engine processes the string directly without data mapping adapters

Processing time < 50 ms

High, Low

SC-02

Modifiability

Developer

Wants to add a new AI strategy

Rust source code (AI module)

Design/Maintenance time

The new strategy is added by implementing an existing interface

0 lines of code modified in the main game engine

High, Medium

SC-03

Performance

User

Refreshes the webpage to resume a game

Complete System (Frontend + Backend + Rust)

Normal Operation

The system analyzes the YEN string and reconstructs the 3D board

Interaction Time < 200 ms

Medium, High

SC-04

Observability

Malicious User/Bot Error

Sends out-of-bounds coordinates (e.g., "Z: 99")

Server (Backend)

Normal Operation

The system logs the incident with context and returns a 400 error

The log includes GameID and the YEN string; Server uptime: 100% (no crashes)

Medium, Low

SC-05

Security

Cheater User

Sends a fake request claiming victory ("winner": true) without playing

Backend (Validation Logic)

Normal Operation

The server ignores the client data, checks the move history, and rejects the request

0% of corrupted games in the database; Server authority is maintained

High, Medium
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.

Risk Description

Inexperience in Microservices Architectures

The team has limited experience in designing large-scale software architectures with multiple interconnected modules. This introduces the risk of defining incorrect boundaries between services or creating circular dependencies that complicate development.

Rust learning curve

Rust is a language we’ve never used before, so the learning curve is going to be very steep. There’s a risk that implementing even simple features will take longer than expected due to the language’s complexity and our inexperience.

Inexperience in using Docker

Setting up internal networks, volumes, and container communication (with Node.js and Rust) can create deployment and configuration problems that delay integration testing or implementation.

Data Consistency

When using a database without a rigid schema, there is a risk of data inconsistency if the model evolves and data migrations are not performed to update older documents.
Technical debt Description

Non-persistent Game State

The current architecture manages active game sessions entirely in-memory within the Gamey Service. There is no real-time persistence layer for the game state (MongoDB is currently restricted to User management), meaning that any service restart or crash results in the immediate loss of all active matches.

Error Handling

Backend error handling is fundamental. The lack of a centralized logging and exception management strategy will hinder the diagnosis of problems in production.

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

Yovi

Web-based system that provides access to the “Game of Y” and related services (registration, gameplay, and history tracking).

Game of Y

Strategic connection board game supported by the system, played on a triangular board.

Micrati

Game development company that requested the development of the system.

User

Person interacting with the system to register, play games, and consult game information.

Web-based system

Application accessible through a web browser.

WebApp

Client-facing application that provides the graphical user interface and communicates with backend services.

Users Service

Backend service responsible for user registration and user-related data management, exposing a REST API.

GameY Engine

Core service implementing the rules and validation of the Game of Y, including bot strategies.

Frontend

Client-side part of the system responsible for the user interface and interaction.

Backend

Server-side part of the system responsible for game logic, user management, validation, and data access.

React

Frontend library used to build the user interface.

TypeScript

Typed superset of JavaScript used to implement the frontend.

Node.js

JavaScript runtime used to implement server-side services.

Express

Node.js framework used to build the user management REST service.

Rust

Programming language used to implement the core game engine to achieve high performance and reliability.

MongoDB

Database used to persist user data and game history.

REST API

HTTP-based interface exposing service endpoints to perform operations (e.g., user management and gameplay actions).

HTTP

Protocol used for communication between the client and the services, and between internal components.

JSON

Data interchange format used in HTTP requests and responses between system components.

Docker

Containerization platform used to package and run the system components in isolated environments.

Docker Compose

Tool used to define and run multi-container applications.

GitHub

Platform used for source code hosting and version control.

GitHub Actions

CI/CD solution used to automate workflows such as building, testing, and integration tasks.

CI/CD

Practices for continuous integration and continuous delivery/deployment, supporting automated build and testing pipelines.

YEN (Y-Game Extended Notation)

Standard notation used to represent game moves and game state for storage and exchange.

Serialization / Deserialization

Process of converting game state between in-memory structures and a transport/storage representation (e.g., JSON).

serde

Rust serialization framework used to map YEN JSON format to internal Rust data structures.

Union-Find

Data structure used to detect connected components and determine winning paths efficiently.

Bot

Automated player that interacts with the system via an API and performs moves according to a strategy.

LLM (Large Language Model)

Type of AI model that can be integrated as a bot strategy to generate moves or decisions.

Strategy Pattern

Design pattern enabling multiple interchangeable bot strategies through a common interface.

State Machine (FSM)

Model used to represent the game flow using explicit states and controlled transitions.

Result Pattern

Approach where operations return typed success/error results, requiring explicit error handling.

GameStatus

Enumeration representing the current state of a game (e.g., ongoing or finished).

GameYError

Enumeration representing typed error conditions produced by the game engine.

Input validation and sanitization

Security measure ensuring coordinates and notation strings are checked before processing to prevent invalid states.

Server authoritativeness

Principle where the backend enforces all rules and move legality to prevent client-side manipulation.

Structured logging

Logging approach that captures consistent, queryable event information for debugging and observability.

tracing

Rust instrumentation/logging library used to record events such as moves, errors, and state changes.

Prometheus

Monitoring component that collects health and technical metrics from services via HTTP endpoints.

Grafana

Visualization tool used to display dashboards based on metrics retrieved from Prometheus.

Observability

Ability to understand system behavior via logs and metrics (e.g., identifying errors, performance issues).

CLI (Terminal)

Command-line interface used as a manual control interface for executing commands and simulating user behavior.

3D barycentric coordinates (x, y, z)

Internal coordinate representation used to compute adjacency and winning paths on the triangular board.

Linear index

Simplified coordinate representation used for user interaction (e.g., indexing cells from 0 to N).

Deployment view

Architecture view describing how software building blocks are mapped to infrastructure elements.

Building Block View

Architecture view describing the decomposition of the system into building blocks and their responsibilities.

Sequence diagram

UML diagram representing the runtime interaction between components in a scenario.