yovi_es1c

Monorepo structure: All services in one repository (webapp/, users/, auth/, gamey/, gameservice/, nginx/) for easier coordination

Docker Compose: Simplified local development with single command startup

Shared YEN notation: Common understanding of game state format across all services

API-first approach: Define API contracts before implementation

Version control: Git with feature branch workflow and code reviews

Documentation: arc42 for architecture, inline code documentation, README files per service

Authentication is fully isolated in the Auth Service and its dedicated auth.db

Nginx routes all /api/auth/* requests to Auth Service (port 3001)

React Frontend stores the JWT token (localStorage or sessionStorage)

auth.db acts as the single source of truth for credentials

A failure in other databases (users.db, game.db) does not affect the login flow

JWT validation is responsibility of the Auth Service

Other services (Game Service, Users Service) delegate token verification to Auth Service via internal call

React Frontend handles unauthorized responses by redirecting to login

Nginx simply routes requests without authentication logic

Method and path: POST /api/auth/verify

Internal URL (Docker network): AUTH_INTERNAL_VERIFY_URL=http://auth:3001/api/auth/verify

Token input: preferred Authorization: Bearer <accessToken> (compatible fallback: JSON body { "token": "<accessToken>" })

Success response (200): { "valid": true, "claims": { "sub": "<userId>", "username": "<username>", "tokenType": "access", "iat": <epoch>, "exp": <epoch> } }

Error response (401): { "valid": false } for missing, malformed, invalid, expired, or non-access tokens

Security boundary: /api/auth/verify must not be exposed publicly through Nginx and should be consumed only over internal service-to-service network calls

Client resilience policy for internal callers: use short timeouts (500ms to 1s) and 0-1 retries to avoid cascading failures

The Game Service owns match lifecycle and persistence in game.db

Initial game state is always stored and returned in YEN format

React Frontend renders the game board based on received YEN notation

Match creation requires authentication (JWT token verified against Auth Service)

auth.db and users.db are not involved in this flow

React Frontend coordinates the multi-step flow from the browser

Game Server (Rust) is stateless and only computes moves based on YEN input, with no DB access

Game Service is the authoritative source of match state persistence in game.db

All updates are persisted atomically in game.db

auth.db and users.db are not involved in this flow

Bot authentication is handled exclusively by Auth Service against auth.db

Game data (match state, moves) is managed exclusively by Game Service against game.db

External bots must follow the same YEN notation format as human players

A failure in users.db does not affect bot gameplay

Statistics are computed from persisted match data in game.db

The Game Service exposes a unified Stats API

React Frontend handles visualization (charts, tables)

All stats queries require authentication (JWT verified against Auth Service)

auth.db and users.db are not involved in this flow

The matchmaking queue is stored entirely in Redis, keeping game.db free from ephemeral queue state

Both players poll independently; neither blocks the other’s request

If no opponent is found within MM_TIMEOUT_SEC, the Game Service assigns a bot as the opponent and creates the session automatically

Once a session is created in Redis, both clients proceed to connect via Socket.IO (see Scenario 8)

All real-time communication uses Socket.IO over WebSocket, proxied through Nginx

The authoritative session state is kept in Redis for low-latency reads and updates

game.db is written for every move (durable history) while Redis holds the live session snapshot

The @socket.io/redis-adapter ensures events are delivered correctly even if multiple Game Service instances are running

When the game ends, the session is removed from Redis and the final result is persisted in game.db

TurnTimerService starts a new countdown after each move (human or bot)

BotFallbackService calls the stateless Game Server (Rust) to compute the fallback move, ensuring consistency with the standard bot logic

Both clients receive a botFallback: true flag in the board update event so the UI can inform players that the move was automatic

The fallback move is persisted in game.db with an auto marker for auditability

If a player disconnects, the RECONNECT_GRACE_SEC window is given before the timeout countdown begins

Security (Defense in Depth): The infrastructure has two layers of isolation. If a container is attacked, the VM acts as an external wall that protects the physical server. Also, the Nginx API Gateway is the only part connected to the public internet.

Portability: By using Docker containers, the environment is always the same. The application works exactly the same way, no matter what physical server is running the Virtual Machine.

Independent Scalability: The system is divided into specific microservices (React Frontend, Auth Service, Users Service, Game Service, Game Server). Because of this, developers can give more resources to a specific service without affecting the others.

Fault Isolation: Each service owns its own data store. An overload or failure in game.db does not affect auth.db or users.db. Similarly, a Redis failure only affects online matchmaking and active sessions, while AI matches and authentication remain fully operational.

Consistency: It solves the classic "it works on my machine" problem.

Fast Setup: A new developer can start the complete system (React Frontend, Nginx, Auth Service, Users Service, Game Service, Game Server, Redis, Prometheus, and Grafana) with just one docker-compose up command.

User browser loads the app: Nginx serves React static files (HTML, CSS, JS)

React app runs in browser: Makes API calls to /api/auth/, /api/users/, /api/game/ and /api/gamey/

React app connects via Socket.IO for real-time online sessions through /api/game/socket.io/

Nginx routes API requests based on URL path:

Internal URL env var: AUTH_INTERNAL_VERIFY_URL=http://auth:3001/api/auth/verify

Recommended timeout in callers: 500ms to 1s

Recommended retries: 0-1 (avoid retry storms)

auth.db is mounted exclusively inside the Auth Service container. Only Auth Service has read/write permissions. Stores credentials and JWT metadata.

users.db is mounted exclusively inside the Users Service container. Only Users Service has read/write permissions. Stores user profile data.

game.db is mounted exclusively inside the Game Service container. Only Game Service has read/write permissions. Stores matches, moves, and statistics.

Redis runs as an ephemeral container (no host volume). Only the Game Service connects to it. Stores the matchmaking queue and active online session snapshots. A Redis failure only affects online matchmaking and active sessions; AI matches and authentication remain fully operational.

Backend services are protected from direct attacks

All requests go through Nginx security layers (rate limiting, CORS)

Each database is isolated behind its own service container

Services communicate only through defined internal APIs

Redis is only reachable from within the Docker network

Visual Feedback: The interface reacts immediately to user actions (valid moves, turn changes, errors). This helps players understand what is happening in the game at all times.

Consistency: We try to keep the same style and interaction patterns across all pages so the user does not have to "relearn" how to use the app.

Accessibility: Clear colors, readable text, and simple layouts help make the game accessible to a wider audience.

API Gateway Isolation: Nginx acts as the single public entry point, isolating backend services from direct external access. Only Nginx is exposed on port 80, while all backend services run on internal Docker network ports.

Authentication and Authorization: Only authenticated users can access certain features, such as creating matches or viewing their profile. The Auth Service handles JWT authentication and exposes token verification for internal service-to-service authorization checks.

Password Protection: Passwords are never stored in plain text. Instead, they are hashed and salted before being saved in the database using bcrypt or Argon2.

Data Protection: We only store the minimum amount of user information needed for the system to work. Data is split by domain with strict ownership: auth.db is accessible only through Auth Service, users.db only through Users Service, and game.db only through Game Service.

CORS and Rate Limiting: Nginx handles Cross-Origin Resource Sharing (CORS) headers and rate limiting to prevent abuse and ensure legitimate API usage.

React Frontend (webapp/): The user interface running in the browser. It is a single-page application (SPA) built with React, Vite, and TypeScript. The frontend manages UI state and coordinates API calls to backend services.

Nginx: The API Gateway and reverse proxy that routes requests to appropriate backend services. It handles CORS, rate limiting, WebSocket proxying for Socket.IO, and serves the React frontend static files.

Auth Service (auth/): Node.js + Express + TypeScript service that manages registration, authentication (JWT access/refresh lifecycle), and internal token verification. It is the single point of access to auth.db.

Users Service (users/): Node.js + Express + TypeScript service that manages user profile data. It is the single point of access to users.db.

Game Service (gameservice/): Node.js + Express + TypeScript service that manages match persistence, move history, player statistics, online matchmaking, and real-time sessions via Socket.IO. It is the single point of access to game.db and Redis.

Game Server (gamey/): Rust service that implements the Y‑game engine and bot logic. It is stateless and focuses purely on game rules, move validation, and bot strategies.

Rust Game Server: unit tests for game logic and strategies

Users Service (Node.js): API endpoint tests and integration tests

Auth Service (Node.js): unit and integration tests for authentication flows

Game Service (Node.js): unit and integration tests for match, matchmaking, and online session logic

React Frontend: component tests and end-to-end tests

auth.db — accessible only through Auth Service. Stores user credentials and JWT token metadata.

users.db — accessible only through Users Service. Stores user profile data.

game.db — accessible only through Game Service. Stores match records, move history, and player statistics.

Matchmaking queue: stores the list of players waiting for an online opponent. Entries are created when a player joins and removed when matched or when the timeout expires.

Online session snapshots: stores the current board state, active turn, and player list for each ongoing online match. This allows the Game Service to process moves and broadcast updates without hitting game.db on every turn.

Socket.IO pub/sub adapter: Redis acts as the message broker between Socket.IO server instances, ensuring events are delivered to all connected clients even if multiple Game Service replicas are running.

React Frontend: Displays user-friendly error messages for API failures, invalid moves, or authentication errors. Uses try-catch blocks and error boundaries for React component errors.

Nginx: Returns standard HTTP error codes (400, 401, 404, 500) and logs errors for monitoring.

Auth Service: Validates input, handles database errors, and returns appropriate HTTP status codes with error messages. Uses middleware for centralized error handling.

Users Service: Validates input, handles database errors, and returns appropriate HTTP status codes with error messages. Uses middleware for centralized error handling.

Game Service: Uses typed domain errors (MatchNotFoundError, UnauthorizedMatchError, InvalidMoveError) mapped to HTTP status codes by a global error handler middleware. Socket.IO errors are emitted as structured events to the affected client.

Game Server: Returns structured error responses for invalid YEN notation, illegal moves, or computation failures. Rust’s Result type ensures explicit error handling.

Context: The platform is expected to scale with increasing user demand, evolve over time with new features or game modes, and support parallel development by multiple team members. High availability and maintainability are important non-functional requirements.

Status: Accepted by the teacher and development team.

Possible alternatives:

Decision: We decided to implement a microservice-based architecture with a clear separation between game logic, data persistence, and presentation layers. The system will consist of:

Pros:

Cons:

Context: The game server must be performant, safe, and reliable, as errors in the game logic could compromise fairness or stability. Additionally, the engine may need to handle multiple concurrent games and interact efficiently with other services in the system.

Status: Accepted by the teacher and development team.

Possible alternatives:

Decision: We decided to implement the Game Server using Rust, which provides strong compile-time guarantees for memory safety and concurrency without relying on a garbage collector. This makes it well-suited for implementing complex game logic that must be both efficient and robust. The Game Server will be completely stateless, with no database access. All persistence is delegated to the Game Service.

Pros:

Cons:

Context: The platform is composed of multiple independent components implemented with different technologies and runtimes. A way to ensure consistent development, testing, and deployment across different environments is essential to reduce configuration issues and simplify setup for new team members.

Status: Accepted by the teacher and development team.

Possible alternatives:

Decision: We decided to containerize all major components of the system using Docker. Each service (React Frontend, Nginx, Auth Service, Users Service, Game Service, Game Server, Redis, Prometheus, Grafana) will run inside its own Docker container, with Docker Compose used to orchestrate and manage the multi-container setup. This ensures environment consistency and simplifies deployment and execution of the full system.

Pros:

Cons:

Context: The application requires persistent storage for game data, user information, and match states. The database solution should be simple to operate, easy to integrate with the existing backend services, and appropriate for an academic project deployed in a cloud environment.

Status: Proposed by the development team.

Possible alternatives:

Decision: We decided to use SQLite as the database system for all three data domains. Each service owns its own SQLite database file (auth.db, users.db, game.db), mounted as an independent Docker volume. No service has access to another service’s database. This choice is also highly based on the development team’s experience using relational databases.

Pros:

Cons:

Context: The system requires a secure entry point for all external requests. Backend services (Auth Service, Users Service, Game Service, and Game Server) should not be directly accessible from the internet. Additionally, cross-cutting concerns such as CORS, rate limiting, and request routing need to be handled consistently.

Status: Proposed by the development team.

Possible alternatives:

Decision: We decided to use Nginx as a reverse proxy and API Gateway. Nginx will be the only component with a publicly exposed port (80). It will route requests based on URL paths:

Pros:

Cons:

Context: The initial architecture used a single SQLite database accessed exclusively by the Users Service. As the system evolved and the number of concurrent users and game sessions grew, a concern arose: a single overloaded or failed database would bring down all data-dependent functionality simultaneously — authentication, user profiles, and game data would all fail together.

Status: Accepted by the teacher and development team.

Possible alternatives:

Decision: We decided to split the data layer into three independent services, each owning its own SQLite database:

Pros:

Cons:

Context: Adding online human-vs-human matches required two capabilities that the existing architecture could not provide efficiently: (1) a low-latency shared queue to pair players waiting for an opponent, and (2) a real-time bidirectional communication channel to propagate board state updates to both players instantly after each move. Polling a REST endpoint for both purposes would introduce unacceptable latency and unnecessary load on game.db.

Status: Proposed by the development team.

Possible alternatives:

Decision: We decided to introduce Redis as an ephemeral in-memory store and Socket.IO as the real-time communication layer, both exclusively used by the Game Service:

Pros:

Cons: