- Overview
- Team Members
- Features
- Architecture
- Tech Stack
- Setup & Deployment
- Testing & Quality Assurance
- Monitoring & Observability
- Performance Testing
- Live Deployment
YOVI is a strategy board game application developed as a capstone project for the Software Architecture course (2025/2026) at the University of Oviedo. Players compete against AI bots of different difficulty levels on a hexagonal board, following the rules of the Game Y.
The system is built as a microservices architecture, with a Rust game engine for board logic and bot AI, Node.js/Express backend services, a React frontend, and MongoDB for persistence. The application supports multiple game modes, match history, player statistics, and a global ranking.
The full requirements specification can be found here.
| Contributor | GitHub | Contact |
|---|---|---|
| Daniel Onís Fabián |  |
UO293946@uniovi.es |
| Sergio Seijo Martínez |  |
UO300084@uniovi.es |
| Martín Almoina Iglesias |  |
UO300717@uniovi.es |
| Gonzalo García Castro |  |
UO294665@uniovi.es |
| Daniel Álvarez Menéndez |  |
UO299778@uniovi.es |
- Multiple Game Modes: Standard, Master, Fortune, Tabu, Holey and WhyNot — each with different board rules and mechanics.
- Difficulty Levels: Three bot difficulties — random, beginner and medium — powered by the Rust game engine.
- Board Sizes: Choose from 4 different board sizes to adjust the game length and complexity.
- User Management: Registration and login with bcrypt password hashing and JWT-based authentication.
- Player Statistics: Track wins, losses, win rate and games played per user.
- Global Ranking: Leaderboard sorted by wins or win rate, showing the top 20 players.
- Match History: Full history of past games per user, including result, bot, board size and game type.
- API Documentation: Interactive Swagger/OpenAPI docs available at
/api-docsvia the gateway.
YOVI uses a microservices architecture where all client traffic passes through a single API Gateway.
webapp/: React + TypeScript frontend. Communicates exclusively with the gateway.gatewayservice/: Single entry point for the system. Routes requests to the appropriate service, handles JWT authentication and CORS.users/: Manages user accounts, authentication, statistics, ranking and match history. Exposes Prometheus metrics at/metrics.gamemanager/: Controls match lifecycle — creating games, applying moves, checking win conditions, and delegating bot moves to the game engine. Exposes Prometheus metrics at/metrics.gamey/: Rust game engine. Implements board logic, win detection and bot AI for all game modes and difficulty levels.docs/: Architecture documentation following the Arc42 template.
| Layer | Technology |
|---|---|
| Frontend | React, TypeScript, Vite |
| Backend | Node.js, Express |
| Game Engine | Rust |
| Database | MongoDB (Mongoose ODM) |
| Authentication | JWT (jsonwebtoken), bcrypt |
| API Gateway | Express + Axios |
| Monitoring | Prometheus (express-prom-bundle), Grafana |
| API Docs | Swagger UI (swagger-ui-express) |
| Testing | Vitest, Supertest, Nock, Playwright (E2E) |
| Performance | Gatling |
| CI/CD | GitHub Actions |
| Containerization | Docker, Docker Compose |
- Git
- Node.js (LTS) and npm
- Rust (stable toolchain)
- Docker and Docker Compose
Create a .env file in the root directory with the following variables:
MONGO_USER=your_mongo_user
MONGO_PASS=your_mongo_password
JWT_SECRET=your_jwt_secretdocker compose up --buildOnce running, the application is available at:
- Webapp: http://localhost:8080
- Swagger Docs: http://localhost:8000/api-docs
- Prometheus: http://localhost:9090
- Grafana: http://localhost:9091
To stop:
docker compose down- Start a MongoDB instance locally or via Docker:
docker run -d -p 27017:27017 mongo:6- Build the Rust game engine:
cd gamey && cargo build- Start each Node.js service (users, gamemanager, gatewayservice):
cd <service> && npm install && npm start- Start the frontend:
cd webapp && npm install && npm run dev- Continuous Integration: GitHub Actions runs all tests automatically on every push and pull request.
- Unit & Integration Tests: Each service has its own test suite using Vitest and Supertest. HTTP calls to external services are intercepted with Nock to isolate tests.
- End-to-End Tests: Playwright simulates real user interactions against the full application stack.
- Rust Tests: The game engine is tested with Cargo's built-in test framework and llvm-cov for coverage.
- Code Quality: SonarCloud analyzes every build for code smells, bugs, security vulnerabilities and coverage.
- Prometheus: Scrapes metrics from the
usersandgame-managerservices every 5 seconds. Metrics include HTTP request duration, rate and error count. - Grafana: Dashboards available at
/grafana/(production) orhttp://localhost:9091(local) showing RED metrics (Rate, Errors, Duration) per service. - API Documentation: Swagger UI available at
/api-docsvia the gateway.
Load tests are implemented with Gatling and cover the main user flows: registration, login, bot API simulation, and ranking/stats queries. Results are stored in docs/load-testing/.
To run the load tests:
cd gatling && ./bin/gatling.shThe application is deployed at: https://yovi-en3a.duckdns.org
- Grafana dashboard: https://yovi-en3a.duckdns.org/grafana/
- API docs: https://yovi-en3a.duckdns.org/api-docs/
- Architecture docs: https://arquisoft.github.io/yovi_en3a/
- Wiki: https://github.com/Arquisoft/yovi_en3a/wiki