# Event Subscription Design Specification - `gameEvents`

This document provides a detailed architectural overview of the `gameEvents` event subscription within the `leaderboard` service. It covers the subscription's transport configuration, topic definitions, authorization model, and payload transformations.

## Subscription Overview

**Description:** Subscribes to gameplay events so the leaderboard can update ELO ratings, player stats, and rankings when games are completed.

- **Transport:** `websocket`
  Clients connect via Socket.IO at namespace `/events/gameEvents` for long-lived bidirectional subscriptions. Ideal for dashboards, live tickers, and collaborative interfaces.

- **Namespace:** `/events/gameEvents`


## Topics

This subscription exposes 1 Kafka topic to connected clients:


### `gameCompleted`

Fires when a chess game is updated (status changes to completed/terminated). Used to trigger ELO recalculation and leaderboard rank updates for both players.

- **Kafka Topic:** `wechess-gameplay-service-game-updated`
- **DataObject:** `playerStats`
- **Access Level:** Inherited from DataObject configuration




#### Excluded Fields
The following fields are stripped from the payload before sending to clients:
`invitationCode`





## Authorization


The subscription uses a layered authorization model that controls which users can connect and which topics they receive:


### Absolute Roles
Users with roles `administrator` bypass all authorization checks and receive all topics without filtering.







### Event Filter Script
Evaluated for each incoming Kafka event before delivery. Returns false to skip the event for the user:

```js
data.result != null && (data.status == 'completed' || data.status == 'terminated')
```
Context variables: `session`, `topicName`, `dataObjectName`, `data`





## Client Integration


### WebSocket Connection (Socket.IO)

```javascript
import { io } from 'socket.io-client';

const socket = io('/events/gameEvents', {
  auth: { token: 'your-jwt-token' }
});

// Subscribe to specific topics
socket.on('gameCompleted', (data) => {
  console.log('gameCompleted event:', data);
});


socket.on('connect', () => console.log('Connected to gameEvents'));
socket.on('disconnect', () => console.log('Disconnected from gameEvents'));
```


---

*This document was generated from the event subscription configuration and should be kept in sync with design changes.*