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

We are a team of four Software Engineering students from the University of Oviedo developing YOVI, a web-based gaming platform for the company Micrati as part of our Architecture of Software Systems (ASR) course project.

The platform will allow users to play Game Y against AI opponents with strategies and track their games via their own account. Our solution is built with a service-oriented architecture comprising three main components: a React frontend (webapp/), a Node.js user service (users/), and a Rust game engine (gamey/), all orchestrated via an API gateway. This architecture ensures clarity, maintainability, and scalability while fulfilling both academic requirements and player expectations.

This document outlines the architectural vision for YOVI, balancing functionality with clarity and maintainability to meet both academic requirements and player expectations.

1.1. Requirements Overview

The YOVI system is a web-based gaming platform based on Game Y, developed for the company Micrati. The main goal is to allow users to play matches against the machine or via bots, with support for registration and statistics functionalities.

Key functional requirements include:

  • Public deployment and web accessibility.

  • Development of a web application in React that allows playing at least the classic version of Game Y.

  • Implementation of a Rust module to verify the game state and suggest moves to the bot.

  • User registration and access to match history.

  • Support for multiple strategies and difficulty levels in the vs. machine mode.

1.2. Quality Goals

The main quality attributes for the system architecture are:

  • Functionality: The system must correctly implement Game Y rules and provide at least one working AI strategies.

  • Usability: The React-based interface must be intuitive for players. The component-based architecture of the webapp supports future internationalization (i18n)

  • Modularity & Maintainability: The clear separation into services ensures that components can be developed, tested, and extended independently.

  • Deployability & Availability: Using Docker and Docker Compose ensures that the multi-service application can be consistently deployed in any environment. The gateway provides a single entry point, simplifying deployment

  • Testability: The separation of concerns allows for comprehensive testing at multiple levels: unit tests in Rust and Node.js, integration tests between services, and end-to-end tests for the webapp

1.3. Stakeholders

Role/Name Contact Expectations

Development Team

yovi_en2c

Implement a scalable, maintainable, and well-documented solution.

End Users

N/A

Usable, stable interface with complete gameplay and statistics features.

Micrati (Client)

N/A

Fulfillment of game, API, and public deployment requirements.

Project Evaluators

Arquisoft

Compliance with documentation, testing, deployment, and code quality criteria.

Bot Developers

API users

Well-documented and stable API for automated integration.

2. Architecture Constraints

This section lists the main constraints that shape the architecture of the YOVI system. Unlike requirements , constraints define how it must be done or which technologies must be used. These are non-negotiable boundaries within which we must operate. .

2.1. Technical Constraints

These constraints are imposed by the client (Micrati). They dictate the technology stack and communication protocols.

Constraint

Explanation

Rationale

Negotiable?

Frontend Technology

The web application MUST be implemented in TypeScript. React is the chosen framework but not strictly mandatory.

The client requires TypeScript for type safety and maintainability.

No (TypeScript is mandatory)

Game Engine Language

The game logic module MUST be implemented in Rust.

Performance and safety requirements for game state validation and AI strategies.

No

Communication Protocol

All communication between the webapp and game engine MUST use JSON messages following YEN notation for game states.

Standardized format specified by the client for interoperability.

No

Public API

The system MUST expose a documented public API that allows external bots to interact.

Core requirement from Micrati for third-party integration.

No

Deployment

The complete system MUST be publicly accessible via the Web.

The client needs to demonstrate the working product.

No

Containerization

All services MUST be containerized using Docker with a root-level docker-compose.yml.

Ensures consistent deployment across environments.

Partial (format flexible)

Database

User data MUST be persisted. MongoDB is the current implementation, but alternatives are possible.

Data persistence is mandatory; the specific database technology is negotiable.

Yes (technology choice)

2.2. Domain Constraints

These constraints come from the game domain itself and the specific requirements of Game Y.

Constraint

Explanation

Rationale

Negotiable?

Game Rules

The system MUST correctly implement the rules of Game Y (classic version minimum).

Core business requirement; incorrect game rules make the product worthless.

No

Game Mode

A player-versus-machine mode MUST be available.

Primary use case for the platform.

No

Board Size

The game MUST support variable board sizes configurable by the user.

Required for different difficulty levels and game variants.

No

AI Strategies

The computer MUST implement more than one strategy, selectable by the user.

Demonstrates AI sophistication and provides varied gameplay.

No

User Data

Users MUST be able to register and access their match history.

Basic user management requirement.

No

2.3. Organizational Constraints

These constraints govern our development process and team practices.

Constraint

Explanation

Rationale

Negotiable?

Documentation Standard

Architecture MUST be documented following the Arc42 template.

Course requirement for the ASR lab.

No

Decision Recording

Architectural decisions MUST be recorded as ADRs (Architectural Decision Records) in the wiki of Github.

Ensures traceability and rationale documentation.

No

Version Control

Development MUST use Git with the repository hosted on GitHub (Arquisoft/yovi_en2c).

Course requirement for collaboration and evaluation.

No

Branching Strategy

A branch-based workflow MUST be followed (feature branches, pull requests, code reviews).

Ensures code quality and team coordination.

Partial (specific workflow details negotiable)

Testing Requirements

The system MUST include unit tests, integration tests, and end-to-end tests.

Quality assurance requirement from course evaluation.

No

Test Coverage

Code coverage MUST meet thresholds defined in sonar-project.properties (minimum 80%).

Quality gate for acceptance.

No

CI/CD

Automated build, test, and deployment MUST be implemented via CI/CD pipelines (GitHub Actions).

Ensures reproducible builds and deployment automation.

No

Issue Tracking

All tasks MUST be tracked using GitHub Issues.

Project management and traceability requirement.

No

2.4. External Constraints

These constraints come from external stakeholders and the operating environment.

Constraint

Explanation

Rationale

Negotiable?

Bot Integration

External bots can ONLY interact through the public API; no direct access to internal services.

Security and encapsulation requirement.

No

API Documentation

The public API MUST be documented for third-party developers.

Enables external developers to build compatible bots.

Partial (documentation format negotiable)

YEN Notation Compliance

Any system claiming to support Game Y MUST use YEN notation for game state representation.

Industry standard for this game family.

No

Public Accessibility

The deployed system MUST be accessible without special network configuration.

End users and evaluators need to access the platform easily.

No

2.5. Quality Constraints

These constraints define the minimum acceptable quality levels the architecture must guarantee.

Constraint

Target

Measurement

Negotiable?

Response Time

Game engine must respond within 2 seconds for standard board sizes.

Performance testing with realistic loads.

Partial (exact threshold)

Concurrent Users

Support at least 10 concurrent users without degradation.

Load testing simulation.

Yes (scale up with resources)

Availability

System must achieve 99% uptime during evaluation period.

Monitoring and observability tools.

Partial (percentage)

2.6. Implications of These Constraints

These constraints collectively shape our architecture in specific ways:

  • Three-service structure: The technology constraints (TypeScript + Rust) force a separation between frontend (webapp) and game engine (gamey). The user management requirement adds a third service (users).

  • API Gateway necessity: Multiple services with public API exposure require a gateway for request routing and security.

  • Docker standardization: The containerization constraint ensures consistent development and deployment environments.

  • Documentation overhead: Arc42 and ADR requirements mean we must invest time in documentation alongside development.

  • Testing necessity: The testing requirements force us to design for testability from the start.

3. Context and Scope

This section delimits the YOVI system from its environment. Following arc42 guidelines, we separate business context (what the system does, from a domain perspective) from technical context (how it communicates, from an infrastructure perspective).

3.1. Business Context

The YOVI system is a web-based gaming platform for Game Y. From a business perspective, it provides two distinct value propositions:

  • For human players: An intuitive web interface to play Game Y against AI opponents, register, and track their performance.

  • For bot developers: A public API that allows automated bots to interact with the game engine, request moves, and play matches.

The system depends on no external business systems - it is self-contained in terms of domain functionality. All game logic, user management, and AI strategies are implemented within the YOVI system boundaries.

3.1.1. Business Context Diagram

Business Context Diagram YOVI System

3.1.2. Business Interfaces

Interface

Description

Input

Output

Communication Partner

Game Play Interface

Web UI for human players to interact with the game

Mouse clicks, keyboard

Visual board, game state

Human Player

User Management

Registration and login interface

Username, password

Session token, user profile

Human Player

Statistics Interface

Access to match history and metrics

User ID

Win/loss records, game history

Human Player

Bot API - Move Request

Programmatic interface for bots to get next move

Board state (YEN), strategy

Move (YEN)

Bot

Bot API - Game State

Programmatic interface to query game status

Game ID

Current board, turn, winner

Bot

3.2. Technical Context

From a technical perspective, the YOVI system is implemented as three independent services communicating via HTTP/REST, plus an API gateway that routes external requests. This section describes the technical channels and protocols that enable the business interfaces defined above.

3.2.1. Technical Context Diagram

Technical Context Diagram YOVI System

3.2.2. Technical Interfaces and Channels

This table maps the business interfaces (what) to the technical channels (how), showing exactly how each domain interaction is implemented technically.

Business Interface

Technical Channel

Protocol

Data Format

Game Play UI

Browser ↔ Gateway

HTTPS

HTML/CSS/JS + JSON

User Management

Gateway ↔ Users Service

HTTP (internal)

JSON

User Registration

Browser ↔ Gateway ↔ Users

HTTPS → HTTP → JSON

JSON

User Login

Browser ↔ Gateway ↔ Users

HTTPS → HTTP → JSON

JSON

Statistics Retrieval

Browser ↔ Gateway ↔ Users

HTTPS → HTTP → JSON

JSON

Bot API - Move Request

Bot ↔ Gateway ↔ Gamey

HTTPS → HTTP → JSON

JSON (YEN)

Bot API - Game State

Bot ↔ Gateway ↔ Gamey

HTTPS → HTTP → JSON

JSON (YEN)

Game Logic Execution

Gateway ↔ Gamey Service

HTTP (internal)

JSON (YEN)

Database Access

Users Service ↔ MongoDB

MongoDB Wire Protocol

BSON

3.2.3. Technology Stack per Component

Component

Technology

Justification

Web Frontend

React + TypeScript

Client requirement, component reusability

User Service

Node.js + Express

Lightweight, npm ecosystem, quick development

Game Engine

Rust

Performance, memory safety, required by client

API Gateway

Nginx (or Express Gateway)

Simple reverse proxy, request routing

Database

MongoDB

Flexible schema for user data, easy integration

Containerization

Docker + docker-compose

Consistent environments, easy deployment

CI/CD

GitHub Actions

Integrated with repository, automated testing

3.3. Scope

3.3.1. In Scope (Core Requirements)

  • Classic Game Y implementation with correct rules

  • Player-versus-machine game mode with variable board size

  • Multiple AI strategies (difficulties), user-selectable

  • User registration and authentication

  • Match history and basic statistics (games played, wins/losses)

  • Public REST API for bots with YEN notation

  • Docker containerization and docker-compose deployment

  • CI/CD pipeline with automated testing

  • Public web deployment

3.3.2. Out of Scope (Optional / Future)

  • Game variants (Poly-Y, Hex, etc.) - optional features if time permits

  • User ranking/leaderboard system - optional

  • Internationalization (i18n) - optional

  • Mobile applications

  • Multiplayer (human vs. human)

  • Advanced analytics or machine learning

3.3.3. In Scope but Implemented Simply

  • Bot strategies: Initial implementation includes random move

  • Statistics: Basic counters only, not visible yet for the user, no advanced metrics

  • Authentication: Simple JWT-based, no OAuth/social login

4. Solution Strategy

This section summarizes the fundamental decisions that shape the YOVI system architecture. Each decision is motivated by specific constraints (from section 2) and quality goals (from section 1), and forms the foundation for detailed design decisions in later sections.

4.1. 1. Technology Decisions

These decisions are primarily driven by the technical constraints defined in section 2 (TypeScript, Rust, Docker) and the quality goal of maintainability.

Decision

Rationale

Constraints/Goals Addressed

Alternatives Considered

Frontend: React + TypeScript

React’s component model enables UI reuse and supports future i18n. TypeScript is mandatory per client.

Technical Constraint: TypeScript; Quality: Usability, Maintainability

Vue, Angular (rejected due to team familiarity)

User Service: Node.js/Express

Lightweight, fast for prototyping, integrates well with MongoDB. Team has JavaScript expertise.

Quality: Development speed, Testability

Python/Flask, Java/Spring (rejected: heavier, slower for simple CRUD)

Game Engine: Rust

Mandated by client. Provides memory safety and performance for game logic and AI.

Technical Constraint: Rust; Quality: Performance, Reliability

C++, Go (not allowed by constraint)

Database: MongoDB

Schema flexibility for user data, easy integration with Node.js, quick setup.

Quality: Development speed, Deployability

PostgreSQL (rejected: schema changes slower for evolving requirements)

Containerization: Docker + docker-compose

Ensures consistent environments across dev/test/prod. Required for deployment.

Technical Constraint: Containerization; Quality: Deployability

Manual deployment (rejected: inconsistent, error-prone)

CI/CD: GitHub Actions

Integrated with repository, automates testing and deployment, free for students.

Organizational Constraint: CI/CD; Quality: Testability

Jenkins (rejected: requires separate infrastructure)

4.2. 2. Top-Level Decomposition (Architectural Pattern)

Decision: Microservices architecture with three independent services (webapp, users, gamey) plus an API gateway.

Reasons: - The technology constraints (TypeScript + Rust) force a separation - they cannot run in the same process - Separating user management from game logic allows independent scaling and development - The gateway provides a single entry point, hiding internal complexity (security constraint)

How it maps to quality goals:

  • Maintainability: Services can be modified independently

  • Testability: Each service can be tested in isolation

  • Deployability: Services can be deployed independently or together via docker-compose

Service Decomposition

4.3. 3. Design Patterns

Pattern

Application

Rationale

Location

Model-View-Controller

Webapp structure

Separates UI (View) from game state (Model) and user input handling (Controller). Essential for maintainability.

webapp/src/ (React components as View, state as Model, event handlers as Controller)

Strategy Pattern

Bot AI implementation

Allows multiple difficulty levels/strategies without changing game core. New strategies = new classes, no modification to existing code.

gamey/src/bot/ (each strategy implements common trait)

Observer Pattern

UI updates

When game state changes, UI must update automatically. React’s virtual DOM and state management handle this efficiently.

webapp/src/ (React hooks/state)

Gateway/Router Pattern

API Gateway

Single entry point routes requests to appropriate services. Simplifies client and adds security layer.

gateway

4.4. 4. Quality Goal Realization

This table shows how specific architectural decisions directly address the quality goals defined in section 1.

Quality Goal

How We Achieve It

Key Decisions

Verification

Functionality

Rust engine ensures correct game rules; multiple strategies in gamey/src/bot/

Rust for game logic; Strategy pattern for AI

Unit tests in gamey/ verify rules; integration tests verify bot moves

Usability

React provides responsive UI; component design supports i18n

React frontend; Externalized strings

E2E tests verify user flows; usability testing with real users

Modularity & Maintainability

Microservices separation; Strategy pattern for extensions

Three-service architecture; Strategy pattern

Independent deployment possible; new strategies added without modifying core

Deployability & Availability

Docker containers; docker-compose; CI/CD

Containerization; GitHub Actions

docker-compose up works; CI pipeline runs on every push

Testability

Separation of concerns; dependency injection in Node.js; Rust’s test framework

Microservices; Repository pattern

Unit tests: cargo test, npm test; Integration tests; E2E tests

Interoperability

REST API with YEN notation; documented for bot developers

Public API in gamey; OpenAPI docs

API tests verify YEN format; documentation generated automatically

4.5. 5. Organizational and Process Decisions

Decision

Rationale

Impact

Constraint Addressed

Iterative Development (2-week sprints)

Early validation of gameplay; adapt to feedback

Regular demos; continuous integration

Course timeline; quality goals

Kanban Board (GitHub Projects)

Visualize work; identify bottlenecks

Issues tracked; clear priorities

Organizational: issue tracking

Code Reviews via Pull Requests

Catch issues early; share knowledge

All PRs require review; coding standards enforced

Quality: maintainability, reliability

Pair Programming for Complex Features

Rust game logic is critical; two minds better than one

Higher quality for core engine

Quality: functionality, reliability

Architectural Decision Records (ADRs)

Document why decisions were made

Github wiki with numbered ADRs

Organizational: documentation standard

Definition of Done

Feature = code + tests + docs + reviewed

Ensures completeness before merge

Quality: testability, maintainability

4.6. 6. Key Architectural Decisions Summary

This table lists the most significant decisions that shape the architecture, with references to detailed ADRs.

Decision

ADR

Summary

Status

Modes of game available to the user

ADR-001

Basic funcionality to create a extendable project

Implemented

MongoDB for user data

ADR-002

Schema flexibility for evolving requirements

Implemented

Three-service architecture

ADR-003

Separate webapp, users, gamey services due to technology constraints

Implemented

API Gateway

ADR-004

Single entry point for security and routing

Implemented

Strategy Pattern for AI

ADR-005

Bot strategies as pluggable components

In progress

4.7. 7. Traceability to Constraints

This section links back to the constraints defined in section 2, showing how our solution strategy satisfies them.

Constraint (from Section 2)

How Solution Strategy Addresses It

TypeScript frontend

React + TypeScript in webapp/

Rust game engine

gamey/ service with core logic and bot strategies

JSON + YEN communication

REST APIs with YEN validation in gamey/

Public API for bots

gamey/ exposes /api/game/* endpoints via gateway

Docker containerization

Each service has Dockerfile; root docker-compose.yml

User data persistence

MongoDB in users/ service

Multiple AI strategies

Strategy pattern in gamey/src/bot/

Testing requirements

Unit, integration, E2E tests in all services

CI/CD

GitHub Actions workflows for test and deploy

Documentation (Arc42 + ADRs)

This document + ADRs in Github wiki

5. Building Block View

This section describes the static decomposition of the YOVI system into building blocks. Following arc42 guidelines, we present a hierarchical view:

  • Level 1: White box description of the overall system, with black box descriptions of each top-level building block

  • Level 2: White box descriptions of selected building blocks, showing their internal structure

This abstraction allows understanding the system structure without drowning in implementation details.

5.1. Level 1: Overall System White Box

The YOVI system is decomposed into four top-level building blocks: three services and an API gateway, plus an external database.

Level 1 System White Box

5.1.1. Black Box Descriptions

API Gateway

  • Purpose/Responsibility: Acts as the single entry point to the system. Routes external requests to the appropriate internal service, handles SSL termination, and provides a security layer.

  • Interface(s):

    • Provided:

      • Public Web UI endpoint

      • Public Bot API endpoint

    • Required:

      • Web Frontend Service (internal HTTP)

      • User Service (internal HTTP)

      • Game Engine Service (internal HTTP)

  • Quality/Performance Characteristics: Must handle all external traffic; availability is critical. Stateless, can be scaled horizontally.

  • Directory/File Location: /gateway/ (nginx config or Express Gateway config)

  • Fulfilled Requirements: Public deployment, single entry point

  • Open Issues: SSL certificate management in production

Web Frontend Service

  • Purpose/Responsibility: Provides the user interface for human players. Handles game rendering, user interaction, and orchestrates calls to backend services.

  • Interface(s):

    • Provided: Web UI (HTML/CSS/JS) served to browsers

    • Required:

      • User Service API

      • Game Engine API

  • Quality/Performance Characteristics: Responsive UI (< 100ms for interactions). Must support i18n. Stateless for scalability.

  • Directory/File Location: /webapp/ (React + TypeScript source)

  • Fulfilled Requirements: Web frontend, game visualization, strategy selection UI

  • Open Issues: Real-time updates for future multiplayer features

User Service

  • Purpose/Responsibility: Manages all user-related data: registration, authentication, profile information, match history, and statistics.

  • Interface(s):

    • Provided: REST API with endpoints for register, login, profile, stats

    • Required: MongoDB for data persistence

  • Quality/Performance Characteristics: Must persist data reliably. Response time < 200ms for typical operations.

  • Directory/File Location: /users/ (Node.js + Express)

  • Fulfilled Requirements: User registration, match history, statistics

  • Open Issues: Authentication token expiration and refresh strategy

Game Engine Service

  • Purpose/Responsibility: Encapsulates all Game Y logic: move validation, win condition checking, and AI move calculation with multiple strategies.

  • Interface(s):

    • Provided: REST API (/api/game/*) using YEN notation for game states

    • Required: None (stateless, no external dependencies)

  • Quality/Performance Characteristics: Low latency (< 500ms for move calculation). High correctness (100% rule compliance). Memory safety critical.

  • Directory/File Location: /gamey/ (Rust)

  • Fulfilled Requirements: Game rule verification, AI move suggestion, multiple strategies, YEN notation

  • Open Issues: Performance optimization for large boards

MongoDB Database

  • Purpose/Responsibility: Persists user data, including profiles, authentication credentials, match history, and statistics.

  • Interface(s):

    • Provided: MongoDB Wire Protocol

    • Required: None (data storage only)

  • Quality/Performance Characteristics: Durable storage, backup capability. Must handle concurrent connections.

  • Directory/File Location: Managed via Docker (not in repo)

  • Fulfilled Requirements: User data persistence

  • Open Issues: Backup and recovery strategy

5.2. Level 2: Building Block Internals

5.2.1. White Box: Web Frontend Service (webapp/)

The web frontend is structured following a component-based architecture with clear separation of concerns.

Webapp Internal Structure
Black Box Descriptions (Webapp Internals) (In development)

Building Block

Responsibility

Key Interfaces

Location

UI Components

Render all user interfaces; handle user input events

Props/State callbacks

webapp/src/components/

State Management

Maintain application state (user, game, UI)

Context API / Redux store

webapp/src/store/

API Client

Communicate with backend services

HTTP methods (GET, POST)

webapp/src/services/

Routing

Handle navigation between views

URL paths

webapp/src/routes/

i18n Module

Provide internationalization support

Translation keys → strings

webapp/src/i18n/

5.2.2. White Box: Game Engine Service (gamey/)

The game engine is structured in layers, with clear separation between parsing, core logic, and AI strategies.

Game Engine Internal Structure
Black Box Descriptions (Game Engine Internals)

Building Block

Responsibility

Key Interfaces

Location

HTTP Server

Expose REST endpoints; handle requests/responses

POST /move, GET /strategies

gamey/src/web/

YEN Parser

Parse and validate YEN notation; serialize to YEN

parse(), serialize()

gamey/src/notation/

Game Core

Implement Game Y rules; validate moves; check wins

apply_move(), is_game_over()

gamey/src/core/

Board Model

Represent board state; manage cells

get_cell(), set_cell()

gamey/src/core/board.rs

AI Strategies

Implement different bot behaviors

calculate_move() (trait)

gamey/src/bot/

5.2.3. White Box: User Service (users/)

The user service follows a typical layered architecture for REST APIs.

User Service Internal Structure
Black Box Descriptions (User Service Internals) (In development)

Building Block

Responsibility

Key Interfaces

Location

API Routes

Define HTTP endpoints and HTTP methods

Express route handlers

users/src/routes/

Controllers

Handle requests, validate input, format responses

Controller functions

users/src/controllers/

Services

Implement business logic (password hashing, etc.)

Service methods

users/src/services/

Repositories

Abstract database operations

CRUD operations

users/src/repositories/

Models

Define data schemas and validation

Mongoose schemas

users/src/models/

5.3. Interface Overview

This table summarizes the key interfaces between building blocks, showing the provided and required relationships.

Interface

Provider

Consumer

Protocol

Data Format

Purpose

Public Web UI

Gateway

Browser

HTTPS

HTML/CSS/JS

Serve frontend to users

Public Bot API

Gateway

External Bot

HTTPS

JSON (YEN)

Bot integration

User API

Users Service

Webapp

HTTP (internal)

JSON

User management

Game API

Gamey Service

Webapp

HTTP (internal)

JSON (YEN)

Game logic

Database Interface

MongoDB

Users Service

MongoDB Wire

BSON

Data persistence

Internal Gateway Calls

Gateway

Webapp/Users/Gamey

HTTP (internal)

JSON

Service communication

5.4. Mapping to Requirements

This table shows how the building blocks fulfill the key requirements from section 1.

Requirement

Primary Building Block

Supporting Building Blocks

Web frontend (TypeScript/React)

Web Frontend Service

Gateway

Rust game engine

Game Engine Service

(none)

JSON + YEN communication

Game Engine Service

Webapp (client), Gateway (routing)

Public API for bots

Gateway

Game Engine Service

User registration

User Service

MongoDB

Match history

User Service

MongoDB, Webapp (UI)

Multiple AI strategies

Game Engine Service

(none)

Docker deployment

All services

docker-compose

CI/CD

GitHub Actions

All services

6. Runtime View

This section describes the dynamic behavior of the YOVI system. Following arc42 guidelines, we present a representative selection of architecturally significant scenarios:

  • Critical use cases: User registration, gameplay against bot, bot API usage

  • Key interactions: How building blocks cooperate

  • Error scenarios: How the system handles failures* Operation scenarios: System startup and shutdown

These scenarios demonstrate how the building blocks defined in Section 5 collaborate at runtime.

6.1. Runtime Scenario 1: User Registration (In development)

This scenario shows how a new user creates an account in the system. This is one of the main objective of the prject, at the moment the user only needs username to register but the verifications works in the same way.

User Registration Sequence

Steps:

  1. User fills registration form in the web frontend

  2. Frontend performs basic validation (format)

  3. Frontend sends registration request to API Gateway

  4. Gateway routes request to User Service

  5. User Service hashes the password (never stored in plain text)

  6. Service checks if username already exists

  7. Alternative 1 (user exists): Returns 409 Conflict, UI shows error

  8. Alternative 2 (new user): Inserts user document in MongoDB

  9. Generates JWT token for automatic login

  10. Returns success response with token

  11. Gateway forwards to frontend

  12. Frontend stores token and redirects user to dashboard

6.2. Runtime Scenario 2: Playthgough of a Game against two players

The following diagram shows the flow of a normal playthrough of a game with two players going against eachother :

User VS User Game Diagram

As such the standard gameplay would be as follows:

Initialization:

  1. User1 navigates to game initialization.

  2. The backend creates a new game session and stores it.

  3. User2 joins the session.

  4. The backend confirms that both players are connected.

  5. The game loop is initialized.

  6. Both users see the initialized game state.

Turns:

  1. The active player makes a move.

  2. The move is sent to the backend.

  3. The backend validates and updates the game state.

  4. The updated state is sent to the opponent.

  5. The opponent’s GUI renders the updated game state.

  6. The turn switches to the other player.

Finalization:

  1. The backend stores the result of the game in the database (User1 victory or User2 victory).

  2. The backend sends the final result to both GUIs.

  3. The winner sees a victory screen.

  4. The loser sees a defeat screen.

  5. The game session is closed and resources are released.

6.3. Runtime Scenario 3: Play Game vs. AI Bot

This scenario shows a complete game session between a human player and the AI, using the Rust game engine.

Game vs Bot Sequence

Steps Summary:

Initialization:

  1. User selects game mode, board size, and AI strategy

  2. Frontend requests new game session

  3. Game engine creates initial state and returns game ID

Game Loop:

  1. Player makes a move (validated by game engine)

  2. If move invalid → error, player tries again

  3. If move valid → game engine updates state and checks win

  4. If player won → game ends, show victory

  5. If game continues → engine calculates bot move using selected strategy

  6. Bot move applied, win condition checked

  7. If bot won → game ends, show defeat

  8. If game continues → updated board shown to player

Finalization:

  1. Game result sent to user service

  2. Match history updated in MongoDB

  3. UI updates local statistics

Architectural significance: - Shows Rust engine in action (move validation, AI calculation) - Demonstrates strategy pattern for bot behavior - Illustrates YEN notation for game state (implicit in API calls) - Shows complete flow from UI → gateway → engine → database

6.4. Runtime Scenario 4: Error and Exception Handling

This scenario shows how the system handles various failure conditions.

6.4.1. Scenario 4.1: Game Engine Unavailable

Game Engine Down

6.4.2. Scenario 4.2: Invalid Move (Business Rule Violation) (In development)

Invalid Move

6.4.3. Scenario 4.3: Database Connection Lost

Database Down

6.5. Summary of Runtime Scenarios

Scenario

Architectural Relevance

Building Blocks Involved

Quality Goals Demonstrated

User Registration

Stateless auth, data persistence

Webapp, Gateway, Users, MongoDB

Usability, Reliability

Player 1 vs Player 2

Core game loop between two real users

Webapp, Gateway, Gamey, Users, MongoDB

Functionality, Performance

Game vs Bot

Core game loop, AI strategies

Webapp, Gateway, Gamey, Users, MongoDB

Functionality, Performance

Error Handling

Resilience, fault tolerance

All services

Reliability, Availability

These scenarios represent the most architecturally significant runtime behaviors of the YOVI system. They demonstrate how the static building blocks from Section 5 collaborate to deliver the required functionality while satisfying the quality goals from Section 1.

7. Deployment View

This section describes the technical infrastructure that executes the YOVI system and the mapping of building blocks (from Section 5) to infrastructure elements. Following arc42 guidelines, we present:

  • Level 1: Overall deployment environment (production)

  • Level 2: Internal structure of key infrastructure nodes

  • Environment variations: Development, test, and production differences The application is built to use Docker and a Virtual Machine as a host in such a way that it combines the portability of the containers with the security and isolation features of the VM.

7.1. Level 1: Production Deployment Overview

The YOVI system is deployed as a containerized application running on a cloud virtual machine. All services run in Docker containers, orchestrated with docker-compose.

Production Deployment Level 1

7.1.1. Infrastructure Elements (Level 1)

Element

Description

Technology

Purpose

Cloud VM

Virtual machine hosting all containers

Ubuntu 22.04 LTS

Execution environment

Docker Engine

Container runtime

Docker v24.0+

Container orchestration

Gateway Container

API Gateway service

Nginx / Express Gateway

Request routing, SSL termination

Webapp Container

Frontend service

Node.js + React (static files)

Serve UI to users

Users Container

User management service

Node.js + Express

User data & auth

Gamey Container

Game engine service

Rust

Game logic & AI

MongoDB Container

Database

MongoDB 7.x

Data persistence

Prometheus Container

Metrics collection

Prometheus latest

Monitoring

Grafana Container

Metrics visualization

Grafana latest

Dashboards

GitHub Registry

Container image registry

GitHub Container Registry

Image storage

7.1.2. Communication Channels (Level 1)

Channel

Protocol

Source

Destination

Purpose

External HTTPS

HTTPS (TLS 1.3)

Internet

Gateway (port 443)

User/bot access

Internal HTTP

HTTP (plain)

Gateway

Webapp/Users/Gamey

Service communication

MongoDB Wire

MongoDB protocol

Users

MongoDB (27017)

Database access

Docker Pull

HTTPS

VM

GitHub Registry

Image download

Metrics Scrape

HTTP

Prometheus

All services

Monitoring data

Grafana Query

HTTP

Grafana

Prometheus

Dashboard queries

7.2. Level 2: Internal Structure of Key Nodes

7.2.1. Level 2: Cloud VM Internal Structure

This diagram zooms into the Cloud VM, showing the container organization and internal networks.

Cloud VM Internal Structure

7.2.2. Production Environment

Aspect Configuration Justification

Location

Cloud VM (AWS EC2 / DigitalOcean)

Public accessibility

Orchestration

docker-compose + systemd

Simple, sufficient for scale

Networking

Public IP + domain

User access

Data

Persistent volumes

Data durability

Monitoring

Prometheus + Grafana

Observability

Backup

Daily automated backups

Disaster recovery

SSL

Let’s Encrypt auto-renew

Security

7.3. Mapping of Building Blocks to Infrastructure

This table maps the building blocks from Section 5 to the infrastructure elements described above.

Building Block Deployed As Environment Node Container Network

Web Frontend Service

Static files + Node server

Production

Cloud VM

webapp_container

frontend_network

User Service

Node.js application

Production

Cloud VM

users_container

backend_network

Game Engine Service

Rust binary

Production

Cloud VM

gamey_container

backend_network

API Gateway

Nginx configuration

Production

Cloud VM

gateway_container

frontend_network

MongoDB Database

MongoDB instance

Production

Cloud VM

mongodb_container

backend_network

Prometheus

Prometheus server

Production

Cloud VM

prometheus_container

monitoring_network

Grafana

Grafana server

Production

Cloud VM

grafana_container

monitoring_network

7.4. Deployment Decisions and Rationale

Decision Rationale Alternatives Considered Trade-offs

Single VM with docker-compose

Simplicity, cost-effective for expected load (10 concurrent users)

Kubernetes (overkill), separate VMs (costly)

Limited horizontal scaling, but simpler operations

Separate networks

Security isolation between frontend and backend

Single flat network

More complex config, but better security

Monitoring stack included

Required for observability and course evaluation

External monitoring service

Additional resource usage, but integrated

Persistent volumes

Data durability across container restarts

Ephemeral storage

Requires backup strategy

Let’s Encrypt SSL

Free, automated certificates

Paid certificates, self-signed

Auto-renewal complexity, but free

7.5. Deployment Scripts and Configuration

The deployment is automated via:

  • docker-compose.yml – at repository root. Defines all services.

  • deploy.sh – script for production deployment.

  • GitHub Actions workflow – CI/CD pipeline for testing and deployment.

7.6. Quality and Performance Features

Some of the characteristics obtained by the use of the specified implementation:

  • Isolation: Both thanks to the container isolation of Docker and the own security features of the Virtual Machine.

  • Portability and Compatibility: Thanks to the use of the Docker containers.

  • Security: If a container is compromised, the VM can act as another security layer.

  • Others: Scalability, easily maintainable, would be very simple to backup…​

7.7. Mapping of Building Blocks to Infrastructure

The building blocks of the current infrastructure would be:

  • Webapp: Located in port 80, it is the one the user will connect to and interact with. It is the GUI (Graphic User Interface), and as such the frontend of the application.

  • Gateway: This block has port 8080 assigned, and it is in charge of acting as a bridge between the rest of the building blocks of the application.

  • Users: It is in charge of the user management as well as the authentication feature, and its port is 3000.

  • Gamey: This service, written in Rust, is the one containing the complete functionality of the Y Game. It uses port 4000.

  • Database: It is an external block containing all the information of the application (user data, game data…​).

Additionally, it is worth mentioning the presence of Prometheus and Grafana, located in ports 9090 and 9091 respectively, are external blocks that will be used to monitor and obtain metrics of the application and its usage.

8. Cross-cutting Concepts

8.1. Game State Representation

All game state across the system is represented using YEN notation, as mandated by the client.

{
  "size": 11,
  "turn": "R",
  "board": {
    "cells": [
      ["R", "B", "R", "B"]
    ]
  }
}

  • Usage:

    • gamey/ service: Parses and validates YEN, returns moves in YEN

    • webapp/: Converts UI interactions to YEN for API calls

    • Public API: Accepts and returns YEN exclusively

  • Rationale: Standardization ensures interoperability with external bots and consistency across services.

8.2. Internationalization

For the application to be more accessible to a wider range of users, internationalization was implemented for the languages of english and spanish, with architecture designed for easy addition of new languages.

  • Implementation:

    • All UI strings externalized to JSON files

    • Language selection in user preferences

    • URL-based language (optional): /en/play, /es/play

// i18n file structure
/locales/
  en/
    common.json
    game.json
    user.json
  es/
    common.json
    game.json
    user.json

  • Fallback: English as default if translation missing

8.2.1. Network Security

Layer

Measure

Purpose

Transport

HTTPS with TLS 1.3

Encrypt all external traffic

Network isolation

Docker networks (frontend/backend)

Prevent direct backend access

Firewall

Only ports 22(SSH) and 443(HTTPS) exposed

Minimize attack surface

API Gateway

Single entry point

Hide internal service topology

8.2.2. Secrets Management

  • Development: .env files (gitignored)

  • CI/CD: GitHub Secrets for all credentials

  • Production: Environment variables in docker-compose (never committed)

Example secrets:

  • JWT_SECRET

  • MONGODB_URI

  • GITHUB_TOKEN

8.3. Architecture and Design Patterns

Already documented in Section 4, but summarized here for cross-cutting relevance:

Pattern

Application

Cross-cutting Concern

Strategy Pattern

Bot AI strategies

Extensibility (new strategies = new classes)

Repository Pattern

Data access in users service

Testability (mock repositories)

Gateway/Router

API Gateway

Security, routing, monitoring

Observer/Reactive

UI updates via React state

Consistent UI across state changes

8.3.1. Error Handling Strategy

Consistent error handling across all services:

API errors always return appropriate HTTP status codes:

Status Code

When

Example

400 Bad Request

Invalid input format

Malformed YEN

401 Unauthorized

Missing/invalid token

No JWT

403 Forbidden

Valid token but insufficient permissions

User accessing another’s data

404 Not Found

Resource doesn’t exist

Invalid game ID

409 Conflict

Business rule violation

Username already exists

500 Internal Error

Unexpected server error

Database connection lost

503 Unavailable

Service temporarily down

Game engine unreachable

8.3.2. Code Organization

All services follow consistent structure:

/service-name/
    src/            # Production code
    test/           # Unit tests
    integration/    # Integration tests
package.json/Cargo.toml
Dockerfile
README.md

8.3.3. Testing Strategy

Test Type

Tool

Location

Coverage Target

Unit tests

Jest (Node), cargo test (Rust)

*/.test.ts, *_test.rs

80%+

Integration tests

Supertest (Node), custom (Rust)

/test/integration/

Key paths

End-to-end tests

Playwright

webapp/e2e/

Critical user journeys

API tests

Postman/Newman

/api-tests/

All endpoints

CI Integration: All tests run on every PR via GitHub Actions

8.3.4. Quality Assurance

  • SonarQube is integrated into the GitHub repository to:

    • Ensure proper code coverage

    • Detect code smells and potential bugs

    • Enforce coding standards

    • Monitor technical debt

  • CI Integration: All tests run on every pull request via GitHub Actions. The pipeline fails if:

    • Any test fails

    • Code coverage drops below threshold (80%)

    • SonarQube detects critical issues

9. Architecture Decisions

This section documents the most significant architectural decisions made during the design and development of the YOVI platform. Each decision follows the ADR (Architecture Decision Record) format to provide context, rationale, and consequences. These decisions complement the solution strategy outlined in Section 4, providing deeper rationale for key choices.

9.1. ADR-001: Game Modes Available to the User

  • Status: Implemented

  • Date: 2026-01-15

  • Deciders: Development Team

Context: The platform needs to offer users different ways to play Game Y. The initial requirements specify player-versus-machine mode, but the architecture should be extensible to support additional modes in the future (multiplayer, different variants, etc.).

Decision: We will design the game mode system with extensibility as a core principle. The architecture will separate game mode logic from core game rules, allowing new modes to be added by:

  • Defining new mode types in the webapp UI

  • Extending the game engine to support mode-specific rules

  • Keeping mode state separate from core game state

Alternatives Considered:

  • Hard-code only PvM mode: Rejected - would require major refactoring for future modes

  • Configuration-driven modes: Considered but deferred - adds complexity for current requirements

  • Plugin architecture: Rejected - overkill for project scope

Consequences:

  • Positive: New game modes can be added without modifying core game logic

  • Positive: Clear separation between "how game is played" and "game rules"

  • Positive: Meets current requirements while preparing for future

  • Negative: Slightly more complex initial implementation

  • Negative: Requires careful design to avoid over-engineering

  • ️ Mitigation: Focus on PvM mode first, ensure extension points are clean

9.2. ADR-002: MongoDB for User Data Persistence

  • Status: Implemented

  • Date: 2026-01-20

  • Deciders: Development Team

Context: The users service needs to persist user profiles, authentication data, and match history. The team needed to choose a database technology that balances development speed with future flexibility.

Decision: We will use MongoDB for user data persistence. The schema will be designed to accommodate:

  • User profiles (username, password hash, email)

  • Authentication data (tokens, sessions)

  • Match history (games played, results, moves)

Alternatives Considered:

  • PostgreSQL: Rejected - schema changes for evolving requirements would be slower

  • MySQL: Rejected - similar concerns

  • In-memory storage: Rejected - data must persist

  • SQLite: Rejected - not suitable for concurrent access

Consequences:

  • Positive: Flexible schema allows easy addition of user fields

  • Positive: Excellent integration with Node.js via Mongoose ODM

  • Positive: Fast prototyping and iteration on data models

  • Negative: No built-in relations (handled in application code)

  • Negative: Eventual consistency (not critical for this domain)

  • Mitigation: Use atomic operations for critical updates (e.g., game statistics)

9.3. ADR-003: Three-Service Microservices Architecture

  • Status: Implemented

  • Date: 2026-01-15

  • Deciders: Development Team

Context: The lab assignment requires a web application in TypeScript and a game engine in Rust. These technologies cannot run in the same process. Additionally, user management (registration, history) is a distinct responsibility that could be separated.

Decision:

We will implement a microservices architecture with three independent services:

  • webapp/ - TypeScript/React frontend

  • users/ - Node.js/Express user management service

  • gamey/ - Rust game engine service

All services will communicate via REST APIs and be orchestrated with an API gateway.

Consequences:

  • Positive: Clear separation of concerns

  • Positive: Each service can be developed and tested independently

  • Positive: Technology-specific optimizations possible

  • Negative: Increased operational complexity (multiple services to deploy)

  • Negative: Network latency between services

  • Mitigation: docker-compose simplifies local development and deployment

9.4. ADR-004: API Gateway as Single Entry Point

  • Status: Implemented

  • Date: 2026-01-20

  • Deciders: Development Team

Context: With three independent services, external clients (human users and bots) would need to know multiple endpoints. This increases complexity and exposes internal service topology.

Decision:

We will implement an API Gateway (gateway/) as the single entry point for all external requests. The gateway will:

  • Route / → webapp service (static files)

  • Route /users/* → users service

  • Route /game/* → gamey service

  • Handle SSL termination

  • Provide a security layer

Alternatives Considered:

  • Direct client-to-service communication: Rejected - exposes internal services, complicates client logic

  • Load balancer only: Rejected - doesn’t provide routing based on paths

  • No gateway: Rejected - security concerns

Consequences:

  • Positive: Single URL for all clients simplifies access

  • Positive: Internal services remain hidden from external clients

  • Positive: Centralized SSL and security policies

  • Negative: Additional component to deploy and maintain

  • Negative: Potential performance bottleneck

  • Mitigation: Gateway is stateless and can be scaled horizontally

9.5. ADR-005: Strategy Pattern for AI Bot Behaviors

  • Status: In Progress

  • Date: 2026-01-25

  • Deciders: Development Team

Context: The system must support multiple AI strategies and difficulty levels. New strategies may be added in the future without modifying existing code. The requirement states "more than one strategy" must be available.

Decision: We will implement the Strategy Pattern in the gamey service. Each AI strategy will be a separate module implementing a common trait (BotStrategy). The game engine will select the appropriate strategy based on user input. Initial strategies will include:

  • Random move (implemented)

  • Heuristic-based (in discussion)

  • Minimax (in discussion)

Alternatives Considered:

  • Conditional logic (if/else or switch): Rejected - violates Open/Closed principle, hard to extend

  • Configuration flags with hard-coded algorithms: Rejected - similar concerns

  • Machine learning model: Rejected - overkill for requirements, unpredictable performance

Consequences:

  • Positive: New strategies can be added without modifying core game logic

  • Positive: Each strategy can be tested independently

  • Positive: Clear separation of concerns

  • Negative: Slight indirection overhead (negligible)

  • Negative: Requires understanding of trait/interface design

  • Mitigation: Well-documented strategy trait and example implementations

9.6. Summary of Architectural Decisions

ID

Decision

Key Rationale

Status

ADR-001

Game Modes

Extensibility for future modes

Implemented

ADR-002

MongoDB for User Data

Schema flexibility, Node.js integration

Implemented

ADR-003

Three-Service Architecture

Technology constraints (TypeScript + Rust)

Implemented

ADR-004

API Gateway

Security, single entry point

Implemented

ADR-005

Strategy Pattern for AI

Extensibility for multiple strategies

In Progress

10. Quality Requirements

This section details the quality requirements for the YOVI system. While Section 1.2 introduced the high-level quality goals, this section makes them concrete, measurable, and testable through a quality tree and specific scenarios.

Quality requirements are critical because they influence architectural decisions and determine whether stakeholders consider the system a success.

10.1. Quality Tree

The following quality tree organizes our quality requirements hierarchically, following the ATAM (Architecture Tradeoff Analysis Method) approach. The tree shows the decomposition of "Quality" into categories and subcategories, with each leaf linked to a measurable scenario.

Quality Tree

10.2. Quality Scenarios (In development)

10.2.1. Scenario QS-01: Move Calculation Performance

This scenario measures the response time of the game engine when calculating a bot move.

QS 01 Move Calculation Performance

Aspect

Description

ID

QS-01

Related Goal

Performance / Response Time

Stimulus

User makes a move in a game vs. bot

Source

Human player

Environment

Normal operation, standard board size (11x11)

Artifact

Game Engine Service (gamey/)

Response

System calculates and returns bot move

Response Measure

95% of moves calculated in < 2 seconds

Priority

High

Verification

Automated performance tests with timing metrics

10.2.2. Scenario QS-02: New User Learnability

This scenario tests whether a new user can start playing without external instructions.

QS 02 New User Learnability

Aspect

Description

ID

QS-02

Related Goal

Usability / Learnability

Stimulus

New user wants to play a game

Source

First-time player

Environment

User has never seen Game Y before

Artifact

Web Frontend (webapp/)

Response

User can start a valid game without external instructions

Response Measure

80% of new users in usability test complete first move within 2 minutes

Priority

High

Verification

Usability testing with 5 new users; task success rate tracking

10.2.3. Scenario QS-03: Feature Extensibility

This scenario measures how easily a new game variant can be added.

QS 03 Feature Extensibility

Aspect

Description

ID

QS-03

Related Goal

Maintainability / Extensibility

Stimulus

Developer needs to add a new game variant (e.g., Hex)

Source

Development team

Environment

Development environment, existing codebase

Artifact

Game Engine Service (gamey/)

Response

New variant can be added with minimal changes

Response Measure

Implementation takes < 2 developer-days and requires changes only to specific extension points

Priority

Medium

Verification

Code review and time tracking; demonstration of adding a sample variant

10.2.4. Scenario QS-04: Crash Recovery (Fault Tolerance)

This scenario tests the system’s ability to recover from a service failure.

QS 04 Crash Recovery

Aspect

Description

ID

QS-04

Related Goal

Reliability / Fault Tolerance

Stimulus

Game Engine service crashes

Source

Internal failure (memory leak, panic)

Environment

Production, during active game

Artifact

Game Engine Service (gamey/)

Response

System detects failure, restarts service, and allows user to continue

Response Measure

Downtime < 30 seconds; game state recoverable

Priority

High

Verification

Chaos engineering: kill container during test game and measure recovery time

10.2.5. Scenario QS-05: Concurrent Users

This scenario tests system performance under load.

QS 05 Concurrent Users

Aspect

Description

ID

QS-05

Related Goal

Performance / Throughput, Reliability / Availability

Stimulus

Multiple users play simultaneously

Source

Human players

Environment

Production deployment

Artifact

All services

Response

All users experience normal response times

Response Measure

Support 10+ concurrent users with response time degradation < 50% compared to single user

Priority

Medium

Verification

Load testing with 10 concurrent sessions; monitor response times

10.2.6. Scenario QS-06: Browser Compatibility

This scenario tests the frontend across different browsers.

QS 06 Browser Compatibility

Aspect

Description

ID

QS-06

Related Goal

Portability / Browser Support

Stimulus

User accesses the game from different browsers

Source

Human player

Environment

Latest versions of major browsers

Artifact

Web Frontend (webapp/)

Response

Game renders correctly and is playable

Response Measure

All core functionality works in Chrome, Firefox, and Edge (latest versions)

Priority

Medium

Verification

Cross-browser testing in CI; manual verification

10.2.7. Scenario QS-07: Internationalization

This scenario tests language switching.

QS 07 Internationalization

Aspect

Description

ID

QS-07

Related Goal

Usability / Accessibility (i18n)

Stimulus

User selects Spanish language

Source

Spanish-speaking player

Environment

Normal operation

Artifact

Web Frontend (webapp/)

Response

All UI text appears in Spanish

Response Measure

100% of user-facing strings translated to English and Spanish; no hardcoded English text

Priority

Low (optional feature)

Verification

Automated check for missing translations; language switch test

10.2.8. Scenario QS-08: Unauthorized Access Prevention

This scenario tests authentication and authorization.

QS 08 Unauthorized Access

Aspect

Description

ID

QS-08

Related Goal

Security / Authentication

Stimulus

User attempts to access another user’s data

Source

Malicious or curious user

Environment

Production

Artifact

User Service (users/), API Gateway

Response

System rejects access with 403 Forbidden

Response Measure

100% of cross-user access attempts blocked

Priority

High

Verification

Security tests in CI; penetration testing attempts

10.2.9. Scenario QS-09: Data Persistence

This scenario tests data durability after system restart.

QS 09 Data Persistence

Aspect

Description

ID

QS-09

Related Goal

Reliability / Recoverability, Security / Data Protection

Stimulus

System restarts after shutdown

Source

Maintenance or crash

Environment

Post-restart

Artifact

MongoDB, User Service

Response

All user data and match history are intact

Response Measure

Zero data loss; 100% of records recoverable

Priority

High

Verification

Backup and restore tests; simulate crash and verify data integrity

10.2.10. Scenario QS-10: Code Maintainability

This scenario tests code quality and maintainability.

QS 10 Code Maintainability

Aspect

Description

ID

QS-10

Related Goal

Maintainability / Testability

Stimulus

New developer joins the team and needs to understand the codebase

Source

Onboarding

Environment

Development

Artifact

All services

Response

Developer can locate and modify a simple feature within a day

Response Measure

Code coverage > 80%; cyclomatic complexity < 10 per function

Priority

Medium

Verification

SonarQube metrics; onboarding test with new team member

10.3. Traceability to Quality Goals

This table maps the quality scenarios back to the quality goals defined in Section 1.2.

Quality Goal (Section 1.2)

Related Scenarios

Key Metrics

Functionality

QS-01, QS-03

Correct game rules, multiple AI strategies

Usability

QS-02, QS-07

Learnability (80% success), i18n support (EN+ES)

Modularity & Maintainability

QS-03, QS-10

Extensibility (< 2 days), code coverage (> 80%)

Deployability & Availability

QS-04, QS-05

Recovery time (< 30 sec), concurrent users (10+)

Testability

QS-10 (indirect)

Test coverage > 80%

Interoperability

(covered in Section 6)

API works for external bots

11. Risks and Technical Debts

Following the principle that "risk management is project management for grown-ups" (Tim Lister), we systematically evaluate and track items that could impact project success.

Each item is assessed using a risk matrix:

  • Probability: Low (1), Medium (2), High (3)

  • Impact: Low (1), Medium (2), High (3)

  • Risk Score = Probability × Impact (1-9)

Items with score ≥ 6 require active mitigation. Items with score ≥ 8 are critical and require immediate attention.

11.1. Technical Risks

The following table lists identified technical risks, ordered by Risk Score (highest first).

ID Risk Description Prob (1-3) Impact (1-3) Score Mitigation Strategy

R1

Rust learning curve – Team lacks Rust experience

3 (H)

3 (H)

9

• Learning sprint (week 1) • Pair programming • Focus on core game verification first • Use Rust’s type system

R2

TypeScript-Rust integration – Communication bugs between services

3 (H)

3 (H)

9

• Versioned JSON interface (YEN) • Contract tests • Integration tests in CI • OpenAPI docs

R3

Game Y rules misunderstanding – Incorrect implementation

2 (M)

3 (H)

6

• Domain analysis session • Shared glossary • Walking skeleton early • Reference authoritative sources

R4

Scope creep – Optional features delay mandatory ones

2 (M)

3 (H)

6

• MoSCoW prioritization • Clear DoD for optional features • Feature flags

R5

API stability for bots – Changes break external bots

2 (M)

2 (M)

4

• Versioned API (/v1/) • Documentation • Deprecation policy (6 months) • Compatibility tests

R6

AI performance – Slow on large boards

2 (M)

2 (M)

4

• Performance budget (< 2s) • Early profiling • CI performance tests

R7

DevOps complexity – Inconsistent deployments

2 (M)

2 (M)

4

• Docker + docker-compose • CI/CD automation • Environment parity

R8

MongoDB data loss – Corruption or deletion

1 (L)

3 (H)

3

• Daily backups • 30-day retention • Monthly restore tests • Replication

R9

JWT vulnerability – Weak secrets or token leakage

1 (L)

3 (H)

3

• Strong secrets (env vars) • Short expiration (1h) • Refresh tokens • GitHub Secrets

R10

Gateway single point of failure – Entire system down if gateway fails

1 (L)

3 (H)

3

• Stateless design • Multiple instances • Docker restart • Prometheus monitoring

11.2. Technical Debts

Technical debts are already incurred design or implementation shortcuts that need to be addressed. These are tracked separately from risks.

ID Debt Description Impact if not fixed Planned Resolution

TD1

Frontend Component Duplication – Similar UI components (buttons, modals) are duplicated across files instead of using a shared library

Medium – Inconsistent UI, harder maintenance

Refactor to use shared component library

TD2

Hardcoded Configuration – Some API endpoints are hardcoded in frontend instead of using environment variables

Low – Works in dev but causes issues in prod

Move all configuration to .env files

TD3

Missing Input Validation – Some user inputs in forms lack client-side validation

Medium – Poor user experience, extra server load

Add validation to all forms

TD4

Incomplete Test Coverage – Some modules have < 70% test coverage

Medium – Higher risk of undetected bugs

Increase coverage to 80% (per QS-10)

12. Glossary

This glossary defines the most important domain and technical terms used throughout the YOVI project. It ensures that all stakeholders (developers, client, evaluators, bot developers) have an identical understanding of these terms.

12.1. Domain Terms

Term Definition

YOVI

The name of the system developed in this project. A web-based platform for playing Game Y, supporting human players and external bots.

Game Y

An abstract strategy board game in which players aim to connect three different sides of the board. The game is played on a triangular or hexagonal grid.

Classic Game Y

The standard version of Game Y defined by the original rules, without additional variants or optional mechanics. This is the mandatory implementation for the project.

Game Variant

An alternative version of Game Y with modified rules, such as Poly-Y, Hex, Tabu Y, or Holey Y. These are optional features.

Player

A human user who interacts with the system through the web frontend to play games.

Bot

An external program that interacts with the system exclusively through the public API to retrieve information and play games automatically. Bots have no UI.

Player-versus-Machine (PvM)

A game mode in which a human player competes against a computer-controlled opponent (AI).

Match / Game Session

A single instance of a game, from initialization to completion, including all moves and the final result.

Move

A single action by a player placing a piece on the board. Represented in YEN notation.

Strategy

A specific algorithm or heuristic used by the AI to determine its next move. Examples: Random, Heuristic, Minimax.

Difficulty Level

A configuration of the AI strategy that affects its playing strength. Usually implemented by varying strategy parameters or search depth.

User Registration

The process of creating an account in the system, providing username, password, and optionally email.

Match History

A record of all games played by a user, including date, opponent (human/bot), result, and moves.

Statistics

Aggregated metrics about a user’s performance, such as total games played, wins, losses, and win rate.

Leaderboard

An optional feature ranking users based on various metrics (win rate, games played, etc.).

12.2. Technical Terms

Term Definition

Architecture Decision Record (ADR)

A document that captures an important architectural decision, including context, rationale, alternatives considered, and consequences. ADRs are stored in the project wiki.

API Gateway

A service that acts as a single entry point for all external requests. Routes requests to the appropriate internal service (webapp, users, gamey) and handles SSL termination.

Microservice

An architectural style in which a system is composed of small, independent services that communicate over a network and can be developed, deployed, and scaled separately. YOVI uses three microservices.

Web Frontend Service (webapp/)

The TypeScript/React service that provides the user interface for human players. Handles game rendering, user interaction, and API calls to backend services.

User Service (users/)

The Node.js/Express service responsible for user management: registration, authentication, profile storage, match history, and statistics.

Game Engine Service (gamey/)

The Rust service that implements all Game Y logic: move validation, win condition checking, and AI move calculation with multiple strategies.

MongoDB

The NoSQL database used by the User Service to persist user profiles, authentication data, and match history.

Docker

A containerization platform used to package each service with its dependencies, ensuring consistent execution across development, test, and production environments.

docker-compose

A tool for defining and running multi-container Docker applications. Used to orchestrate all YOVI services locally and in production.

CI/CD (Continuous Integration / Continuous Deployment)

An automated pipeline (using GitHub Actions) that builds, tests, and deploys the system whenever changes are pushed to the repository.

GitHub Actions

The CI/CD platform used for automated testing, building, and deployment of the YOVI system.

SonarQube

A code quality analysis tool integrated into the CI pipeline to monitor test coverage, code smells, bugs, and technical debt.

Prometheus

A monitoring and metrics collection tool used to gather performance data from all services.

Grafana

A visualization tool that creates dashboards from Prometheus metrics, used for monitoring system health.

JWT (JSON Web Token)

A compact, URL-safe token used for stateless authentication. Contains user identity and claims, signed with a secret key.

YEN Notation

A JSON-based notation used to represent the state of a Game Y match, including board size, current turn, players, and board layout. Mandated by the client.

REST API

An architectural style for designing networked applications. YOVI exposes RESTful APIs for all service-to-service and external communication.

HTTP / HTTPS

Hypertext Transfer Protocol (Secure). The application-layer protocol used for all communication between clients, bots, and services.

JSON

JavaScript Object Notation. A lightweight data-interchange format used for all API payloads, especially YEN notation.

TypeScript

A statically typed programming language that extends JavaScript, used to implement the web frontend.

Rust

A systems programming language focused on safety and performance, used to implement the game engine.

Node.js

A JavaScript runtime used to execute the User Service backend.

Express

A web framework for Node.js used to build the User Service REST API.

React

A JavaScript library for building user interfaces, used in the web frontend.

12.3. Acronyms

Acronym Definition

ADR

Architecture Decision Record

API

Application Programming Interface

CI/CD

Continuous Integration / Continuous Deployment

DoD

Definition of Done

HTTP

Hypertext Transfer Protocol

HTTPS

Hypertext Transfer Protocol Secure

i18n

Internationalization

JSON

JavaScript Object Notation

JWT

JSON Web Token

MVC

Model-View-Controller

ODM

Object Document Mapper

PvM

Player versus Machine

REST

Representational State Transfer

SSL

Secure Sockets Layer

TLS

Transport Layer Security

UI

User Interface

UX

User Experience

VM

Virtual Machine

YEN

Y Notation (specific to Game Y)