ADR: gameyapi as Node.js REST API Service

Status

Accepted

Context

Game Y needs a backend service to manage game sessions, process player moves, handle bot interactions, and store match results. This service also exposes player profile data derived from game history.

Decision

We will implement gameyapi as a Node.js REST API using Express.

• Role in the architecture: gameyapi is the core game service. It sits between the frontend and two downstream dependencies: a Rust engine (for bot move calculation) and MongoDB (for persisting finished games and user profiles). Authentication is handled upstream by users-service; gameyapi trusts the JWT passed in each request and extracts the userId from it.
• Language: JavaScript (ES modules) running on Node.js. Chosen for its async I/O model, which suits a service that makes frequent outbound calls to the Rust engine and database.
• API style: REST. Game sessions are created, queried, and mutated via standard HTTP methods. Endpoints are documented with an OpenAPI spec served via Swagger UI at /api-docs.
• JSON: used as the data communication for both MongoDB and movements in the game.
• Session state: Active game sessions are stored in-memory (a Map). Only finished classic-mode games are persisted to MongoDB.

Alternatives

• Python / FastAPI: Strong async support and good ecosystem, but the team has more Node.js experience and sharing JWT verification logic with the rest of the stack is simpler in the same language.
• Rust (same as the engine): Would eliminate the Node.js layer entirely, but the game logic and routing code is more ergonomic to write and iterate on in JavaScript. The performance-critical bot computation is already delegated to the Rust engine.

Consequences

Positive

• Express is lightweight and well-understood by the team; routing and middleware are easy to extend.
• Delegating bot computation to the Rust engine keeps the Node.js service simple and fast.
• OpenAPI spec keeps the contract between frontend and gameyapi explicit and testable.

Negative

• In-memory session storage means active games are lost if the process restarts; this is acceptable for the current scope but will need revisiting for production resilience.
• The service has two hard runtime dependencies (Rust engine and MongoDB); if either is unavailable, parts of the API degrade.

Verification

Verification is successful when a full game flow — session creation, player moves, bot response, and match persistence — completes via the REST API, the finished game appears in MongoDB, and the /health endpoint correctly reflects the status of the Rust engine.