Service Design Specification

wechess-gameplay-service documentation Version: 1.0.74

Scope

This document provides a structured architectural overview of the gameplay microservice, detailing its configuration, data model, authorization logic, business rules, and API design. It has been automatically generated based on the service definition within Mindbricks, ensuring that the information reflects the source of truth used during code generation and deployment.

The document is intended to serve multiple audiences:

Service architects can use it to validate design decisions and ensure alignment with broader architectural goals.
Developers and maintainers will find it useful for understanding the structure and behavior of the service, facilitating easier debugging, feature extension, and integration with other systems.
Stakeholders and reviewers can use it to gain a clear understanding of the service’s capabilities and domain logic.

Note for Frontend Developers: While this document is valuable for understanding business logic and data interactions, please refer to the Service API Documentation for endpoint-level specifications and integration details.

Note for Backend Developers: Since the code for this service is automatically generated by Mindbricks, you typically won’t need to implement or modify it manually. However, this document is especially valuable when you’re building other services—whether within Mindbricks or externally—that need to interact with or depend on this service. It provides a clear reference to the service’s data contracts, business rules, and API structure, helping ensure compatibility and correct integration.

`Gameplay` Service Settings

Service for managing real-time chess games, matchmaking, move history, and private invitations, including lifecycle management (mutual game-save/resume, admin termination), supporting both guest and registered users. Enables API access for reviewing games, enforcing moderation actions, and tracking game results.

Service Overview

This service is configured to listen for HTTP requests on port 3000, serving both the main API interface and default administrative endpoints.

The following routes are available by default:

API Test Interface (API Face): /
Swagger Documentation: /swagger
Postman Collection Download: /getPostmanCollection
Health Checks: /health and /admin/health
Current Session Info: /currentuser
Favicon: /favicon.ico

The service uses a PostgreSQL database for data storage, with the database name set to wechess-gameplay-service.

This service is accessible via the following environment-specific URLs:

Preview: https://wechess.prw.mindbricks.com/gameplay-api
Staging: https://wechess-stage.mindbricks.co/gameplay-api
Production: https://wechess.mindbricks.co/gameplay-api

Authentication & Security

Login Required: Yes

This service requires user authentication for access. It supports both JWT and RSA-based authentication mechanisms, ensuring secure user sessions and data integrity. If a crud route also is configured to require login, it will check a valid JWT token in the request query/header/bearer/cookie. If the token is valid, it will extract the user information from the token and make the fetched session data available in the request context.

Service Data Objects

The service uses a PostgreSQL database for data storage, with the database name set to wechess-gameplay-service.

Data deletion is managed using a soft delete strategy. Instead of removing records from the database, they are flagged as inactive by setting the isActive field to false.

Object Name	Description	Public Access
`chessGame`	No description	accessPrivate
`chessGameMove`	Represents a single move in a chess game (FIDE-compliant SAN/LAN representation, timestamp, player, time, move number).	accessPrivate
`chessGameInvitation`	An invitation for a private chess game between two players; status tracked; expires at set time or when accepted/declined.	accessPrivate
`customBoard`	No description	accessPrivate
`boardTheme`	No description	accessPrivate
`userPreference`	No description	accessPrivate
`gameHubMessage`	Auto-generated message DataObject for the gameHub RealtimeHub. Stores all messages with typed content payloads.	accessPrivate
`gameHubModeration`	Auto-generated moderation DataObject for the gameHub RealtimeHub. Stores block and silence actions for room-level user moderation.	accessPrivate

chessGame Data Object

Object Overview

Description: No description provided.

This object represents a core data structure within the service and acts as the blueprint for database interaction, API generation, and business logic enforcement. It is defined using the ObjectSettings pattern, which governs its behavior, access control, caching strategy, and integration points with other systems such as Stripe and Redis.

Core Configuration

Soft Delete: Enabled — Determines whether records are marked inactive (isActive = false) instead of being physically deleted.
Public Access: accessPrivate — If enabled, anonymous users may access this object’s data depending on API-level rules.

Properties Schema

Property	Type	Required	Description
`playerWhiteId`	ID	Yes	User ID of the player assigned White (guest or registered); references auth:user.id.
`playerBlackId`	ID	No	-
`createdById`	ID	Yes	ID of the user who created the game (can be a guest or registered user).
`status`	Enum	Yes	Lifecycle status: pending, active, paused, completed, terminated
`mode`	Enum	Yes	Game mode: public (matchmaking), private (invitation-based)
`invitationCode`	String	No	-
`currentFEN`	String	Yes	Current board state in FEN notation for restoration/resume.
`gameType`	Enum	Yes	Game type: timed, untimed, blitz, rapid
`saveStatus`	Enum	Yes	Game mutual-saving: notSaveable, requested, paused (both agreed)
`saveRequestWhite`	Boolean	No	Whether white has requested save/resume; mutual save when both true.
`saveRequestBlack`	Boolean	No	Whether black has requested save/resume; mutual save when both true.
`movedAt`	Date	No	Timestamp of last move (heartbeat/game activity).
`result`	Enum	No	Game result/outcome: whiteWin, blackWin, draw, aborted
`terminatedById`	ID	No	ID of administrator who forced terminated the game (if applicable).
`reportStatus`	Enum	No	Moderation/review status: none, reported, underReview
`guestPlayerWhite`	Boolean	No	True if white is a guest (not a registered user); needed to distinguish guest/registered in history.
`guestPlayerBlack`	Boolean	No	True if black is a guest (not a registered user); needed to distinguish guest/registered in history.
`initialFEN`	String	No	The starting FEN position when the game was created. Used to identify custom games.

Required properties are mandatory for creating objects and must be provided in the request body if no default value is set.

Default Values

Default values are automatically assigned to properties when a new object is created, if no value is provided in the request body. Since default values are applied on db level, they should be literal values, not expressions.If you want to use expressions, you can use transposed parameters in any business API to set default values dynamically.

playerWhiteId: ‘00000000-0000-0000-0000-000000000000’
createdById: ‘00000000-0000-0000-0000-000000000000’
status: pending
mode: public
currentFEN: startpos
gameType: untimed
saveStatus: notSaveable
reportStatus: none

Constant Properties

playerWhiteId createdById mode invitationCode gameType initialFEN

Constant properties are defined to be immutable after creation, meaning they cannot be updated or changed once set. They are typically used for properties that should remain constant throughout the object’s lifecycle. A property is set to be constant if the Allow Update option is set to false.

Auto Update Properties

playerWhiteId playerBlackId createdById status mode invitationCode currentFEN gameType saveStatus saveRequestWhite saveRequestBlack movedAt result terminatedById reportStatus guestPlayerWhite guestPlayerBlack initialFEN

An update crud API created with the option Auto Params enabled will automatically update these properties with the provided values in the request body. If you want to update any property in your own business logic not by user input, you can set the Allow Auto Update option to false. These properties will be added to the update API’s body parameters and can be updated by the user if any value is provided in the request body.

Enum Properties

Enum properties are defined with a set of allowed values, ensuring that only valid options can be assigned to them. The enum options value will be stored as strings in the database, but when a data object is created an addtional property with the same name plus an idx suffix will be created, which will hold the index of the selected enum option. You can use the index property to sort by the enum value or when your enum options represent a sequence of values.

status: [pending, active, paused, completed, terminated]
mode: [public, private]
gameType: [timed, untimed, blitz, rapid]
saveStatus: [notSaveable, requested, paused]
result: [whiteWin, blackWin, draw, aborted]
reportStatus: [none, reported, underReview]

Elastic Search Indexing

Properties that are indexed in Elastic Search will be searchable via the Elastic Search API. While all properties are stored in the elastic search index of the data object, only those marked for Elastic Search indexing will be available for search queries.

Database Indexing

playerWhiteId playerBlackId createdById status mode invitationCode movedAt result

Properties that are indexed in the database will be optimized for query performance, allowing for faster data retrieval. Make a property indexed in the database if you want to use it frequently in query filters or sorting.

Secondary Key Properties

mode invitationCode

Secondary key properties are used to create an additional indexed identifiers for the data object, allowing for alternative access patterns. Different than normal indexed properties, secondary keys will act as primary keys and Mindbricks will provide automatic secondary key db utility functions to access the data object by the secondary key.

Relation Properties

playerWhiteId playerBlackId createdById terminatedById

Mindbricks supports relations between data objects, allowing you to define how objects are linked together. You can define relations in the data object properties, which will be used to create foreign key constraints in the database. For complex joins operations, Mindbricks supportsa BFF pattern, where you can view dynamic and static views based on Elastic Search Indexes. Use db level relations for simple one-to-one or one-to-many relationships, and use BFF views for complex joins that require multiple data objects to be joined together.

playerWhiteId: ID Relation to user.id

The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object.

On Delete: Set Null Required: No

playerBlackId: ID Relation to user.id

The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object.

On Delete: Set Null Required: No

createdById: ID Relation to user.id

The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object.

On Delete: Set Null Required: No

terminatedById: ID Relation to user.id

The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object.

On Delete: Set Null Required: No

Filter Properties

status invitationCode

Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API’s that have “Auto Params” enabled.

status: Enum has a filter named status
invitationCode: String has a filter named invitationCode

chessGameMove Data Object

Object Overview

Description: Represents a single move in a chess game (FIDE-compliant SAN/LAN representation, timestamp, player, time, move number).

Core Configuration

Soft Delete: Enabled — Determines whether records are marked inactive (isActive = false) instead of being physically deleted.
Public Access: accessPrivate — If enabled, anonymous users may access this object’s data depending on API-level rules.

Composite Indexes

moveByGameAndNumber: [gameId, moveNumber] This composite index is defined to optimize query performance for complex queries involving multiple fields.

The index also defines a conflict resolution strategy for duplicate key violations.

When a new record would violate this composite index, the following action will be taken:

On Duplicate: throwError

An error will be thrown, preventing the insertion of conflicting data.

Properties Schema

Display Label Property: moveNotation — This property is the default display label for records of this data object. Relation dropdowns and record references in the frontend will show the value of this property as the human-readable label.

Property	Type	Required	Description
`gameId`	ID	Yes	Reference to the chessGame this move belongs to.
`moveNumber`	Integer	Yes	Move number (starting from 1 in each game).
`moveNotation`	String	Yes	Chess move in either Standard Algebraic or Long Algebraic Notation (SAN/LAN).
`moveTime`	Integer	No	Time in milliseconds since the previous move (for time control, etc.).
`movedById`	ID	Yes	User ID of the player who made the move (guest/registered); references auth:user.id.
`moveTimestamp`	Date	Yes	Timestamp when move was made.

Required properties are mandatory for creating objects and must be provided in the request body if no default value is set.

Default Values

gameId: ‘00000000-0000-0000-0000-000000000000’
moveNumber: 0
moveNotation: ‘default’
movedById: ‘00000000-0000-0000-0000-000000000000’
moveTimestamp: new Date()

Constant Properties

gameId moveNumber moveNotation moveTime movedById moveTimestamp

Auto Update Properties

gameId moveNumber moveNotation moveTime movedById moveTimestamp

Elastic Search Indexing

gameId moveNumber moveNotation movedById moveTimestamp

Database Indexing

gameId moveNumber moveTimestamp

Secondary Key Properties

gameId moveNumber

Relation Properties

gameId movedById

gameId: ID Relation to chessGame.id

The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object.

On Delete: Set Null Required: Yes

movedById: ID Relation to user.id

The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object.

On Delete: Set Null Required: No

Filter Properties

gameId

gameId: ID has a filter named gameId

chessGameInvitation Data Object

Object Overview

Description: An invitation for a private chess game between two players; status tracked; expires at set time or when accepted/declined.

Core Configuration

Soft Delete: Enabled — Determines whether records are marked inactive (isActive = false) instead of being physically deleted.
Public Access: accessPrivate — If enabled, anonymous users may access this object’s data depending on API-level rules.

Composite Indexes

invitationUniqueForGameAndRecipient: [gameId, recipientId] This composite index is defined to optimize query performance for complex queries involving multiple fields.

The index also defines a conflict resolution strategy for duplicate key violations.

When a new record would violate this composite index, the following action will be taken:

On Duplicate: throwError

An error will be thrown, preventing the insertion of conflicting data.

Properties Schema

Property	Type	Required	Description
`gameId`	ID	Yes	Game this invitation is linked to.
`senderId`	ID	Yes	-
`recipientId`	ID	Yes	-
`status`	Enum	Yes	-
`expiresAt`	Date	Yes	Expiration date/time for the invitation.

Required properties are mandatory for creating objects and must be provided in the request body if no default value is set.

Default Values

gameId: ‘00000000-0000-0000-0000-000000000000’
senderId: ‘00000000-0000-0000-0000-000000000000’
recipientId: ‘00000000-0000-0000-0000-000000000000’
status: “pending”
expiresAt: new Date()

Constant Properties

gameId

Auto Update Properties

gameId senderId recipientId status expiresAt

Enum Properties

status: [pending, accepted, declined, cancelled]

Elastic Search Indexing

gameId senderId recipientId status expiresAt

Database Indexing

gameId senderId recipientId expiresAt

Secondary Key Properties

gameId

Relation Properties

gameId senderId recipientId

gameId: ID Relation to chessGame.id

The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object.

On Delete: Set Null Required: Yes

senderId: ID Relation to user.id

The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object.

On Delete: Set Null Required: No

recipientId: ID Relation to user.id

The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object.

On Delete: Set Null Required: No

Filter Properties

senderId recipientId status

senderId: ID has a filter named senderId
recipientId: ID has a filter named recipientId
status: Enum has a filter named status

customBoard Data Object

Object Overview

Description: No description provided.

Core Configuration

Soft Delete: Enabled — Determines whether records are marked inactive (isActive = false) instead of being physically deleted.
Public Access: accessPrivate — If enabled, anonymous users may access this object’s data depending on API-level rules.

Properties Schema

Display Label Property: name — This property is the default display label for records of this data object. Relation dropdowns and record references in the frontend will show the value of this property as the human-readable label.

Property	Type	Required	Description
`name`	String	Yes	Name of the custom board position
`fen`	String	Yes	FEN string representing the board position
`description`	Text	No	Optional description of the custom board
`isPublished`	Boolean	Yes	-
`category`	Enum	Yes	-
`createdById`	ID	Yes	-

Required properties are mandatory for creating objects and must be provided in the request body if no default value is set.

Default Values

name: ‘default’
fen: ‘default’
isPublished: false
category: “endgame”
createdById: ‘00000000-0000-0000-0000-000000000000’

Auto Update Properties

name fen description isPublished category createdById

Enum Properties

category: [endgame, opening, puzzle, custom]

Elastic Search Indexing

name fen description isPublished category createdById

Database Indexing

name isPublished category createdById

Relation Properties

createdById

createdById: ID Relation to user.id

The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object.

On Delete: Set Null Required: No

Filter Properties

isPublished category createdById

isPublished: Boolean has a filter named isPublished
category: Enum has a filter named category
createdById: ID has a filter named createdById

boardTheme Data Object

Object Overview

Description: No description provided.

Core Configuration

Soft Delete: Enabled — Determines whether records are marked inactive (isActive = false) instead of being physically deleted.
Public Access: accessPrivate — If enabled, anonymous users may access this object’s data depending on API-level rules.

Properties Schema

Property	Type	Required	Description
`name`	String	Yes	Theme display name
`lightSquare`	String	Yes	Hex color for light squares
`darkSquare`	String	Yes	Hex color for dark squares
`isPublished`	Boolean	No	Whether the theme is publicly visible
`createdById`	ID	Yes	User who created this theme

Required properties are mandatory for creating objects and must be provided in the request body if no default value is set.

Default Values

name: ‘default’
lightSquare: ‘default’
darkSquare: ‘default’
createdById: ‘00000000-0000-0000-0000-000000000000’

Always Create with Default Values

Some of the default values are set to be always used when creating a new object, even if the property value is provided in the request body. It ensures that the property is always initialized with a default value when the object is created.

isPublished: Will be created with value false

Constant Properties

createdById

Auto Update Properties

name lightSquare darkSquare isPublished createdById

Elastic Search Indexing

name lightSquare darkSquare isPublished createdById

Database Indexing

name isPublished createdById

Relation Properties

createdById

createdById: ID Relation to user.id

The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object.

On Delete: Set Null Required: No

Filter Properties

isPublished

isPublished: Boolean has a filter named isPublished

userPreference Data Object

Object Overview

Description: No description provided.

Core Configuration

Soft Delete: Enabled — Determines whether records are marked inactive (isActive = false) instead of being physically deleted.
Public Access: accessPrivate — If enabled, anonymous users may access this object’s data depending on API-level rules.

Properties Schema

Property	Type	Required	Description
`userId`	ID	Yes	The user this preferences record belongs to
`activeThemeId`	String	No	ID of the currently selected board theme (preset ID or custom theme ID)
`soundEnabled`	Boolean	No	Whether game sounds are enabled
`showAnimations`	Boolean	No	Whether board animations are shown
`boardOrientation`	Enum	No	Default board orientation preference
`premoveEnabled`	Boolean	No	Whether premove feature is enabled

Required properties are mandatory for creating objects and must be provided in the request body if no default value is set.

Default Values

userId: ‘00000000-0000-0000-0000-000000000000’
activeThemeId: classic
soundEnabled: true
showAnimations: true
boardOrientation: auto
premoveEnabled: true

Constant Properties

userId

Auto Update Properties

userId activeThemeId soundEnabled showAnimations boardOrientation premoveEnabled

Enum Properties

boardOrientation: [auto, white, black]

Elastic Search Indexing

userId activeThemeId soundEnabled showAnimations boardOrientation premoveEnabled

Database Indexing

userId

Unique Properties

userId

Unique properties are enforced to have distinct values across all instances of the data object, preventing duplicate entries. Note that a unique property is automatically indexed in the database so you will not need to set the Indexed in DB option.

Relation Properties

userId

userId: ID Relation to user.id

The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object.

On Delete: Set Null Required: No

gameHubMessage Data Object

Object Overview

Description: Auto-generated message DataObject for the gameHub RealtimeHub. Stores all messages with typed content payloads.

Core Configuration

Soft Delete: Enabled — Determines whether records are marked inactive (isActive = false) instead of being physically deleted.
Public Access: accessPrivate — If enabled, anonymous users may access this object’s data depending on API-level rules.

Properties Schema

Property	Type	Required	Description
`roomId`	ID	Yes	Reference to the room this message belongs to
`senderId`	ID	No	Reference to the user who sent this message
`senderName`	String	No	Display name of the sender (denormalized from user profile at send time)
`senderAvatar`	String	No	Avatar URL of the sender (denormalized from user profile at send time)
`messageType`	Enum	Yes	Content type discriminator for this message
`content`	Object	Yes	Type-specific content payload (structure depends on messageType)
`timestamp`		No	Message creation time
`status`	Enum	No	Message moderation status

Required properties are mandatory for creating objects and must be provided in the request body if no default value is set.

Default Values

roomId: ‘00000000-0000-0000-0000-000000000000’
messageType: “text”
content: {}
timestamp: now()
status: approved

Constant Properties

roomId senderId senderName senderAvatar messageType timestamp

Auto Update Properties

roomId senderId senderName senderAvatar messageType content timestamp status

Enum Properties

messageType: [text, system, chessMove, drawOffer, drawAccepted, drawDeclined, resignation, saveRequest, saveAccepted, saveDeclined, resumeRequest, resumeAccepted, resumeDeclined]
status: [pending, approved, rejected]

Elastic Search Indexing

roomId senderId senderName senderAvatar messageType content timestamp status

Database Indexing

roomId senderId senderName senderAvatar messageType content timestamp status

Secondary Key Properties

roomId

Session Data Properties

senderId

Session data properties are used to store data that is specific to the user session, allowing for personalized experiences and temporary data storage. If a property is configured as session data, it will be automatically mapped to the related field in the user session during CRUD operations. Note that session data properties can not be mutated by the user, but only by the system.

senderId: ID property will be mapped to the session parameter userId.

Filter Properties

roomId senderId senderName senderAvatar messageType content timestamp status

roomId: ID has a filter named roomId
senderId: ID has a filter named senderId
senderName: String has a filter named senderName
senderAvatar: String has a filter named senderAvatar
messageType: Enum has a filter named messageType
content: Object has a filter named content
timestamp: has a filter named timestamp
status: Enum has a filter named status

gameHubModeration Data Object

Object Overview

Description: Auto-generated moderation DataObject for the gameHub RealtimeHub. Stores block and silence actions for room-level user moderation.

Core Configuration

Soft Delete: Disabled — Determines whether records are marked inactive (isActive = false) instead of being physically deleted.
Public Access: accessPrivate — If enabled, anonymous users may access this object’s data depending on API-level rules.

Properties Schema

Property	Type	Required	Description
`roomId`	ID	Yes	Reference to the room where the moderation action applies
`userId`	ID	Yes	The user who is blocked or silenced
`action`	Enum	Yes	Moderation action type
`reason`	Text	No	Optional reason for the moderation action
`duration`	Integer	No	Duration in seconds. 0 means permanent
`expiresAt`		No	Expiry timestamp. Null means permanent
`issuedBy`	ID	No	The moderator who issued the action

Required properties are mandatory for creating objects and must be provided in the request body if no default value is set.

Default Values

roomId: ‘00000000-0000-0000-0000-000000000000’
userId: ‘00000000-0000-0000-0000-000000000000’
action: “blocked”
duration: 0

Constant Properties

roomId userId action duration expiresAt issuedBy

Auto Update Properties

roomId userId action reason duration expiresAt issuedBy

Enum Properties

action: [blocked, silenced]

Elastic Search Indexing

roomId userId action reason duration expiresAt issuedBy

Database Indexing

roomId userId action reason duration expiresAt issuedBy

Secondary Key Properties

roomId userId

Relation Properties

roomId

roomId: ID Relation to chessGame.id

The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object.

On Delete: Set Null Required: Yes

Session Data Properties

issuedBy

issuedBy: ID property will be mapped to the session parameter userId.

Filter Properties

roomId userId action reason duration expiresAt issuedBy

roomId: ID has a filter named roomId
userId: ID has a filter named userId
action: Enum has a filter named action
reason: Text has a filter named reason
duration: Integer has a filter named duration
expiresAt: has a filter named expiresAt
issuedBy: ID has a filter named issuedBy

Business Logic

gameplay has got 28 Business APIs to manage its internal and crud logic. For the details of each business API refer to its chapter.

Realtime Hubs

gameplay has 1 Realtime Hub configured. Each hub provides bidirectional communication powered by Socket.IO with room-based messaging, built-in and custom message types, and auto-generated REST endpoints.

Hub Name	Namespace	Room DataObject	Roles
`gameHub`	`/hub/gameHub`	`chessGame`	player

For detailed documentation on each hub, refer to:

gameHub

Service Library

Functions

processGameResult.js

const { interserviceCall } = require("serviceCommon");

/**
 * Mindbricks interservice calls return the same envelope as REST (e.g. { playerStats: {...} }).
 * Unwrap so we read id, eloRating, wins, etc. from the actual row.
 */
function unwrapPlayerStats(res) {
  if (res == null || typeof res !== "object") return null;
  const inner = res.playerStats;
  if (inner && typeof inner === "object" && inner.id) return inner;
  if (res.id && res.userId) return res;
  return null;
}

/**
 * Processes a completed/terminated chess game result:
 * - Computes ELO changes for both players
 * - Calls leaderboard service to update playerStats for registered (non-guest) players
 * - Calls leaderboard service to update leaderboardEntry eloRating and rank
 *
 * @param {object} context - The API context (this)
 */
module.exports = async function processGameResult(context) {
  const game = context.chessGame;
  const updatedFields = context;

  const status = updatedFields.status || game.status;
  const result = updatedFields.result || game.result;

  if (!["completed", "terminated"].includes(status) || !result) {
    return null;
  }

  if (result === "aborted") {
    return null;
  }

  const playerWhiteId = game.playerWhiteId;
  const playerBlackId = game.playerBlackId;
  const isWhiteGuest = game.guestPlayerWhite === true;
  const isBlackGuest = game.guestPlayerBlack === true;

  let whiteOutcome;
  let blackOutcome;
  if (result === "whiteWin") {
    whiteOutcome = "win";
    blackOutcome = "loss";
  } else if (result === "blackWin") {
    whiteOutcome = "loss";
    blackOutcome = "win";
  } else if (result === "draw") {
    whiteOutcome = "draw";
    blackOutcome = "draw";
  } else {
    return null;
  }

  let whiteStats = null;
  let blackStats = null;

  if (!isWhiteGuest && playerWhiteId) {
    try {
      const raw = await interserviceCall("leaderboard", "getPlayerStats", { userId: playerWhiteId });
      whiteStats = unwrapPlayerStats(raw);
    } catch (e) {
      /* player may not have stats yet */
    }
  }
  if (!isBlackGuest && playerBlackId) {
    try {
      const raw = await interserviceCall("leaderboard", "getPlayerStats", { userId: playerBlackId });
      blackStats = unwrapPlayerStats(raw);
    } catch (e) {
      /* player may not have stats yet */
    }
  }

  const whiteElo = whiteStats ? (Number(whiteStats.eloRating) || 1200) : 1200;
  const blackElo = blackStats ? (Number(blackStats.eloRating) || 1200) : 1200;

  const K = 32;
  const expectedWhite = 1 / (1 + Math.pow(10, (blackElo - whiteElo) / 400));
  const expectedBlack = 1 / (1 + Math.pow(10, (whiteElo - blackElo) / 400));

  let actualWhite;
  let actualBlack;
  if (result === "whiteWin") {
    actualWhite = 1;
    actualBlack = 0;
  } else if (result === "blackWin") {
    actualWhite = 0;
    actualBlack = 1;
  } else {
    actualWhite = 0.5;
    actualBlack = 0.5;
  }

  const newWhiteElo = Math.round(whiteElo + K * (actualWhite - expectedWhite));
  const newBlackElo = Math.round(blackElo + K * (actualBlack - expectedBlack));

  const now = new Date().toISOString();

  function buildUpdatePayload(stats, outcome, newElo) {
    const wins = (stats ? stats.wins : 0) + (outcome === "win" ? 1 : 0);
    const losses = (stats ? stats.losses : 0) + (outcome === "loss" ? 1 : 0);
    const draws = (stats ? stats.draws : 0) + (outcome === "draw" ? 1 : 0);
    const totalGames = wins + losses + draws;
    let streak = stats ? stats.streak : 0;
    if (outcome === "win") streak = streak > 0 ? streak + 1 : 1;
    else if (outcome === "loss") streak = streak < 0 ? streak - 1 : -1;
    else streak = 0;
    return { eloRating: newElo, totalGames, wins, losses, draws, streak, lastGameAt: now };
  }

  if (!isWhiteGuest && playerWhiteId && whiteStats) {
    try {
      const payload = buildUpdatePayload(whiteStats, whiteOutcome, newWhiteElo);
      await interserviceCall("leaderboard", "updatePlayerStats", { id: whiteStats.id, ...payload });
    } catch (e) {
      console.error("Failed to update white player stats:", e.message);
    }
  }

  if (!isBlackGuest && playerBlackId && blackStats) {
    try {
      const payload = buildUpdatePayload(blackStats, blackOutcome, newBlackElo);
      await interserviceCall("leaderboard", "updatePlayerStats", { id: blackStats.id, ...payload });
    } catch (e) {
      console.error("Failed to update black player stats:", e.message);
    }
  }

  return { whiteElo: newWhiteElo, blackElo: newBlackElo, result };
};

This document was generated from the service architecture definition and should be kept in sync with implementation changes.

Service Design Specification

Scope

Gameplay Service Settings

Service Overview

Authentication & Security

Service Data Objects

chessGame Data Object

Object Overview

Core Configuration

Properties Schema

Default Values

Constant Properties

Auto Update Properties

Enum Properties

Elastic Search Indexing

Database Indexing

Secondary Key Properties

Relation Properties

Filter Properties

chessGameMove Data Object

Object Overview

Core Configuration

Composite Indexes

Properties Schema

Default Values

Constant Properties

Auto Update Properties

Elastic Search Indexing

Database Indexing

Secondary Key Properties

Relation Properties

Filter Properties

chessGameInvitation Data Object

Object Overview

Core Configuration

Composite Indexes

Properties Schema

Default Values

Constant Properties

Auto Update Properties

Enum Properties

Elastic Search Indexing

Database Indexing

Secondary Key Properties

Relation Properties

Filter Properties

customBoard Data Object

Object Overview

Core Configuration

Properties Schema

Default Values

Auto Update Properties

Enum Properties

Elastic Search Indexing

Database Indexing

Relation Properties

Filter Properties

boardTheme Data Object

Object Overview

Core Configuration

Properties Schema

Default Values

Always Create with Default Values

Constant Properties

Auto Update Properties

Elastic Search Indexing

Database Indexing

Relation Properties

Filter Properties

userPreference Data Object

Object Overview

Core Configuration

Properties Schema

Default Values

Constant Properties

Auto Update Properties

Enum Properties

Elastic Search Indexing

Database Indexing

Unique Properties

`Gameplay` Service Settings