yovi_en1a

The internal behavior of this module is driven by the state within RegisterForm.tsx:

The GameY module operates through distinct execution patterns:

The system runs on a single Azure Virtual Machine (Ubuntu 24.04 LTS). Azure was chosen for its reliability and easy VM setup. A single VM keeps costs low while still resembling a real production environment. All components are containerized with Docker so that the setup works the same way in development and in production, and deployments via GitHub Actions stay simple.

Docker Compose manages all containers in a single configuration file. All services run on a shared internal network (monitor-net) so they can talk to each other without exposing unnecessary ports to the outside. The Webapp is compiled with the backend URLs baked in at build time (VITE_API_URL, VITE_GAMEY_URL), so no extra runtime configuration is needed.

The diagram below shows how containers are connected inside monitor-net. Grafana maps its internal port 3000 to host port 9091 to avoid clashing with the Users service.

The application requires its data to survive when containers restart. Prometheus and Grafana use bind mounts so their configuration files live directly in the repository and are version-controlled like any other code. MongoDB uses a named Docker volume so that user and game data persists across docker-compose down and up cycles without any manual intervention.

The core domain of the application revolves around the "Classic Version" of Game Y. The game environment is based on variable-sized hexagonal boards. The system supports multiple coordinate representations for these grids: * Barycentric Coordinates (x,y,z): Used to represent three-dimensional positioning in a 2D hexagonal space. * Index-based Coordinates (0…​n): Linear representation for simpler indexing in arrays or matrices.

All game states are uniformly formatted using the YEN Notation, which dictates how board sizes, player turns, and piece positions are serialized. This ensures consistent state representation across the Frontend, the Logic Engine, and external bots.

A YEN string encodes the complete game state in a compact, human-readable format. For example, on a 3×3 board where Blue has played two cells and Red has played one:

The concrete service breakdown (Webapp, User Service, Logic Engine) is described in Sections 4 and 5. The cross-cutting design rules that govern the microservice decomposition are:

The Logic Engine is intentionally stateless. Current game states (in JSON format) are passed within each request, allowing the engine to calculate AI behavior or determine win/loss states without storing active match sessions in memory.

Communication both internally (between subsystems) and externally (third-party bots) relies fully on HTTP REST APIs utilizing JSON. * Internal APIs: The User Service and Logic Engine communicate with the Webapp using predefined JSON schemas strictly validating YEN notation. * External Bot Interface: The system provides dedicated endpoints (e.g., a play method) for third-party bots to interact with the engine.

For real-time interactions, particularly in the "Human vs. Human" multiplayer scenario, the architecture envisions asynchronous push communication. Instead of relying on inefficient client-side polling, the Node.js User Service will actively push game state updates (e.g., opponent moves) directly to the connected React clients via WebSockets. * Current State: Asynchronous push communication is planned but not yet implemented. The current system relies exclusively on RESTapi calls. * Future Updates: Once WebSockets (e.g., via Socket.IO) are integrated, this section will be expanded with the specific event structures and network flow diagrams.

The technology choice (MongoDB) is documented in Sections 4 and 7. The cross-cutting design rule for persistence is how domain relationships are mapped to documents:

Service configuration (ports, upstream URLs, database connection strings) is managed through environment variables that are injected via docker-compose.yml.

Because the Webapp (Port 80) communicates with backend APIs on different ports (3000, 3001, 4000), CORS must be configured explicitly.

In the Frontend Webapp, complex match states and user actions are managed reactively. * State Trees: React manages the active game properties (board layout, opponent type, current turn) locally to provide instant visual feedback without blocking for server responses during non-validating actions. * Hexagonal UI Representation: The UI seamlessly maps the engine-provided mathematical coordinate arrays (Barycentric or Index-based) onto visual hexagonal grids for intuitive gameplay.

All services emit logs exclusively to stdout/stderr, which allows the Docker container runtime to collect and forward them transparently. No dedicated log-aggregation sidecar is required for the current setup.

The system uses a layered error propagation model based on standard HTTP semantics. The example described in Scenario 5 (Section 6.5) illustrates a concrete instance of this pattern.

The concrete error handling layers are:

To satisfy availability evaluation metrics, the system incorporates rigorous operational monitoring: * Metrics Ingestion: Both the Node.js API and the Rust Gamey Engine emit structured operational metrics. * Visualization: Prometheus scrapes system health, latency, and throughput metrics, which are then aggregated and visualized using Grafana dashboards.

System reliability is continuously verified through multiple layers of testing: * Multi-Layer Testing: The system utilizes unit tests for individual algorithmic checks (especially Rust logic), integration tests for API endpoints, and End-to-End (E2E) UI tests for critical user journeys. * Static Analysis: Code quality and security are strictly evaluated via SonarCloud against defined Quality Gates prior to any merge.

The development pipeline is automated natively with GitHub Actions: * CI Pipelines: Push events and pull requests trigger automated test suites and SonarCloud evaluations. * CD Pipelines: Upon a successful release merge, Docker images are automatically built from each service’s Dockerfile and orchestrated on the production server via docker-compose (see Sections 2 and 7 for the containerization details).

The architecture documentation follows a strict Docs-as-Code approach: * AsciiDoc & Arc42: All architectural documentation is written in AsciiDoc, structured entirely according to the arc42 template. This approach ensures technical documentation lives alongside the source code in version control. * PlantUML: As dictated by our conventions, all architectural diagrams and models must comply with UML standards and are rendered programmatically using PlantUML.