1. Introduction and Goals
1.1. Requirements Overview
1.1.1. Related to Gameplay
-
The system must allow users to play a complete match of the classic Game Y, following the official rules and supporting different board sizes.
-
The application must allow the user to select the difficulty level before starting a match.
-
The system must correctly detect the win condition and determine when a match has ended.
-
After the match finishes, the system must display an end-game summary screen including relevant statistics such as match duration, number of moves, difficulty level, and winner.
-
The application must allow users to view rankings, including local and global rankings.
-
The system must provide a tutorial or help section explaining the rules of Game Y and how to interact with the interface.
1.1.2. Related to the AI Service
-
The system must provide an AI opponent capable of generating valid moves according to the selected difficulty level.
-
The AI must always generate legal moves and must never violate the rules of Game Y.
1.1.3. Related to the Persistence Layer
-
The system must store user accounts and authentication data securely.
-
This service must store match results, including outcome, duration, difficulty, and player statistics.
1.1.4. Related to the Authentication System
-
The system must allow users to register or log in with valid credentials.
-
It also shall include an option to play as a Guest without requiring authentication.
1.2. Quality Goals
| Quality Goal | Description |
|---|---|
Functional Suitability |
The system shall correctly implement the classic version of Game Y, including win-condition verification for any supported board size. All user-facing features (play game, select strategy, view statistics) and API operations shall behave according to the specified requirements. |
Performance Efficiency |
For a standard match, the system shall return a computer move or API response within 1 second under normal load. The architecture shall support at least 20 concurrent players without noticeable degradation in responsiveness. |
Reliability |
The system shall consistently determine correct game outcomes and suggested moves, with an error rate of less than 1% in win detection or AI move generation. User data and match history shall not be lost during normal operation. |
Usability |
First-time users shall be able to start and complete a game without external help. The web interface shall clearly display the board state, available actions, and game status. The learning time for basic gameplay should be less than 30 minutes. |
Maintainability |
The architecture shall allow new AI strategies, difficulty levels, or Game Y variants to be added without major refactoring. Clear module boundaries and documented interfaces shall enable developers to modify or extend functionality efficiently. |
Security |
User accounts and personal data shall be protected through proper authentication and authorization mechanisms. API endpoints shall restrict access to authorized clients and prevent unauthorized manipulation of game or user data. |
1.3. Stakeholders
| Role/Name | Contact | Expectations |
|---|---|---|
Owner [Client] |
He is the main client of the system, for he enforces expected behaviors and has to be the most satisfied stakeholder. |
|
Dev Team |
Jaime Alonso, Pelayo Pérez, Ana Calleja, David García, Matías Valle |
They are the ones that implement and determine whether a problem may be solved given the constraints, being able to discuss with the client (Labra). |
Game Y rules |
Inmutable statement that define de rules for playing the vanilla version of the game. Shall be followed. |
|
Final users |
There is no direct communication though social media or polls may be useful |
They will be the main enjoyers of the system, they shall communicate errors and tell thing they are not really keen on or improvements. The system shall be design expecting them to use it. |
Server |
??? |
It will include all of the different parts of the game dockerized allowing acccess to all users. |
Google Workspace DDBB |
Firebase |
It is a no relational DDBB that will store all the persistent information regarding the users and the games. |
… |
… |
… |

2. Architecture Constraints
2.1. Technical Constraints
| Constraint | Explanation |
|---|---|
Web application must be implemented in TypeScript/JavaScript |
The frontend and external API are required to be developed using TypeScript/JavaScript as specified in the assignment. |
Bot logic must be implemented in Rust |
The game engine responsible for move suggestion and win detection must be developed as a separate Rust module. |
Communication between subsystems via JSON using YEN notation |
The web application and the Rust service must exchange data using JSON messages following the YEN game notation defined in the assignment. |
Service-oriented architecture |
The Rust module must expose its functionality through a web service interface callable by the web application. |
Use of Firebase as the database |
User data, match history, and statistics must be stored in Firebase, as chosen by the team. |
Deployment on a cloud platform |
The system must be publicly accessible. The backend services will be deployed on a cloud provider (e.g., Vercel, Railway, or Azure). |
Public external API for bots |
The system must expose a documented API allowing external bots to access game data and play matches. |
Browser-based execution |
The frontend must run in standard modern web browsers without requiring special installations. |
2.2. Organizational Constraints
| Constraint | Explanation |
|---|---|
Assignment requirements define core functionality |
The system must implement at least the classic version of Game Y with player-vs-machine mode and variable board size. |
Public deployment required |
The application must be accessible through the web as part of the evaluation criteria. |
Documentation must follow arc42 |
Architecture documentation must comply with the arc42 structure provided by the course. |
Quality requirements for evaluation |
The project must include testing (unit, integration, and e2e), CI/CD, monitoring, and proper repository management. |
Team-based academic project |
Decisions must consider limited time, resources, and team size typical of a university assignment. |
2.3. Conventions and Standards
| Constraint | Explanation |
|---|---|
Use of YEN notation for game state |
All game states exchanged between components must follow the defined YEN notation format. |
REST-style API with JSON |
All external and internal services will communicate using JSON over HTTP. |
Version control with Git |
All source code and documentation will be managed using a Git repository. |
Code quality and testing practices |
The project must include automated tests and follow agreed coding standards. |
3. Context and Scope
3.1. Business Context
The folloing table includes the different bussines components of the application, ecxplaining for each their points of interaction with the rest of the system.
| Element | Description | Inputs | Outputs |
|---|---|---|---|
Player |
Takes part in the game, is able to create a user in the application and launch a game either against a bot or against a local opponent |
the current state of the game and any requested statistics |
their username and password as well as their moves and requests |
Interface |
Shows the user the current state of the match as well as any relevant information |
all the user’s interactions with its components as well as the moves and information obtained from the game engine and database respectively |
the updated state of the game and statistics |
Engine |
generates the bot moves in a PvE game |
the user’s move coordinates |
the following bot move |
Database |
stores infromation about past matches |
the data from played games |
information requested by the player to be displayed by the ui |
3.2. Technical Context
The following table describes the technical interfaces and the channels used to link the system components and external entities.
| Component / Channel | Description |
|---|---|
User Device |
Computer, laptop, or mobile device used to access the system via a secure HTTPS connection. |
Web Application (Frontend) |
Developed in TypeScript. Manages matches, communicates with the Rust module, and interacts with Firebase and the Bot API. |
Rust Game Logic Module |
Component responsible for match outcomes and bot moves. Exposes a web service endpoint for the Frontend. |
Firebase Database |
Cloud persistence layer for user information and statistics via Firebase SDK. |
Public API for Bots |
Interface for external bots to interact with the system over HTTPS. |
Deployment Platform (Azure) |
Cloud infrastructure hosting the Rust backend and WebApp, ensuring HTTPS and availability. |
3.2.1. Mapping Input/Output to Channels
The following table maps the domain-specific inputs and outputs to their respective technical channels and protocols.
| Channel | Input | Output |
|---|---|---|
HTTPS (Browser → WebApp) |
User moves, bot strategy selection, login registration info. |
Board updates, results, statistics. |
HTTP JSON/YEN (WebApp → Rust) |
Board state (YEN), active player, strategy. |
Match outcome, bot move. |
Firebase SDK (WebApp ↔ Firebase) |
User registration, results, statistics. |
Data persistence and retrieval. |
HTTPS (API → Bot) |
Board state (YEN), strategy parameters. |
Bot move response. |
4. Solution Strategy
4.1. Technical Decisions
-
Firebase is the chosen data base management tool for our project.
-
All of the bot logic will be implemented in rust.
-
We will implement our user interface using the react javaScript library because it allows us to organize and reuse our ui components easily.
-
Docker will be used to launch the project in the same way regardless of hardware.
4.2. Organizational Decisions
-
We are using github to organize the project’s developement, using the wiki to document our meetings and using the branch protection features to avoid mistakes and make sure every push to a main brach is reviewed by another team member.
4.3. Level 1
5. Building Block View
5.1. Whitebox Overall System
- Motivation
-
The system uses a hybrid backend approach. Firebase is used as a Third-Party Building Block to offload identity management and real-time state persistence. This allows the Users Service to focus on custom business logic and the Game Engine (Rust) to handle CPU-intensive game mechanics without managing user sessions directly.
- Contained Building Blocks
| Name | Responsibility |
|---|---|
Webapp |
Frontend SPA that coordinates User-Firebase-Engine interactions. |
Users Service |
Backend orchestration, monitoring, and providing an OpenAPI-compliant gateway for administrative tasks. |
Game Engine |
High-speed game processing, bot AI management, and move validation. |
Firebase |
External black box providing Authentication and cloud-based data storage. |
- Important Interfaces
-
-
Firebase SDK Interface: Client-side link for Auth and Realtime updates.
-
Gamey WebSocket/gRPC: Low-latency interface for game move submission to the Rust engine.
-
5.1.1. Webapp
- Purpose/Responsibility
-
Coordinates the user experience. It uses Firebase for Authentication and the Game Engine for the actual gaming logic.
- Interface(s)
-
React Hooks for Firebase; REST client for Users Service.
- Directory/File Location
-
/webapp
5.1.2. Users Service
- Purpose/Responsibility
-
Provides a secure layer for user-related logic that shouldn’t live on the client. It uses the Firebase Admin SDK to verify identities.
- Interface(s)
-
Exposes endpoints defined in
openapi.yaml. - Directory/File Location
-
/users
5.1.3. Game Engine
- Purpose/Responsibility
-
The computational core. It is agnostic of user identity (delegated to other blocks) and focuses on the game rules.
- Directory/File Location
-
/gamey
5.2. Level 2
5.2.1. White Box Game Engine (Rust)
The Game Engine is organized as a modular Rust crate. The core module is strictly separated from the bot_server to allow for local CLI usage or networked server usage.
5.2.2. White Box Users Service (Node.js)
-
users-service.js: Main entry point using Express.
-
Firebase Admin Logic: Middleware to intercept requests and validate Firebase JWT tokens.
-
monitoring/: Dedicated module for service health and logging.
5.3. Level 3
(Not really sure if it is even detailed)
6. Runtime View
6.1. <Runtime Scenario 1>
-
<insert runtime diagram or textual description of the scenario>
-
<insert description of the notable aspects of the interactions between the building block instances depicted in this diagram.>
It is possible to use a sequence diagram:
6.2. <Runtime Scenario 2>
6.3. …
6.4. <Runtime Scenario n>
7. Deployment View
7.1. Infrastructure Level 1
- Motivation
-
The system is containerized to ensure environment parity between development and production. Since the Gamey Engine is built in Rust, it requires a high-performance runtime environment, while the Users Service and Webapp benefit from the managed scalability of Firebase and standard Node.js container hosting.
- Quality and/or Performance Features
-
-
Scalability: The Rust Game Engine can be scaled vertically or horizontally depending on the number of active game sessions.
-
Latency: WebSockets are used for the Game Engine to minimize overhead during competitive play.
-
Security: Sensitive user data is offloaded to Firebase, reducing the attack surface of the self-hosted infrastructure.
-
- Mapping of Building Blocks to Infrastructure
| Building Block | Infrastructure Element |
|---|---|
Webapp |
Distributed via Content Delivery Network (CDN) for low-latency frontend delivery. |
Users Service |
Deployed as a Docker container (referencing |
Gamey Engine |
Deployed as a high-performance Docker container (referencing |
Database/Auth |
Managed by Firebase (Google Cloud Infrastructure). |
7.2. Infrastructure Level 2
7.2.1. Docker Environment (Internal Node)
Each service (Users and Gamey) is encapsulated in a Docker image to isolate dependencies.
Users Service Node:
-
Runtime: Node.js 20+.
-
Config: Environment variables for Firebase Admin credentials.
-
Port: Exposes 3000 (REST API).
Game Engine Node:
-
Runtime: Scratch or Debian-slim (for the compiled Rust binary).
-
Performance: Optimized with LTO (Link Time Optimization) during the build stage.
-
Port: Exposes 8080 (WebSockets/gRPC).
8. Cross-cutting Concepts
8.1. <Concept 1>
<explanation>
8.2. <Concept 2>
<explanation>
…
8.3. <Concept n>
<explanation>
9. Architecture Decisions
This section documents the most important architectural decisions made during the development of the system. Each decision includes its context, the chosen option, and the rationale.
9.1. ADR-001: Separation into Web Application and Rust Game Engine
Status: Accepted
Context: The assignment requires the system to be composed of at least two subsystems: - A web application implemented in TypeScript. - A game logic module implemented in Rust.
Decision: The system will follow a service-oriented architecture where: - The web application handles the user interface, API, and user management. - The Rust module provides game logic (win detection and move suggestion) through a web service.
Rationale: - Required by the assignment. - Separates concerns between UI and game logic. - Rust provides high performance for algorithmic computations.
Consequences: - Requires inter-service communication via HTTP and JSON. - Adds deployment and integration complexity.
9.2. ADR-002: Communication via JSON using YEN Notation
Status: Accepted
Context: The assignment specifies that both subsystems must communicate using JSON messages following YEN notation.
Decision: All communication between the web application and the Rust service will use: - HTTP requests - JSON payloads - YEN notation for game states
Rationale: - Mandatory requirement from the assignment. - JSON is simple, widely supported, and easy to debug.
Consequences: - Both services must implement serialization and validation of YEN data. - Changes to the notation would affect both subsystems.
9.3. ADR-003: Use of Firebase as the Database
Status: Accepted
Context: The system requires user registration, match history, and statistics storage.
Possible options: - Self-hosted database (PostgreSQL, MySQL) - Managed cloud database - Firebase
Decision: Use Firebase as the main data storage solution.
Rationale: - Fully managed service with minimal setup. - Built-in authentication and real-time database features. - Reduces infrastructure and maintenance effort. - Suitable for small-to-medium academic projects.
Consequences: - Vendor lock-in to Firebase ecosystem. - Limited flexibility compared to self-hosted databases. - Requires internet connectivity for all operations.
9.4. ADR-004: Cloud Deployment of the Application
Status: Accepted
Context: The assignment requires the system to be publicly accessible via the web.
Possible hosting options: - Local/on-premise server - Traditional VM hosting - Cloud platform (Vercel, Railway, Azure)
Decision: Deploy the system on a cloud platform, with the final choice between: - Vercel - Railway - Azure
Rationale: - Meets the public deployment requirement. - Simplifies infrastructure management. - Enables CI/CD and easy scaling.
Consequences: - Requires configuration for cloud environments. - Possible cost considerations. - Platform-specific deployment setups.
9.5. ADR-005: External REST API for Bots
Status: Accepted
Context: The assignment requires an API that allows external bots to interact with the system and play games.
Decision: Expose a REST-style HTTP API that: - Accepts JSON requests. - Uses YEN notation for game state. - Provides endpoints for game interaction.
Rationale: - REST is simple and widely supported. - Easy integration with external bots. - Matches the JSON communication requirement.
Consequences: - Requires proper authentication and validation. - Must be fully documented.
10. Quality Requirements
10.1. Quality Tree

Explanation: This quality tree is structured from ISO 25010-inspired categories. Each main branch (Functional, Performance, etc.) links to more concrete sub-goals, which are then detailed in the scenarios below.
10.2. Quality Scenarios
| Quality Attribute | Scenario | Stimulus | Environment | Response | Metric / Success Criteria |
|---|---|---|---|---|---|
Functional Suitability |
Correct game logic |
A player makes a move |
Web frontend or bot API |
The system updates the board and verifies the win condition |
Must correctly determine game state |
Functional Suitability |
API operation correctness |
External bot calls the 'play' endpoint |
System running normally |
System returns next move in YEN notation |
Response contains valid move; no invalid game states |
Performance Efficiency |
Fast move computation |
Player requests next move |
Normal load (~1 concurrent player) |
System calculates AI move |
Response returned within 1 second |
Performance Efficiency |
Handle concurrency |
Multiple users/bots interact simultaneously |
Normal server load |
System serves all requests |
20 concurrent matches without noticeable lag |
Reliability |
Accurate game outcome |
Match completes |
Normal operation |
System records winner/loser correctly |
<1% error rate in win detection or move suggestion |
Reliability |
Data persistence |
Unexpected restart or refresh |
Web app and backend running |
User stats and match history retained |
No loss of game or user data |
Usability |
Learnability |
New user starts first game |
First-time user accesses web frontend |
User can complete a match |
Game completed without external help; <30 min to understand basic rules |
Usability |
Board clarity |
Player observes board and options |
Normal gameplay |
Actions and current game state are clearly displayed |
User can easily understand current turn, available moves, and game status |
Maintainability |
Extend AI strategies |
Developers add new AI strategy or difficulty |
Source code maintained and documented |
System integrates new strategy without breaking existing features |
Minimal code changes needed; no regression errors |
Maintainability |
Clear module interfaces |
Developers modify Rust module or frontend |
Existing system deployed |
Interfaces documented; components interact correctly |
Changes localized; integration works without extensive refactoring |
Security |
Authentication |
User logs in |
Public internet |
System verifies credentials |
Unauthorized access denied; valid users granted access |
Security |
API protection |
External bot tries to call API |
System exposed to network |
API checks credentials and permissions |
Unauthorized requests blocked; only authorized clients allowed |
11. Risks and Technical Debts
12. Glossary
| Term | Definition |
|---|---|
<Term-1> |
<definition-1> |
<Term-2> |
<definition-2> |
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.
