Yovi_es3c - Game Y at UniOvi

This project has been developed as part of the Software Architecture course (2026) at the University of Oviedo.
It is an academic project that provides basic functionality and serves as a foundation for the ASW labs.

Project Documentation

https://arquisoft.github.io/yovi_es3c/

Deployment Server

http://20.199.40.219

API Documentation

http://20.199.40.219/api-docs/

Participants

• Juan Fernández – uo296143@uniovi.es
• Juan Losada – uo302850@uniovi.es
• Pablo Pérez – uo288816@uniovi.es
• Daniel López – uo289510@uniovi.es
• Mateo Rubio – uo300069@uniovi.es

Project Structure

The project is divided into three main components, each in its own directory:

• webapp/: A frontend application built with React, Vite, and TypeScript.
• users/: A backend service for managing users, built with Node.js and Express.
• gamey/: A Rust game engine and bot service.
• docs/: Architecture documentation sources following Arc42 template

Each component has its own package.json file with the necessary scripts to run and test the application.

Core Features

• User Registration & Authentication: Create and manage user accounts with login functionality.
• Game Y: Play the Y board game with variable board sizes against AI opponents.
• Game Statistics & Ranking: Track game history, win/loss records, and view player rankings.
• Multiple Bot Strategies: Choose from different difficulty levels (Random, Heuristic, Monte Carlo, Shortest Path, Defensive).
• Move Validation & Win Detection: Real-time move validation and win condition checking powered by the Rust engine.
• Bot API: Standardized API for external bots to play matches using YEN notation.
• Web Interface: Responsive user interface built with React for playing games and viewing stats.

Components

Webapp

The webapp is a single-page application (SPA) created with Vite and React.

• src/App.tsx: The main component of the application.
• src/RegisterForm.tsx: The component that renders the user registration form.
• package.json: Contains scripts to run, build, and test the webapp.
• vite.config.ts: Configuration file for Vite.
• Dockerfile: Defines the Docker image for the webapp.

Users Service

The users service is a simple REST API built with Node.js and Express.

• users-service.js: The main file for the user service. It defines an endpoint /createuser to handle user creation.
• package.json: Contains scripts to start the service.
• Dockerfile: Defines the Docker image for the user service.

Gamey

The gamey component is a Rust-based game engine with bot support, built with Rust and Cargo.

• src/main.rs: Entry point for the application.
• src/lib.rs: Library exports for the gamey engine.
• src/bot/: Bot implementation and registry.
• src/core/: Core game logic including actions, coordinates, game state, and player management.
• src/notation/: Game notation support (YEN, YGN).
• src/web/: Web interface components.
• Cargo.toml: Project manifest with dependencies and metadata.
• Dockerfile: Defines the Docker image for the gamey service.

Running the Project

You can run this project using Docker (recommended) or locally without Docker.

With Docker

This is the easiest way to get the project running. You need to have Docker and Docker Compose installed.

1. Build and run the containers: From the root directory of the project, run:

docker-compose up --build

This command will build the Docker images for both the webapp and users services and start them.

2.Access the application:

• Web application: http://localhost
• User service API: http://localhost:3000
• Gamey API: http://localhost:4000

Without Docker

To run the project locally without Docker, you will need to run each component in a separate terminal.

Prerequisites

• Node.js and npm installed.

1. Running the User Service

Navigate to the users directory:

cd users

Install dependencies:

npm install

Run the service:

npm start

The user service will be available at http://localhost:3000.

2. Running the Web Application

Navigate to the webapp directory:

cd webapp

Install dependencies:

npm install

Run the application:

npm run dev

The web application will be available at http://localhost:5173.

3. Running the GameY Engine

Navigate to the gamey directory:

cd gamey

You can run the game engine in two modes:

Interactive mode (play in terminal):

cargo run

Server mode (API for Web App and external bots):

cargo run -- --mode server --port 4000

The Game Engine API will be available at http://localhost:4000.

Available Scripts

Each component has its own set of scripts defined in its package.json. Here are some of the most important ones:

Webapp (webapp/package.json)

• npm run dev: Starts the development server for the webapp.
• npm test: Runs the unit tests.
• npm run test:e2e: Runs the end-to-end tests.
• npm run start:all: A convenience script to start the webapp, the users and the gamey service concurrently.

Users (users/package.json)

• npm start: Starts the user service.
• npm test: Runs the tests for the service.

Gamey (gamey/Cargo.toml)

• cargo build: Builds the gamey application.
• cargo test: Runs the unit tests.
• cargo run: Runs the gamey application.
• cargo run -- --mode server --port 4000: Runs the gamey bot server at the port 4000
• cargo doc: Generates documentation for the GameY engine application

License

This project uses two licenses:

• Main repository: GNU GPL v3.0 or later.
• gamey subproject: MIT (inherited from the original upstream fork).

Full license texts:

• GPLv3: LICENSE
• MIT (gamey): gamey/LICENSE