arc42 yovi_es4b

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

YOVI is an online game based on Game Y, an abstract strategy board game described by John Milnor in the 1950’s and indepently invented in 1953 by Craige Schensted and Charles Titus.
The game is normally played on a triangular board by two players, whose goal is to connect the three sides of the board with an unbroken chain of their pieces.
YOVI is a modern implementation of Game Y, which allows players to play against bots of varying dificulties, against other players locally or online. It also features a login system, allowing it to log accounts' stats.

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

  • underlying business goals,

  • essential features,

  • essential functional requirements,

  • quality goals for the architecture and

  • relevant stakeholders and their expectations

1.1. Requirements Overview

  • User registration and login system

    • Allow users to create accounts and log in securely

  • Game modes

    • Single-player mode against AI opponents of varying difficulties

    • Local multiplayer mode for two players on the same device

    • Online multiplayer mode for players to compete against each other over the internet

  • Game mechanics

    • Implement the rules of Game Y accurately

    • Provide an intuitive and responsive user interface for gameplay

    • Provide custom game settings (e.g., board size, time limits, game variants)

  • Account statistics

    • Track and display players' game statistics, such as wins, losses, and games played

  • Bot opponents

    • Develop AI opponents with varying levels of difficulty and different strategies to provide a challenging gaming experience for players of all skill levels

  • API

    • Provide an API that allows bots to retrieve their game statistics, enabling them to track their progress and performance over time

    • Provide an API that allows bots to play against the game, enabling developers to create their own bots and integrate them into the game

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

Description

1

Robustness

The game should be able to handle unexpected inputs and situations without crashing or producing incorrect results. This includes handling invalid moves, network interruptions, and other unforeseen circumstances gracefully.

2

Usability

The game should have an intuitive and user-friendly interface that allows players to easily navigate through menus, understand game mechanics, and enjoy a seamless gaming experience.

3

Performance

The game should run smoothly with minimal latency, especially in online multiplayer mode, to ensure a responsive and enjoyable gaming experience for all players.

4

Compatibility

The game should be compatible with any type of device that has a web browser, including desktops, laptops, tablets, and smartphones, to reach a wide audience of players.

5

Security

The game should implement robust security measures to protect user data and prevent unauthorized access, especially in the context of user accounts and online multiplayer interactions.
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

Form

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

Role/Name Contact Expectations

Development Team

Julián Fernández Herruzo (UO300199@uniovi.es)
Fernando Begega Suarez (UO295286@uniovi.es)
Rodrigo García López (UO300548@uniovi.es)
Adrian Burguet Diego (UO294819@uniovi.es)

Responsible for implementing and designing the architecture, ensuring that it meets the specified requirements and quality goals.

Micrati

N/A

Interested in the successful development and deployment of the game, as well as its commercial success. They also specify some requirements or constraints that need to be considered during the architectural design process, such as the chosen language (Rust)

Players

N/A

Expect a fun and engaging gaming experience, with a user-friendly interface, smooth performance, and challenging gameplay. They also expect regular updates and improvements to the game based on their feedback.

2. Architecture Constraints

2.1. Technical Constraints

Constraint

Description

Languages

Front-end: TypeScript (React). Game engine: Rust.

Communication format

JSON using the YEN notation for game states and moves.

Public API

Must implement an API for bots to interact with the game, and view users stats.

Deployment

Application must be deployable and publicly accessible through the internet.

Testing

Unit, integration and end-to-end test.

Security

Authentication for users with a secure login mechanism.

Stored data

User data and game states must be stored persistently in a database.

2.2. Organizational Constraints

Constraint

Description

Documentation

Use arc42 template for documentation of the application. The documentation must be publicly accessible and updated regularly.

Development time

The application should be developed by the end of the semester.

Github repository

Use a shared GitHub repository for version control and collaboration.

Meetings

At least one meeting per week to discuss progress, challenges and next steps. Every meeting must be documented.

2.3. Conventions

Convention

Description

Code style & linting

Follow existing project style for TypeScript and Rust.

Version control

Use of "main" branch for stable code releases; feature branches for development. Use pull requests and code review before merging.
Contents

Any requirement that constrains architects' freedom of design and implementation. These can be technical, organizational, or conventional and may be negotiable.

Motivation

Architects should know where they have freedom and where they must adhere to constraints.

Form

Short tables and paragraphs describing constraints, rationale and impact.

Further Information

See Architecture Constraints in the arc42 documentation.

3. Context and Scope

This section describes the system boundary: the communication partners (users and external systems), the domain-level inputs and outputs, and the technical channels used for interaction. It separates business context (who interacts with the system and what domain information is exchanged) from technical context (protocols, ports, and runtime deployment aspects).

Motivation: clear context and scope prevent misunderstandings about responsibilities, interfaces, and deployment requirements. === Business Context

diagram name

3.1. Elements Description

  • Player: The end-user who interacts with the system through a web browser to play games and view statistics.

  • Administrator: Responsible for managing users and monitoring the system.

  • Bot: An automated agent that can interact with the game engine to play games and view user stats.

  • WebApp: The front-end application built with React and Vite, serving the user interface and handling user interactions.

  • Users: The back-end service responsible for user authentication and management, built with Node.js.

  • Gamey: The game engine and bot service implemented in Rust, responsible for game logic and interactions with bots.

  • DB: The database used to persist user data and games.

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.

The title of the table is the name of your system, the three columns contain the name of the communication partner, the inputs, and the outputs.

3.2. Technical Context

diagram name

3.2.1. Elements Description

Contents

Technical interfaces (channels and transmission media) linking the 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.

Participants Input/Output Channel/Protocol

Player (Browser)

Web navigation, gameplay actions, requests to the frontend

HTTPS (via Reverse Proxy) / HTTP (dev 5173)

Administrator

Administration actions, user management requests

HTTPS (Users API)

External Bot

Game actions, statistics queries, automated gameplay

HTTPS JSON (Gamey API)

Reverse Proxy (nginx)

Incoming HTTP/HTTPS traffic, routing to internal services

HTTPS externally / HTTP internally

WebApp (React + Vite + TypeScript)

User interactions, REST API calls to Users and Gamey

HTTP (internal REST)

Users (Node.js + Express)

Authentication, user management, metrics endpoint

HTTP (internal REST) / TCP (database driver)

Gamey (Rust Engine + Bot Service)

Game logic, bot API, metrics endpoint

HTTP (internal REST) / TCP (database driver)

Database (Postgres / Mongo)

Storage of users, game sessions, statistics

SQL/NoSQL over TCP

Prometheus

Metrics scraping from Users and Gamey

HTTP (/metrics)

Grafana

Dashboard visualization, queries to Prometheus

HTTP (host port 9091 → container port 3000)

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.

This section summarizes the architectural decisions that guide the system and explains how they support the main quality goals.

4.1. 4.1 Technology Decisions

  • Frontend: React + TypeScript.

    Reason: fast development, maintainability through static typing, and a broad ecosystem.

  • Application Backend: Node.js + Express (with TypeScript in the application layer where applicable).

    Reason: agile REST API development and a mature ecosystem.

  • Game Engine Service: Rust + Axum.

    Reason: alignment with assignment constraints and clear separation of game-domain logic in a specialized service.

  • Containerization: Docker + Docker Compose.

    Reason: reproducible environments and consistent service integration.

  • Monitoring: Prometheus + Grafana.

    Reason: baseline observability through service-level metrics.

  • Deployment Target: Azure.

    Reason: academic availability and prior team experience.

4.2. 4.2 Top-Level Decomposition Decision

The architecture is decomposed into four main building blocks:

  1. Webapp (Frontend)

    Responsibility: user interaction and game state visualization.

    Architectural role: system client.

  2. Users Service (Application API)

    Responsibility: public API, user/game/history management, and use-case orchestration.

    Architectural role: single entry point for frontend clients.

  3. Gamey Service (Game Engine)

    Responsibility: move validation, game rules, and bot move calculation.

    Architectural role: internal domain service invoked by Users Service.

  4. Persistence Layer (Database)

    Responsibility: storage of users, matches, statistics, and history.

    Architectural role: persistence dependency used by Users Service.

4.2.1. Communication Between Subsystems

Communication follows the pattern Webapp → Users Service → Gamey Service.

  • Webapp → Users Service: HTTP/REST + JSON (public API).

  • Users Service → Gamey Service: HTTP/REST + JSON (internal domain API).

  • Users Service <→ Database: persistence operations.

The Users → Gamey interaction is synchronous for move validation/calculation, and the backend returns a normalized game state to the frontend.

4.3. 4.3 Decisions to Achieve Quality Goals

Quality Goal Architectural Decision

Usability

React UI with straightforward navigation, clear loading/error feedback, and input validation.

Performance

Critical game logic isolated in Gamey (Rust), with a lightweight application API in Users.

Testability

Unit tests per service, integration tests across services, and E2E tests for key user flows.

Maintainability

Clear separation of responsibilities (webapp, users, gamey), explicit API contracts, and CI with linting and tests.

Availability and Reliability

Containerized execution, baseline monitoring with Prometheus/Grafana, and cloud deployment strategy.

4.4. 4.4 Organizational Decisions

  • Central GitHub repository for source code and collaboration.

  • Task tracking and technical discussion through GitHub Issues.

  • Periodic team meetings for progress review and task distribution.

  • Decision and meeting traceability through documented records (e.g., team wiki).

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

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.

General View - System Boundary
Motivation

This first view shows the system at its highest abstraction level. It defines the system boundary (Yovi) and the external actor (Usuario) before introducing internal decomposition. This helps stakeholders understand scope and ownership before going into technical details.

Contained Building Blocks

  • Yovi: Main system boundary that contains the application internals, detailed in the next levels.

Important Interfaces

  • Usuario → Yovi: Primary interaction interface between the end user and the system.

Insert your explanations of black boxes from level 1:

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

Name Responsibility

<black box 1>

 <Text>

<black box 2>

 <Text>

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

5.1.1. Yovi

System boundary that provides gameplay capabilities to the user and is internally decomposed in the following levels.

5.2. Level 2

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

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

5.2.1. White Box Yovi

…​describes the internal structure of building block 1.

Level 2 - Yovi Main Decomposition
Motivation

Level 2 decomposes Yovi into its main runtime building blocks while keeping implementation details hidden. This view clarifies responsibilities between presentation, backend logic, and persistence.

Contained Building Blocks

  • WebApp: Frontend used by the player for interaction.

  • Backend: Server-side component that exposes business operations.

  • BBDD: Persistent storage used by backend services.

Important Interfaces

  • Usuario → WebApp: User interaction interface.

  • WebApp → Backend: HTTP/JSON application interface.

  • Backend → BBDD: Persistence access interface.

5.3. Level 3

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

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

5.3.1. White Box Backend

Specifies the internal structure of building block x.1.

Level 3 - Backend Internal Decomposition
Motivation

Level 3 details the internal structure of the backend component. It isolates the key business services and their collaboration for user and gameplay operations.

Contained Building Blocks

  • User: Service responsible for user-related operations.

  • Gamey: Service responsible for game engine and game logic.

  • BBDD: Shared persistence component used by backend services.

Important Interfaces

  • User ←→ Gamey: Internal service-to-service interface for game/user data exchange.

  • User → BBDD: User data persistence interface.

  • Gamey → BBDD: Game state persistence interface.

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.

6.1. Login

runtime login

  • Escenario de autenticacion de usuario.

  • WebApp se comunica directamente con User para autenticar.

  • User usa BBDD para comprobar los datos del usuario.

6.2. Jugar partida

runtime play game

  • Escenario principal de ejecucion de juego.

  • Gamey encapsula la logica de partida.

  • El estado de la partida se persiste en BBDD.

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.

The system is deployed as a distributed, container-based architecture. It consists of independent services communicating over HTTP and running within isolated container environments.

The deployment view describes the technical infrastructure required to execute the system and the mapping of software building blocks to infrastructure elements.

The following diagram shows the high-level deployment structure in a local environment using containerization. <Overview Diagram> @startuml node "User Device" { component "Web Browser" }

node "Docker Host" {

node "Docker Network" {
node "Webapp Container\n(React + Vite)" {
  component "SPA Frontend"
}
node "Users Service Container\n(Node.js + Express)" {
  component "Users REST API"
}
node "Gamey Container\n(Rust Engine)" {
  component "Game Engine API"
}
node "Database Container" {
  database "User Database"
}
  }
}

"Web Browser" -→ "SPA Frontend" : HTTP "SPA Frontend" -→ "Users REST API" : HTTP /createuser "SPA Frontend" -→ "Game Engine API" : HTTP "Users REST API" -→ "User Database" : DB connection

@enduml

Motivation

The deployment structure is based on containerized services to ensure:

  • Clear separation between frontend, backend, and game engine.

  • Independent deployment and scalability of each service.

  • Reproducible development environments.

  • Isolation of runtime dependencies.

A database component has been introduced to persist user data, enabling real user registration and long-term storage.

Quality and/or Performance Features

  • Scalability: Services can be scaled independently in future production environments.

  • Isolation: Each component runs in its own container.

  • Loose Coupling: Communication occurs via well-defined HTTP APIs.

  • Persistence: User data is stored in a dedicated database component.

  • Portability: The system can run on any infrastructure supporting containerization.

  • Maintainability: Clear separation of concerns reduces system complexity.

Mapping of Building Blocks to Infrastructure

| Building Block | Infrastructure Element | | ---------------------- | -------------------------------------------- | | React SPA (Webapp) | Webapp Container | | User Management Logic | Users Service Container | | User Persistence Layer | Database Container | | Game Core & Bots | Gamey Container | | Client Interface | Web Browser | | Communication | Docker Internal Network (HTTP + DB protocol) |

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.

This level provides a more detailed view of selected infrastructure elements.

7.2.1. <Webapp Container>

@startuml node "Webapp Container" { component "React SPA" component "UI Components" component "API Client Module" }

node "External Services" { component "Users REST API" component "Game Engine API" }

"React SPA" -→ "UI Components" "React SPA" -→ "API Client Module" "API Client Module" -→ "Users REST API" : HTTP "API Client Module" -→ "Game Engine API" : HTTP

@enduml

The Webapp container:

  • Hosts a Single Page Application built with React.

  • Handles all user interactions.

  • Communicates with backend services via HTTP.

  • Does not maintain persistent state.

  • Acts as the primary system entry point.

7.2.2. <Users Service Container>

@startuml node "Users Service Container" { component "Express Server" component "User Controller" component "User Service" component "Persistence Layer" }

node "Database Container" { database "User Database" }

"Express Server" -→ "User Controller" "User Controller" -→ "User Service" "User Service" -→ "Persistence Layer" "Persistence Layer" -→ "User Database"

@enduml The Users Service container:

  • Exposes REST endpoints (e.g., /createuser).

  • Implements business logic for user registration.

  • Contains a persistence layer responsible for storing user data.

  • Connects to an external database container.

  • Ensures separation between API layer, business logic, and data access.

7.2.3. <Gamey Container>

@startuml node "Gamey Container" { component "Web API" component "Game Core" component "Bot Engine" component "Notation Module" }

"Web API" -→ "Game Core" "Game Core" -→ "Bot Engine" "Game Core" -→ "Notation Module"

@enduml

The Gamey container:

  • Hosts the Rust-based game engine.

  • Encapsulates all core game logic.

  • Provides bot functionality.

  • Exposes a Web API for interaction with the frontend.

  • Does not directly depend on the user database.

Gamey remains logically independent from user management.

7.2.4. <Database Container>

@startuml node "Database Container" { database "User Database" }

@enduml

The database container:

  • Stores user registration data persistently.

  • Is accessed exclusively by the Users Service.

  • Is not directly exposed to the frontend or Gamey.

  • Ensures data durability and separation of concerns.

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.

This section describes the fundamental concepts, architectural principles, and technical decisions that apply across multiple components of the system. These concepts ensure architectural consistency, reduce complexity, and support the system’s long-term evolution.

8.1. <Domain Concepts>

The domain of the system is centered around user management and Game Y execution.

Key domain concepts include:

  • User: A registered client of the system.

  • Game: A Game Y match, either active or completed.

  • Player: An entity participating in a game (human or automated).

  • Bot: An automated player controlled by the game engine.

  • Move / Action: A single action performed during gameplay.

  • Game State: The current state of a game.

  • User Profile: Persisted information associated with a user.

8.2. <Architecture and Design Patterns>

The system follows a service-oriented and layered architecture, applying the following principles:

  • Client–Server Architecture The web application acts as a client, while backend services act as servers.

  • Separation of Concerns Each component has a clearly defined responsibility:

  • Webapp: User interaction and presentation

  • Users Service: User management and persistence

  • Gamey: Game logic and bot execution

  • API-first Design All communication between components is performed through HTTP-based APIs.

This approach ensures loose coupling and enables independent evolution of components.

8.3. <Security Concepts>

The system implements basic security concepts, appropriate for a development or educational environment:

  • No authentication or authorization mechanisms are currently enforced.

  • No sensitive credentials are stored.

  • Database access is restricted to the Users Service.

  • Services communicate within a trusted internal network.

  • Security considerations are intentionally simplified to keep the architectural focus on modularity and clarity.

8.4. <Development Concepts>

Development follows these principles:

  • Each service can be built, tested, and run independently.

  • Clear interface contracts define inter-service communication.

  • Technology choices are isolated per component.

This enables parallel development and easier maintenance.

8.5. <Operational Concepts>

From an operational perspective:

  • The system is primarily designed for local and development environments.

  • Services are started and stopped as a group.

  • Logs are written to standard output.

  • No monitoring or automated scaling is currently implemented.

The operational model favors simplicity and transparency over production-level optimization.

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.

Architecture Decisions

This section documents the most relevant architectural decisions made during the design of the system. Each decision includes context, alternatives, rationale, and consequences to ensure traceability and transparency.

ADR-01: Adoption of a Service-Oriented Architecture

Status
Accepted
Context
The system consists of three main functional areas:
User interface (Webapp)
User management
Game engine logic
These areas could be implemented either as a single monolithic application or as independent services.
Decision
The system is implemented as a set of loosely coupled services, each running independently and communicating via HTTP APIs.
Alternatives Considered
Monolithic architecture
Service-oriented (multi-container) architecture
Rationale
The service-oriented approach was selected because:
It enforces clear separation of concerns.
It allows independent development and testing.
It aligns with container-based deployment.
It improves maintainability and scalability.
Consequences
Positive:
Independent evolution of components.
Clear API contracts.
Better modularity.
Negative:
Increased deployment complexity.
Network communication overhead.

ADR-02: Use of Container-Based Deployment

Status
Accepted
Context
The system needs to be executable in development environments and easily portable across machines.
Decision
All services are deployed using containerization and orchestrated together.
Alternatives Considered
Native execution on host machine
Containerized execution
Rationale
Containerization ensures:
Environment consistency.
Dependency isolation.
Simplified onboarding.
Infrastructure reproducibility.
Consequences
Positive:
Predictable deployments.
Technology independence per service.
Negative:
Slight overhead compared to native execution.

ADR-03: Introduction of a Dedicated Persistence Layer for Users

Status
Accepted
Context
To support real user management, persistent storage is required.
Decision
A dedicated database component is introduced for storing user data.
The database is accessed exclusively through a persistence layer inside the Users Service.
Alternatives Considered
In-memory user storage
File-based storage
Rationale
A database-based solution was chosen because:
It provides durability and consistency.
It enables long-term user management.
It allows future extension (authentication, statistics, etc.).
It enforces architectural separation between services.
Consequences
Positive:
Persistent user data.
Improved scalability.
Clear data ownership (Users Service).
Negative:
Additional infrastructure component.
Need for connection management and data modeling.

ADR-04: Separation of Game Logic from User Management

Status
Accepted
Context
The system includes both user registration and game execution logic.
Decision
T   he Gamey engine remains fully independent from user persistence and user management.
Rationale
Ensures single responsibility per service.
Allows the game engine to be reused in other contexts.
Prevents unnecessary coupling between domain areas.
Consequences
Positive:
Clear domain boundaries.
Higher reusability.
Easier testing.
Negative:
Requires API coordination between services.

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

Quality Tree

Content

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

Motivation

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

Form

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

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

  • a mind map with quality categories as main branches

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

10.2. Quality Scenarios

Priority Quality Requirement Scenario System Response

1

Usability

A user opens the game and wants to play.

The interface should be intuitive, the rules clear and the user should be able to understand how to play.

2

Performance

Multiple players plays simultaneously.

The game updates all moves and displays changes within 1 second.

3

Reliability

A network hiccup occurs during a match.

The game state is preserved, players can continue without losing progress.

4

Maintainability

Developers add a new feature.

The new feature integrates smoothly without affecting existing gameplay.

5

Availability

The system needs to handle more concurrent users.

The game continues to run with a minimal decrease in latency.
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

Identifying and recording technical risks and debts at an early stage is essential for the project’s success. By identifying potential issues ahead of time, the team can take appropriate measures to minimize their impact. Prioritizing these risks ensures that the most critical ones are addressed first, allowing for better planning and a more stable and maintainable architecture.

Contents

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

Motivation

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

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

Form

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

Further Information

See Risks and Technical Debt in the arc42 documentation.

11.1. Technical Risks

This table lists the main technical risks for our online board game project, including both team-related and system-related risks, ordered by priority.

Priority Risk Description Mitigation

High

Team members abandoning the project

One or more team members leave the project in the middle of development, increasing workload for remaining members.

Ensure code is well documented and modular, redistribute tasks, and maintain clear progress tracking.

High

Poor or limited communication within the team

Misunderstandings and delays occur due to a lack of communication between team members.

Hold regular meetings with clear minutes; use task boards and messaging tools to achieve constant communication.

High

Limited experience with large-scale projects

The team has little prior experience working on projects from scratch or with multiple contributors.

Conduct research, review best practices, and define clear development workflows and responsibilities.

Medium

Limited experience with Rust

The project uses Rust, which is new to the team members, potentially causing delays or inefficient code.

Each team member should independently study Rust and experiment with small prototypes to build competence.

Medium

Lack of experience with Docker

Docker is used for deployment and development environments, but the team is not familiar with it.

Set up step-by-step guides and practice building containers.

Medium

Database performance or schema issues

As users increase, the database may slow down or be difficult to scale due to initial design choices.

Optimize queries, define indexes, and design the schema for future scalability.

Medium

Third-party API failures

Some game functionalities rely on external APIs, which may become unavailable.

Implement caching, evaluate fallback APIs, and provide error handling to minimize disruption.

Low

High concurrent usage

Many players using the system simultaneously may degrade performance or affect game state consistency.

Conduct load testing, use caching, and optimize backend services.

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

JavaScript

A dynamic, high-level programming language frequently utilized for client-side and interactive web development

Front-end

The part of a web application that interacts with the user, usually involving the user interface and client-side logic.

Back-end

The part of a web application that runs on the server, handling data storage, business logic, and interaction with the front-end.

Rust

A modern programming language focused on safety, performance, and concurrency.

Node.js

A JavaScript runtime built on Chrome’s V8 engine that allows executing JavaScript on the server-side.

Docker

An open-source platform that automates the deployment, scaling, and management of applications using containerization.

Framework

A reusable set of libraries or tools that provides a structured environment to develop software applications efficiently.

API

API refers to Application Programming Interface. It is a set of rules and protocols that allows software applications to communicate with each other.

React

A JavaScript library for building interactive user interfaces, particularly single-page applications.