Skip to main content

Activity service (Kaleido.Gre.Activity, :8081)

The activity service is the diary of Kaleido GRE. It stores every transaction (wager or payout) and every play session, refuses nonsense, ignores duplicates, and answers "what did this customer do on each game in this time window". It knows nothing about affinities or recommendations.

API​

MethodPathPurpose
POST/events/transactionsStore a JSON array of TransactionEvent (1 to Activity:MaxBatch, default 5,000)
POST/events/sessionsStore a JSON array of SessionEvent
GET/customers/{customerId}/activity?from&toOne customer's signals per game in [from, to)
GET/activity?after&from&to&sizeCustomers in id order, size per page (1 to 5,000, default 500), each with signals per game
GET/statsTotals, distinct customers and games, first and last event
DELETE/dataTruncate both tables (simulation reset)

Both ingest endpoints return an IngestResult:

{ "received": 4000, "accepted": 3990, "duplicates": 8, "rejected": 2,
"errors": ["[17] Amount must be above 0.", "[903] OccurredAt is in the future."] }

At most 20 error messages are returned per batch, each prefixed with the event's index.

How ingestion works​

Idempotency comes from the primary keys: EventId for transactions and SessionId for sessions. A producer can retry a whole batch after a timeout and nothing is stored twice. The insert uses Postgres unnest over column arrays, which is one round trip per batch regardless of size.

Validation rules​

EventRule
BothId not empty; CustomerId 1 to 64 characters; GameRef 1 to 128 characters
TransactionKind is Wager or Payout; Amount above 0 and at most 1,000,000,000; Currency equals Activity:Currency (EUR); OccurredAt not more than 5 minutes in the future
SessionEndedAt not before StartedAt; at most 24 hours long; EndedAt not more than 5 minutes in the future

Only one currency is accepted because adding euros and dollars would give meaningless totals.

How aggregation works​

Aggregate is one SQL statement with two CTEs, one per table, joined with a FULL JOIN so a game with sessions but no wagers (or the reverse) still appears.

Output fieldComputed from
WagerCountcount(*) of transactions with Kind = 0
WagerAmountsum of wager amounts
PayoutAmountsum of payout amounts
SessionCountcount(*) of sessions
SessionSecondssum of DurationSeconds
LastPlayedAtgreatest(max(OccurredAt), max(EndedAt))

Transactions are filtered by OccurredAt and sessions by StartedAt, both in [from, to). Either bound may be open.

The bulk /activity read first selects the next size distinct customer ids after after from the union of both tables, then aggregates only those. next is the last id when the page is full and null at the end.

Data model​

The comment in ActivityDb notes the next scaling step: partition transaction by month on OccurredAt when volume demands it.

Configuration​

KeyDefaultPurpose
Activity:CurrencyEURThe only accepted currency
Activity:MaxBatch5000Largest batch per request
Service:ApiKeyrequiredShared service key