yovi_en1a

The project aims to develop a full-stack web application for a game named YOVI, communicating human players and automated agents. The following high level specifications must be in the final version of the application:

Technical constraints define the specific technologies and tools that must be used.

Architectural constraints are the high-level design requirements that dictate the system’s structure.

Organizational constraints relate to the project management and academic requirements.

Conventions are the rules agreed upon by the team to ensure consistency.

The business context defines how YOVI interacts with external entities. The system acts as a standardized provider for both human players and third-party bots, ensuring interoperability through the YEN notation.

External Domain Interfaces:

The YOVI_0 architecture follows a microservices-inspired model. All communication between the React-based frontend and the specialized services is handled over network calls.

Mapping Input/Output to Channels:

The system architecture bridges mandated technical constraints with strategic choices focused on security, internationalization, and performance.

The system follows a microservices-oriented approach to ensure a clean separation of concerns:

Level 1 represents the highest level of abstraction, showing the main subsystems of the YOVI_EN1A system and their interactions. Each subsystem is responsible for a specific aspect of the system’s functionality, and they communicate with each other to fulfill the requirements of the project.

The following diagram shows the top-level decomposition of the YOVI_EN1A system into its four primary subsystems: the Frontend (Webapp), the User Management (User Service), the API Gateway (GameY API), and the Logic Engine (GameY).

The Webapp is a Single Page Application (SPA) built with React and Vite. It acts as the primary user interface and the orchestrator of requests between the User Service and the GameY API Gateway.

The GameY Engine is a high-performance Rust subsystem responsible for the rules of the "Game of Y". It is structured as both a Library (lib.rs) for core logic and a Binary (main.rs) that provides a Command-Line Interface (CLI) and an HTTP Bot Server.

The User Service is a Node.js/Express application responsible for user identity management. It handles registration, login, password hashing, and JWT token generation.

The GameY API Gateway is a Node.js/Express service that orchestrates active game sessions, routes moves to the Rust engine, handles win detection, and persists completed games to MongoDB.

Description: The entry point where a user creates an account or authenticates via the RegisterForm. Trigger: User submits credentials. The component determines the endpoint based on the mode state ('login' or 'register'). Endpoint(s): POST :3000/createuser or POST :3000/login.

Description: Orchestrating a move in "Human vs Bot" (hvb) mode. Trigger: Player clicks a cell on the GameBoard. Endpoint(s): POST :3001/play/:gameId/move and internal proxy to POST :4000/v1/ybot/choose/:bot_id.

Description: Handling illegal moves (e.g., clicking an occupied cell or playing out of turn). Trigger: User attempts an invalid action. Endpoint(s): POST :3001/play/:gameId/move.

Description: Saving game results to the permanent match history upon completion. Trigger: updateWinStatus(s) sets state to 'finished'. Endpoint(s): Internal call to saveGameResult(session).

Description: Fetching match history and updating user personalization. Trigger: User navigates to ?view=profile or selects a new avatar. Endpoint(s): GET :3001/profile and POST :3001/profile/avatar.

All containers communicate over the monitor-net bridge network (Docker default bridge driver). The following ports are exposed to the host:

We need a database for the game backend to store player data, game sessions, and other game-related entities. The data model is expected to evolve during development.

We decided to use MongoDB as our primary Database Management System (DBMS). Unlike relational databases such as MySQL, MongoDB uses a document model based on BSON/JSON-like structures. It integrates well with web applications and is suited for self-contained entities like players and game sessions.

The flexible schema of MongoDB makes it easier to adapt the data model and acts as a natural fit for our JSON-based web backends. The primary alternative, MySQL, was considered due to the team’s familiarity with it, but MongoDB’s schema flexibility was deemed more important. As a consequence, the team requires some time to learn MongoDB, and the system is less suited for complex relational queries compared to SQL databases.

The project requires a reliable and scalable environment to host the application and its associated services, primarily our Docker containers and Node.js instances. The chosen cloud provider needs to offer robust Virtual Machine management, global availability, and integration with DevOps workflows.

We selected Microsoft Azure (Azure Virtual Machines) to host our infrastructure. Azure provides seamless integration with GitHub Actions for our CI/CD pipelines and offers "Azure for Students" credits, which fits the constraints of our academic project. It also provides a web portal for monitoring VM health.

While alternatives like AWS (Amazon Web Services) and Google Cloud Platform (GCP) are prominent in the cloud landscape, standardizing on Azure simplifies our deployment pipeline without introducing a steeper learning curve regarding billing or disconnecting us from existing academic subscriptions. Using Azure still requires us to monitor credit usage and accept specific Azure CLI tools.

The application uses a microservices architecture (users-service and gameyapi). We need a secure, stateless method to share user identity across these boundaries without querying a central database for session validation on every API call.

We chose JSON Web Tokens (JWT) for authentication. Upon a successful login, the users-service generates a signed token containing the user’s ID and username. Secret management uses .env files locally and GitHub Secrets in production to protect the JWT_SECRET. Consumer services like gameyapi verify the token locally using this shared secret.

Session-based authentication was discarded because it requires centralized stores like Redis, which increases latency. Opaque tokens were bypassed because they require resource servers to constantly contact the authentication service. JWTs improve performance through localized verification and allow horizontal scalability. However, this introduces security risks if the secret is compromised, and prevents instantly revoking specific active sessions.

The game services must handle concurrent players without performance degradation. We require load tests that simulate realistic user flows crossing multiple microservices.

We selected Gatling for load testing. Gatling simulations are written in a Scala/Java Domain-Specific Language (DSL) and execute against our staging environment during CI pipelines. Pipelines fail automatically if p95 response times or error rates exceed agreed thresholds. Gatling generates HTML reports after execution.

While other tools like JMeter use an XML-heavy format that is difficult to version-control, and options like k6 do not leverage our team’s existing JVM expertise, choosing Gatling ensures simulations live directly in version control and robustly handle stateful user flows. The primary downside is the needed Scala ramp-up time for developers lacking JVM experience.

To validate that backend and API logics execute according to defined business rules, we required a testing framework capable of matching behavioral specifications to executable code.

We integrated Cucumber for our API-level and functional End-To-End (E2E) tests. Cucumber allows us to write tests using natural language formats (Given/When/Then), directly bridging specifications and code assertions. This ensures our APIs behave exactly as requested by stakeholders.

The application provides a web frontend managing registration, authentication, and gameplay. To ensure user interface flows behave correctly across varied browsers, we need an automated browser testing setup to complement our Cucumber scenarios.

We implemented Playwright as our frontend UI testing framework. Tests run in TypeScript against Chromium, Firefox, and WebKit to catch browser-specific rendering flaws. In scenarios where login is not tested, the JWT is injected directly to maintain execution speed.

Compared to tools like Selenium, which can be slower with excessive setup boilerplate, or Cypress, which is often tightly bound to Chromium and challenges cross-browser testing needs, Playwright effectively centralizes our test suite. It reduces flakiness through built-in auto-waiting mechanisms. The trade-off is the inherent fragility of UI tests and the extended CI execution times required for multiple browser engines.

The users-service handles player registration and login. Passwords must be hashed securely to prevent raw credentials from being exposed in case of a database breach.

We standardized on bcrypt as the main library to hash and verify passwords. Passwords are hashed with salt and never persist as plain text. Upon login, bcrypt evaluates the injected password against the stored hash before issuing a JWT.

Fast hashing algorithms like MD5 or SHA-256 without key stretching were disqualified because they are easily cracked by modern hardware. Argon2 was considered but passed over due to its smaller ecosystem in Node.js compared to bcrypt. While bcrypt’s scalable workload provides strong security, developers must use its asynchronous methods to prevent blocking the Node.js event loop.

The game aims to reach players across multiple language regions. Hardcoding strings into React components requires expensive refactoring later.

We integrated react-i18next as our internationalization framework early in development. All user-facing strings are extracted into locale-specific JSON files, allowing frontend code to reference descriptive translation keys. English acts as the fallback locale when a token is missing.

By avoiding hardcoded layouts, we uncoupled the translation process from the codebase. Translators can manage the JSON files independently. This requires strict discipline from the frontend team to extract new strings immediately and maintain organized key naming conventions.

The application needs a backend orchestration service to manage game sessions, route player moves to the bot engine, and store match results in the database.

We built the gameyapi as a Node.js REST API utilizing the Express framework. It communicates via JSON and trusts authenticated JWTs. The service stores ongoing game sessions in memory and only persists completed classic-mode games to MongoDB.

Python with FastAPI was considered for its async capabilities, but the team opted for Node.js to reuse JavaScript tooling and knowledge. A pure Rust solution was discarded because routing API traffic is faster to iterate on in JavaScript, while calculation burdens remain delegated to the Rust service. This design capitalizes on Node’s async I/O strengths, but risks losing active in-memory games if the Node process restarts unexpectedly.

The following quality tree summarizes the most important quality goals and links them to the concrete scenarios described in the next section. Higher-priority goals are listed first.

Our testing strategy focuses on verifying the reliability of both the internal logic and the interaction between microservices. We employ a "bottom-up" approach, moving from isolated utility functions to full API endpoint validation.

Acceptance testing ensures the application fulfills the business requirements by simulating real user behavior across different environments.

To evaluate if the application is intuitive and identify visual or flow weaknesses, we conducted a moderated usability test with external users.

We use Gatling (bundle, version 3.10.5) to implement load tests over our deployed application. The signup functionality, which creates users from the users service API was tested, along with the game service, which checks multiple moves in the board of GameY.

In order to record the requests, we used the recorder script. Using Mozilla Firefox and configuring a proxy for localhost’s port 8000, we record interactions with the app (signup, moves in board,) and they are recorded in request file in resources. Simulation file YoviEn1aLoadTest.java is generated as well.

We modify the simulation for managing 100-150 randomized users interacting with the application at once. Approximately, we send 330 requests to the system at once, at it can manage it. After executing, we get 0 KO messages and this results, showing a good management of a bigger user quantity: