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.

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 project that was proposed was implementing the "Game Y" (similar to the best-known board game "Hex"), all while mantaining a professional workflow simulating real life situations, covering all the aspects that could happen, these include:

  • Backend development

  • Frontend development

  • Management of the APIs

  • Overcome difficulties with new software

  • Quality control

If all of these are followed correctly the resulting project should go according to the theory.

1.1. Requirements Overview

  • The game will be available as a web application.

  • Players can register, log in, play matches, and have their results stored and accessible from their profile.

  • The game includes an AI opponent whose behavior depends on the selected difficulty, ranging from easy to hard.

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

Priority Quality Goal Scenario

1

Usability

A new player can register, log in, select a difficulty, and start a match against the bot in under 30 seconds without reading documentation.

2

Performance

For typical board sizes, bot move computation stays below 500 ms on "Hard" to keep gameplay fluid; worst cases must degrade gracefully (e.g., show a "thinking" state rather than freezing).

3

Maintainability

A new bot strategy or feature can be implemented and integrated in ⇐ 1 work day without breaking the existing frontend or any published API contract.

4

Security

Only authenticated users can submit results to their own profile; the system must prevent score spoofing attempts (e.g., forged results or manipulated game states).

5

Reliability

Game results are reliably persisted: at least 99% of save operations complete without data loss, and failures are reported explicitly (no silent loss).
Contents

The top three (max five) quality goals for the architecture whose fulfillment is of highest importance to the major stakeholders. We really mean quality goals for the architecture. Don’t confuse them with project goals. They are not necessarily identical.

Consider this overview of potential topics (based upon the ISO 25010 standard):

Categories of Quality Requirements
Motivation

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

Form

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

1.3. Stakeholders

Contents

Explicit overview of stakeholders of the system, i.e. all person, roles or organizations that

  • should know the architecture

  • have to be convinced of the architecture

  • have to work with the architecture or with code

  • need the documentation of the architecture for their work

  • have to come up with decisions about the system or its development

Motivation

You should know all parties involved in development of the system or affected by the system. Otherwise, you may get nasty surprises later in the development process. These stakeholders determine the extent and the level of detail of your work and its results.

Form

Table with role names, person names, and their expectations with respect to the architecture and its documentation.

Role/Name Contact Expectations

Project Sponsor (Micrati)

Company (Micrati)

Expects a working, publicly accessible web game with a clear architecture, documented APIs, and a deliverable aligned with the assignment scope and timeline.

Project Supervisor (Teacher)

Teaching Staff

Expects a professional development workflow, clean and documented code, and fulfillment of all functional requirements (bot + web application).

Development Team (Team)

Team members

Expect to learn new technologies (API management, frontend/backend), gain experience in professional workflows, and achieve a high grade.

End Users (Players)

Web

Expect a functional and entertaining game, a challenging bot difficulty, and the ability to save their progress reliably.

API Consumers (Bot developers / external clients)

Public API

Expect a stable and well-documented API contract, with clear error messages and examples.

Quality Assurance (Team / reviewers)

Team members

Expect the code to be testable and the game to be free of critical bugs before deployment.

2. Architecture Constraints

2.1. Technical Constraints

Constraint Background and/or Motivation

Web-based Access

The game must be accessible via a standard web browser (Chrome, Firefox, etc.) without requiring local installation.

Public Deployment

The application must be deployed and publicly accessible via the Web (academic delivery constraint).

Backend/Frontend Separation

The logic (APIs/services) and the presentation (UI) must be decoupled to keep clear client/server boundaries and enable independent development.

Bot Implementation

The system must include an algorithmic bot with selectable difficulty and/or multiple strategies (exact number of difficulty levels is not fixed).

Persistence

A database or persistent storage must be used to save player profiles and game history.

YEN notation (JSON messages)

Game state must be exchanged as JSON using YEN notation to ensure interoperability between modules.

2.2. Organizational Constraints

Constraint Background and/or Motivation

Team Structure

Work is divided among students acting as a full-stack development team, requiring clear communication and task management.

Deadline

The project must be completed and documented within the academic semester timeframe.

Technology adoption (learning curve)

The project requires using technologies that are new to the team (e.g., Docker, TypeScript, Rust), which may affect planning and delivery.

2.3. Conventions

Constraint Background and/or Motivation

arc42 Documentation

The software architecture must be documented using the arc42 template.

Version Control

Use of Git (e.g., GitHub or GitLab) is mandatory to track progress and manage collaborative code changes.

YEN notation

Use YEN notation in JSON messages whenever a game state is exchanged.
Contents

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

Motivation

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

Form

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

Further Information

See Architecture Constraints in the arc42 documentation.

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.

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 business context defines the external actors and how they interact with the YOVI system. The system exposes two public API surfaces (user management and game interaction) and delegates core game validation / bot move selection to the internal Rust engine.

Table 1. Communication Partners
Communication Partner Inputs Outputs

Human Player (Web client)

Registration/login, game actions (moves), game configuration

UI feedback, game state, personal profile and history

External Client (Public User API consumer)

Register/login, profile/history requests (JWT-based)

JWT tokens, user/profile/history data

External Client (Public Game API consumer)

Game requests (create/join room, play), board state in YEN/JSON when required

Game state updates, bot next move (when playing vs AI), error responses

Operator (Project team / admin role)

Service status queries (health) and basic operational requests

Service status information and basic diagnostics

3.1.1. Domain Interfaces

  • Web UI: React-based interface for end-user interaction.

  • Public User API: REST endpoints for registration/login and user profile/history.

  • Public Game API: REST endpoints to interact with the game (including playing against the bot using JSON/YEN).

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.

The technical context describes the protocols and communication channels between services and external clients.

3.2.1. Technical Interfaces and Channels

Table 2. Technical Interfaces and Channels
Interface Channel / Protocol Description

Frontend ↔ Webapp-backend

HTTP / REST

The React application (Vite) communicates with the Node.js backend using REST endpoints.

Frontend ↔ Webapp-backend (realtime)

WebSocket

Realtime channel used for gameplay/multiplayer events (when enabled).

Webapp-backend ↔ gamey (Rust engine)

HTTP / JSON (YEN)

The Node.js service delegates game validation and bot move computation to the Rust engine.

Webapp-backend ↔ users

HTTP / REST

Webapp-backend calls the users service for authentication/authorization and user-related operations.

External clients ↔ users

HTTP / REST

Public user management API (register/login/profile/history).

Users ↔ MariaDB

MariaDB protocol

Persistence of user data and credentials.

3.2.2. Mapping of Inputs/Outputs to Channels

  1. Access Management: Login/registration requests are handled by the Users service, which returns a JWT on success.

  2. Move Processing: Game flow uses REST and/or WebSockets from client to Webapp-backend; bot move/validation is delegated to gamey via HTTP using JSON/YEN.

  3. Persistence: User data and history are persisted in MariaDB via the Users service; additional persistence responsibilities are TBD (if introduced later).

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.

The architecture of the YOVI system follows a modular client/server approach that separates the user interface from backend services and the core game engine. This strategy supports maintainability and interoperability by keeping clear boundaries between UI, user management, and game logic. The system exposes public APIs for user management and game interaction, while the Rust game engine remains internal and focused on validation and bot move computation.

4.1. Technology decisions

The web client is implemented in TypeScript to enable fast development of an interactive UI using modern web frameworks. Backend services are implemented as HTTP APIs, and the game engine is implemented in Rust for performance and memory safety when running validation and search-based bot strategies. Inter-service communication uses JSON and the YEN notation as the game-state contract.

4.2. Quality Goal Realization

Correctness and reliability are improved by enforcing game rules and validating YEN/JSON game states in the Rust engine. Usability is addressed through a simple web-based flow (register/login/start game) and a clear UI. Performance is addressed by using a compiled Rust engine for the computationally intensive bot logic and by keeping service calls bounded (timeouts) to avoid hanging requests. Maintainability is supported by the separation into services (webapp-backend, users, gamey) and stable API contracts between them. Security is handled through JWT-based authentication and role-based authorization (player/admin) for protected operations.

4.3. Organizational decisions

The system is developed by a four-member team with shared responsibilities across the stack. Version control and issue tracking support collaborative work and code quality through reviews and automated checks.

5. Building Block View

Content

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

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

Motivation

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

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

Form

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

Hierarchy of building blocks

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

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

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

Further Information

See Building Block View in the arc42 documentation.

5.1. Whitebox Overall System

overview diagram

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.

Rationale

We applied functional decomposition to separate responsibilities within the YOVI system and keep clear client/server boundaries.

Contained Blackboxes
Building Block Description

Web Frontend

Browser-based TypeScript application. Renders the Y game board, handles user interaction, and communicates with the public APIs via REST (and WebSockets when realtime gameplay is enabled).

webapp-backend (Game API / BFF)

Node/TypeScript service exposing the public Game API (match flow, play actions, game-related statistics). Orchestrates calls to gamey using JSON/YEN and calls users when authentication/profile data is required.

users service (User API / Auth)

Service exposing the public User API (register/login/profile). Issues and verifies JWTs, applies basic authorization (roles), and is the only component that accesses MariaDB.

gamey (Rust engine)

Rust service responsible for validating game states and computing the next move. Uses YEN notation for board representation and exposes a minimal JSON-based web service interface to webapp-backend.

Database (MariaDB)

Persistent storage for user accounts and credentials/roles. Accessed exclusively by the users service.

Player (external)

Human user interacting through the Web Frontend to play matches and manage their account.

External client (external)

Any third-party client consuming the public APIs (User API and/or Game API) over HTTP, e.g., automated gameplay clients.

5.2. Level 2

level2 diagram

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. Level 2 - webapp-backend (Game API / BFF)

Building Block Description

Routes

Single entry point for the public APIs exposed by webapp-backend. Delegates game requests to MatchService and forwards authentication/profile operations to the users service.

MatchService

Encapsulates game workflow logic: creating matches/rooms, updating board states, and coordinating validation and next-move computations. Calls users only for authentication/profile data when required.

RustClient

HTTP client responsible for invoking the gamey service. Sends board state in JSON/YEN format to request validation or next-move suggestions.

5.2.2. Level 2 - users service (User API / Auth)

Building Block Description

Routes

Handles HTTP requests entering the User API. Delegates to UserService.

UserService

Business logic for authentication and user operations (issue/verify JWTs, profile management, role checks). Coordinates persistence via UserRepository.

UserRepository

Persistence component managing user accounts and credentials/roles (create, read, update, delete). Accessed exclusively via UserService.

5.2.3. Level 2 - gamey (Rust engine)

Building Block Description

Axum API

Minimal internal HTTP interface invoked by webapp-backend for validation and choose-move requests.

YENAdapter

Parses and serializes YEN/JSON game states and converts them to/from internal board representation.

Validator + Bot

Enforces game rules and computes next moves.

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.

The runtime view describes the behaviour and interactions of the system’s building blocks through selected scenarios. It captures how the TypeScript Web Application and the Rust Module cooperate to fulfill the requirements.

6.1. Human vs Computer Match

This scenario references the high-level requirement: Classic version of Game Y, player-vs-machine mode. It covers the logic when a human player makes a move on the board.

6.1.1. Quality Context

Source

Human Player

Stimulus

Selects a position on the board via the Web Frontend

Artifact

System (Web App + Rust Module)

Environment

Normal operation

Response

The move is validated, if the game ends the result is persisted, and the board is updated

Response Measure

The UI reflects the new state in less than 0.5 seconds

6.1.2. Interaction sequence

Registration Sequence

1. User selects a position on the board via the Web Frontend.

2. Web Application (TypeScript) sends a JSON message in YEN notation to the Rust Module to verify the move.

3. Rust Module verifies if the move is valid and if the match has ended.

4. Rust Module returns the result (Move valid/Match won/Match continues) to the Web Application.

5. If the game ended the Web Application updates the game state in the MariaDB database and reflects the new state in the Web Frontend anyways.

6.2. User Registration and History Consultation

This scenario references the high-level requirement: Users will be able to register and consult participation history. It describes how a user interacts with the system to manage their profile and view their match history.

6.2.1. Quality Context

Source

Human Player

Stimulus

Provides registration details via the Web Frontend

Artifact

System (Web App)

Environment

Normal operation

Response

Redirects the user to the game app and allows to view the match history

Response Measure

The UI reflects the new state in less than 0.5 seconds

6.2.2. Interaction sequence

registration
Figure 1. User registration
history
Figure 2. History consultation

1. User provides registration details through the Web Frontend.

2. Web Application (TypeScript) receives the request and validates the information with the data on the MariaDB database.

3. When the registered User requests their history, the Web Application queries the MariaDB database for the raw data.

4. The Web Application then calculates the history metrics and returns them to the Web Frontend for rendering.

6.3. Computer Strategy Execution

This scenario references the high-level requirement: The game against the computer must implement more than one strategy. It describes how the system suggests of executes a move for the computer.

6.3.1. Quality Context

Source

Human Player

Stimulus

Provides a computer difficulty level via the Web Frontend

Artifact

System (Web App + Rust Module)

Environment

Normal operation

Response

The GameEngine works with the strategy according to the difficulty level chosen

Response Measure

The UI reflects the new state in less than 1 seconds

6.3.2. Interaction sequence

Registration Sequence

1. Web Application (TypeScript) triggers a request for a computer move based on the user-selected difficulty/strategy.

2. The request is sent to the Rust Module containing the current board state in YEN notation.

3. Rust Module invokes the selected strategy algorithm to calculate the next move.

4. Rust Module suggests the next move via its Web Service Interface.

5. Web Application receives the move and performs the action.

6.4. External Bot Interaction

This scenario references the high-level requirement: API will enable a bot to play…​ a 'play' method will be exposed. It describes the interaction of an external bot with the YOVI system.

6.4.1. Quality Context

Source

External Bot

Stimulus

Invokes the API 'play' method providing a 'boardState' in YEN notation

Artifact

System (Web App + Rust Module)

Environment

Normal operation

Response

The system validates the input, processes game logic via the Rust module, and returns the result

Response Measure

The API returns the next move in YEN notation in less than 1 seconds

6.4.2. Interaction sequence

Registration Sequence

1. External Bot calls the 'play' method on the External API (Web Application).

2. The request includes a 'boardState' parameter, the board state in YEN notation.

3. Web Application forwards the state to the Rust Module for the best’s move calculation.

4. Rust Module returns the updated state/result to the Web Application.

5. Web Application returns the next move to the External Bot using YEN notation.

7. Deployment View

The deployment view describes the physical environment in which the YOVI system is executed and the automation processes that manage its lifecycle.

7.1. Infrastructure Level 1: Cloud Environment

The system is deployed on the Microsoft Azure cloud platform, using the "Azure for Students" subscription. A system with the following capabilities was deployed looking for a compromise between performance and cost:

  • Location: France Central

  • Operating System: Linux Ubuntu

  • Hardware Profile: Standard B2ats v2 (2 vCPUs, 1 GiB memory)

7.2. Infrastructure Level 2: Execution Environment (Docker)

The system follows a "Cattle" not "Pets" approach, using containerization to ensure consistency between development and production.

Container

Technology

Responsibility

Web Application

TypeScript / Node.js

Handles the UI, User sessions, and API requests.

Game Engine

Rust

Performs game logic validation and strategy suggestions.

Database

MariaDB

Persistent storage for users and match history.

Monitoring

Prometheus / Grafana

Observability of system health (Ports 9090/9091).

7.3. Network and Connectivity

The Virtual Machine is configured with a Public IP and specific inbound port rules as required by the project specifications:

  • Port 80/443: Public access to the Web Application.

  • Port 3000/4000: Internal service communication.

  • Port 22: Restricted SSH access for automated deployment.

  • Ports 9090/9091: Monitoring and metrics data.

7.4. Deployment Pipeline (CI/CD)

The system utilizes GitHub Actions for Continuous Deployment (CD). The process is triggered automatically when a new release is created or a version tag is pushed.

CI/CD Pipeline

  1. Automation: Configuration is stored as YAML files in .github/workflows.

  2. Artifact Management: Docker images are built and stored in the GitHub Container Registry (GHCR).

  3. Secrets Management: Sensitive data (IP addresses, SSH keys, DB passwords) are stored as GitHub Actions Secrets and injected into the environment at runtime.

7.4.1. Documentation Deployment

Following the "Documentation as Code" principle, our arc42 documentation is automatically built and published.

  1. Automation: A dedicated GitHub Action tracks changes in the docs/ directory.

  2. Build Process: The action executes npm install and npm run build to generate the HTML version of this arc42 documentation from the AsciiDoc source files.

  3. Publication:

    • The system uses the gh-pages npm package to automate the transfer of generated files.

    • The build result is pushed to the gh-pages branch of the repository.

    • The documentation is then hosted and accessible via GitHub Pages at the project’s public URL.

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. YEN - JSON Game State (domain contract)

Purpose

Represent the state of a Game Y match at a particular point of time. Domain contract between
webapp-backend ←→ gamey.

Format

The game state is serialized as JSON using YEN notation.

Example:
{
  "size": 4,
  "turn": "R",
  "players": [ "B", "R" ],
  "layout": "B/.B/RB./B..R"
}
Minimal invariants

  • size: integer > 0.

  • turn: must be a player ID from the players list.

  • players: an array holding player IDs, currently "B" and "R".

  • layout: string representation of the board, '/' is the separator and '.' represents an empty cell.

  • The system responds with a 4xx error for invalid states (see 8.2 / 8.2.1).

Compatibility

  • We only publish one version of the API as part of M1, and we’re not too concerned about backward compatibility.

  • Any breaking change must be reflected in the documentation and contract tests.

8.2. REST conventions

Scope

  • Applies to:

    • webapp-backend → frontend

    • webapp-backend → users

    • webapp-backend → gamey

Conventions

  • JSON as the default payload format.

  • HTTP status codes:

    • 2xx success, 4xx client/request/validation/auth error, 5xx internal/server error.

  • Timeouts and retries:

    • Calls to gamey/users must use finite timeouts.

    • Do not automatically retry non-idempotent operations (if any exist).

  • Recommended headers

    • Content-Type: application/json

    • Accept: application/json

8.3. Authentication and authorization

Scope

  • Applies to public endpoints exposed by users (authentication/user management) and to protected endpoints in webapp-backend (game interaction).

Authentication

  • users acts as the auth server: it issues JWTs and verifies them (HS256).

  • Clients send JWTs in Authorization: Bearer <token>; webapp-backend may also verify them when protecting endpoints.

Authorization

  • Role-based access control with roles: player and admin.

  • Default rule: a user can only access/modify their own data; admin-only operations (if any) require admin.

8.4. Backend for Frontend (BFF)

Principles

  • The frontend only consumes webapp-backend.

  • users and gamey are not accessible from the browser (no direct routing and no CORS exposure).

Motivation

  • Simplifies the frontend and centralizes auth and service composition in one place.

8.5. Development concepts

Rules

  • Trunk-based development with short-lived branches.

  • Changes reach trunk (master) only via Pull Request.

  • Mandatory checks before merge: at least 1 human approval + green CI.

  • Pull Requests are merged using squash merge to keep a linear history.

  • Merge without feature flags to prioritize simplicity.

8.6. User Experience (UX)

TBD

…​

8.7. Configuration and secrets

Rules

  • Environment-specific configuration is injected from the outside (e.g., environment variables in compose/CI).

  • Secrets (keys, tokens, passwords) are never committed to the repo and never baked into images; local dev uses a non-committed .env.

  • Do not log secret, mask if needed.

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.

9.1. ADR-001: BFF + internal services (REST)

Field Description

Status

APPROVED

Context

Browser-facing API should be centralized; system is split into webapp (frontend + backend), users, and gamey.

Decision

Use webapp-backend as a Backend-for-Frontend (BFF); the BFF calls users and gamey via REST.

Consequences

Browser talks only to BFF; orchestration and cross-cutting concerns (auth, validation, timeouts) are centralized.

9.2. ADR-002: Internal endpoints between BFF and gamey

Field Description

Status

APPROVED

Context

gamey provides core game logic (win verification + bot move selection); BFF must check health and request moves.

Decision

Expose a minimal internal HTTP API in gamey: GET /status (health), POST /ybot/choose/{botId} (YEN/JSON in, move out as JSON).

Consequences

Small, stable internal surface; requires consistent contracts for YEN and coordinate encoding.

9.3. ADR-003: YEN/JSON as game state contract + validation in gamey

Field Description

Status

APPROVED

Context

Game state must follow YEN notation; invalid states must be rejected.

Decision

Exchange game state as JSON following YEN; validate YEN in gamey and return a JSON error on invalid input.

Consequences

Single source of truth for domain validation; BFF maps validation failures to 4xx for clients.

9.4. ADR-004: Stateless engine + no game state persistence in M1

Field Description

Status

APPROVED

Context

M1 prioritizes end-to-end functionality; persisting full game states is out of scope for M1.

Decision

Keep gamey stateless; do not persist game state in M1.

Consequences

Each request must carry full required state; simpler deployment/testing for M1.

9.5. ADR-005: API versioning

Field Description

Status

NOT APPROVED

Context

Breaking changes may happen; a versioning policy was proposed early.

Decision

(Not approved) URL-based versioning and “major bump rules” are not decided yet; avoid committing to /v1 paths until requirements stabilize.

Consequences

No premature coupling to a versioning scheme; versioning can be introduced later (or via headers) if needed.

9.6. ADR-006: JWT signing algorithm

Field Description

Status

APPROVED

Context

The users service acts as the auth server: it issues tokens and also verifies them; the webapp (BFF and/or frontend) receives tokens and may verify them when needed.

Decision

Use HS256 for JWT signing/verification (shared secret) for M1.

Consequences

Simple setup and fast verification; secret must be protected across components that verify tokens.

9.7. ADR-007: Secrets/config injection mechanism

Field Description

Status

APPROVED

Context

Secrets must not be stored in git; configuration must work locally and in CI/CD.

Decision

Use environment variables for configuration; store sensitive values as GitHub Actions Secrets and inject them into the deployment as env vars; local dev uses dotenv (.env not committed).

Consequences

Consistent secret values across deployments; requires discipline to avoid leaking env values in logs.

9.8. ADR-008: Error response envelope

Field Description

Status

APPROVED

Context

Multiple services/clients need consistent error handling.

Decision

Standardize JSON error responses with: errorCode, message, requestId.

Consequences

Simpler client-side mapping and debugging; requires stable error codes over time.

9.9. ADR-009: BFF → Game Service timeouts

Field Description

Status

PROPOSED

Context

Bot computation and network calls may be slow/fail; BFF must stay responsive.

Decision

Apply timeouts for BFF → gamey requests; allow strictly bounded retries only for safe idempotent operations.

Consequences

Prevents hanging requests; retries must be conservative to avoid overload during outages.

9.10. ADR-010: User persistence and minimal user entity

Field Description

Status

APPROVED

Context

users must persist accounts; we need credentials and basic authorization.

Decision

Persist user accounts; minimal user entity includes: id, username, email, passwordHash, role (player/admin) (extra fields TBD).

Consequences

Enables authentication and basic admin features; requires clear password hashing rules and role-based authorization checks.

9.11. ADR-011: Client/Server entrypoint and public APIs

Field Description

Status

APPROVED

Context

Client/server architecture: browser client (SPA) calls server APIs over HTTP; we want a single public entrypoint.

Decision

Expose: / for the SPA, plus two public API surfaces: one for user management (register/login/profile/history) and one for game interaction (create/join room, play, etc.); exact path prefixes are stable but versioning is not decided.

Consequences

Clear boundaries between “user management” and “game” concerns; simpler documentation and security rules per API.

9.12. ADR-012: Reverse proxy for path-based routing (Nginx)

Field Description

Status

PROPOSED

Context

Single public port must serve the SPA and route requests to backend APIs; full API gateway is overkill.

Decision

Use Nginx to route by path: / → SPA static assets, /api/…​ → BFF (covering both public APIs), optional /ws/…​ → BFF for WebSockets; no API version prefix is assumed.

Consequences

One clean entrypoint with simple routing rules; adds a lightweight component to configure and maintain.

10. Quality Requirements

Content

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

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

Motivation

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

Further Information

See Quality Requirements in the arc42 documentation.

10.1. Quality Tree

Content

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

Motivation

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

Form

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

  • tree-like refinement of the term "quality". Use "quality" or "usefulness" as a root

  • a mind map with quality categories as main branches

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

quality tree horizontal

10.2. Quality Scenarios

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.

This section makes quality requirements concrete through a quality tree and measurable scenarios, referencing the quality goals defined in section 1.2 Quality Goals where applicable. The quality-attribute taxonomy follows ISO/IEC 25010 (product quality: usability, performance efficiency, reliability, security, maintainability, compatibility, portability, etc.). The YOVI system consists of a TypeScript web application and a Rust module exposed via a web interface, communicating through JSON messages and YEN notation to represent game states.

Scenarios make quality requirements precise by stating stimulus, response, and measurable criteria (usage scenarios and change scenarios).

ID Type Stimulus Response Measure / Acceptance criteria

QS-01 (Fast start)

Usage

A new player accesses the web application for the first time.

They can register, log in, and start a game against the bot.

Completes the flow in < 30 s without needing a manual (quality goal 1).

QS-02 (Playable UI)

Usage

A player starts a game and makes a move.

The UI responds without noticeable blocking and reflects the new state.

Main interaction (render + local confirmation) does not exceed 500 ms on the client (TBD: might measure in the future).

QS-03 (API latency without Rust)

Usage

A standard REST request to the Node/Express backend (e.g., login/profile) that does not require Rust computation.

The system responds with the result.

p95 ⇐ 50 ms for ~10 concurrent users (internal target).

QS-04 (Rust healthcheck)

Usage

The backend invokes the Rust service health-check endpoint.

It receives OK/FAIL and can degrade functionality if FAIL.

p95 ⇐ 50 ms.

QS-05 (Choose-move latency by board size)

Usage

A player/bot requests “choose next move” from the Rust module (Random strategy or Minimax with alpha-beta + iterative deepening).

The service returns a valid move in the expected format.

  • “Hard” target (board size 4-12): p95 ⇐ 500 ms (quality goal 2).

  • “Hard” target (board size 13-16): p95 ⇐ 3000 ms, and the UI shows a “thinking…” state without blocking the session.

  • Note: these thresholds will be validated with real measurements (not fully measured yet).

QS-06 (Add bot strategy in 1 day)

Change

A new bot strategy or difficulty adjustment is added to the Rust module.

The feature is integrated without breaking the frontend or API contracts.

Effort ⇐ 1 work day, and the /play endpoint contract remains compatible (quality goal 3).

QS-07 (Extend board size)

Change

Board-size support is extended/refactored within the allowed range.

The change does not require rewriting the UI or persistence layer.

Localized changes and updated tests; the YEN/JSON format is not broken.

QS-08 (Persist match result)

Usage

A game ends and the result is saved to MariaDB.

The result is persisted and appears in the user’s history.

99% of save operations without losing the result (quality goal 4); on failure, an explicit error is returned and no match is “confirmed” as saved when it was not.

QS-09 (Service degraded availability)

Usage

The VPS suffers downtime/restarts (low availability, short-lived operation).

The system becomes operational again after restart, even if live sessions are lost.

Service recovers after restart (TBD: ⇐ 5 min) and keeps already persisted data (no backups).

QS-10 (Authenticated score submission)

Usage

An unauthenticated user tries to submit a score/result or access private data.

The backend rejects the operation.

Only authenticated users can submit scores to their own profile (quality goal 5).

QS-11 (Score spoofing)

Usage

An authenticated user attempts to forge results: submit results without having played, manipulate the state/input (e.g., YEN) to obtain an illegitimate score.

The backend validates consistency and rejects the operation.

“Score spoofing” is prevented for those two scenarios (quality goal 5); replay © will be addressed when a global scoring system exists.

QS-12 (Anti-abuse / rate limiting)

Usage

A malicious client attempts brute force / spam against server-side “users” endpoints.

The system limits and logs the abuse.

Rate limiting enabled (TBD: thresholds per IP/user) and security-event logs.

QS-13 (Documented external API)

Usage

A third party implements a bot using the public API.

They can integrate without reverse engineering.

API is “fully documented” (OpenAPI/Swagger + examples) as required by the assignment.

QS-14 (Observability)

Usage

An error occurs in a match (Node or Rust) or latency increases.

The team diagnoses the issue using metrics/logs.

Minimum metrics (p95 latencies, error rate, Rust health) and logs with correlation-id (TBD implementation).

QS-15 (Arc42 + ADR quality)

Change

Team reviews the architecture and decisions.

They can trace decisions and quality attributes.

Clear documentation (complete arc42) and relevant decisions recorded (e.g., ADR) per evaluation criteria.

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.

This section lists identified technical risks and technical debts, ordered by priority. Risk management enables proactive decision-making and informs stakeholders (project managers, teaching staff) about architectural concerns.

11.1. Technical Risks

ID Priority Impact Mitigation

R-01 (Minimax algorithm does not scale beyond board size 11)

HIGH

The current Minimax implementation (alpha-beta + iterative deepening) cannot handle boards of size 11+ within acceptable time limits; this limits the "variable board size" requirement.

  • Option A: Cap maximum board size to 10 for "Hard" difficulty.

  • Option B: Optimize algorithm (transposition tables, better move ordering) or reduce search depth for larger boards.

  • Option C: Add time-limit cutoff and return best move found so far; display "thinking…​" state to user.

R-02 (Rust service failure blocks gameplay)

HIGH

If the Rust module (win verification + move suggestion) becomes unavailable, players cannot continue games against the bot.

  • Implement a fallback mode: automatically switch to local player-vs-player with a clear notification ("Bot unavailable; multiplayer mode enabled").

  • Add health-check monitoring and alert if Rust service is down.

  • Ensure graceful degradation rather than complete system failure.

R-03 (WebSocket technology adoption unproven)

HIGH

The team has not tested WebSocket integration for real-time multiplayer; lack of experience increases risk of incomplete implementation or bugs.

  • Spike/prototype WebSocket basics early (by sprint N, TBD).

  • Allocate buffer time for debugging connection issues and state synchronization.

  • Fallback: if WebSocket multiplayer is not ready, prioritize player-vs-bot and consider multiplayer optional.

R-04 (Lack of observability in production)

HIGH

Without metrics and correlation-based logging, diagnosing errors or performance issues in the deployed VPS will be difficult.

  • Implement basic structured logging with correlation-id (request tracing across Node ↔ Rust).

  • Add minimal metrics (error rate, p95 latencies, Rust health) using a lightweight tool (e.g., Prometheus + Grafana, or simpler: logs + parsing scripts).

  • Allocate time for this before final deployment.

R-05 (Team inexperience with stack)

MEDIUM

The team is relatively inexperienced with the chosen stack (React/Node/Rust), which may slow development and increase bug rate.

  • The team has sufficient time to learn (academic project schedule).

  • Pair programming and code reviews help share knowledge.

  • SonarQube enforces quality standards and catches common mistakes (see TD-01).

R-06 (Scope creep from optional features)

MEDIUM

The assignment includes many optional features (variants, i18n, mobile, undo, hints, etc.); the team has not yet decided which to implement, risking overcommitment.

  • Finalize scope early: prioritize 1–2 optional features aligned with grading criteria (e.g., one Game Y variant + leaderboard).

  • Avoid starting optional features until core requirements (player-vs-bot, API, user management) are stable and tested.

R-07 (Documentation contains TBD sections)

MEDIUM

Arc42 documentation is up-to-date and API documentation is exhaustive, but some sections still contain "TBD" placeholders.

  • Schedule a documentation review sprint before final delivery.

  • Assign owners to close remaining TBDs (e.g., finalize ADRs, update deployment diagrams).

11.2. Technical Debt

ID Debt Impact / Plan

TD-01 (SonarQube slows development velocity)

SonarQube quality gates are enabled and catch issues early, but they slow down the development workflow (additional checks, required fixes before merge).

  • Impact: Reduced short-term velocity, but higher long-term code quality and fewer bugs.

  • Plan: Accept this trade-off; SonarQube prevents accumulation of worse technical debt (poor code, security issues).

  • Consider adjusting thresholds if checks become overly strict for the project scope.
Test coverage is currently >= 80% across the codebase, which is acceptable. Score spoofing validation is implemented in the Rust module (validates YEN state integrity server-side). CI/CD pipeline for deployment is already operational. Rate limiting is not prioritized (low risk in academic/closed project context). VPS availability is low (cheap Azure instance, no backups), but this risk is accepted given the academic scope.

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

Further Information

See Glossary in the arc42 documentation.

Term Definition

YOVI

System name: a web-based platform to play Game Y through a browser and public APIs.

Game Y

Board game implemented by the system, including a player-vs-bot mode.

Micrati

Company behind the project in the assignment context (project sponsor).

Web Frontend

Browser-based TypeScript SPA that renders the board UI and interacts with backend APIs via HTTP (and WebSockets when enabled).

SPA (Single-Page Application)

Web application that loads once and updates the UI dynamically by calling backend APIs.

webapp-backend

Backend that exposes the public Game API and acts as orchestration layer (BFF) towards internal services (notably gamey) and the users service.

BFF (Backend for Frontend)

Pattern where a single backend endpoint is tailored to a specific frontend, centralizing orchestration and cross-cutting concerns.

users (service)

Service responsible for authentication and user management, exposing the public User API (e.g., register/login/profile) and persisting user data in MariaDB.

User API (Public User API)

Public HTTP API surface for user management (register/login/profile) provided by the users service.

Game API (Public Game API)

Public HTTP API surface for game interaction (match flow/play actions) provided by webapp-backend.

gamey (Rust engine)

Internal Rust service that validates game states and computes bot moves; invoked by webapp-backend via HTTP using JSON/YEN.

YEN

Notation used to represent a Game Y state (board size, players, turn, and layout), exchanged as JSON between services.

YEN/JSON game state

JSON payload that encodes the game state following YEN; invalid states must be rejected by the engine.

JSON

Default payload format used in the system APIs and service-to-service communication.

REST

HTTP-based style used for request/response APIs in the system.

WebSocket

Bidirectional communication channel used for realtime gameplay/multiplayer events when enabled.

JWT (JSON Web Token)

Token format used for authentication; clients send it via Authorization: Bearer <token>.

HS256

HMAC-SHA256 algorithm used to sign/verify JWTs using a shared secret.

Authentication

Process of proving identity (who a user/client is), handled by the users service via JWT issuance/verification.

Authorization

Process of deciding permissions (what a user can do), implemented as role-based checks (e.g., player/admin).

Role (player/admin)

User permission label used for authorization decisions.

MariaDB

Relational database used by the users service to persist user accounts and credentials/roles.

ADR (Architecture Decision Record)

Short document describing an important architectural decision, its context, and consequences.

arc42

Software architecture documentation template used to structure this documentation (sections 1–12).

M1

First milestone focused on end-to-end functionality.

Error envelope

Standard JSON structure for error responses using errorCode, message, and requestId.

requestId

Identifier included in error responses to correlate client-visible failures with server-side logs/traces.