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
| Method | Path | Purpose |
|---|---|---|
| POST | /events/transactions | Store a JSON array of TransactionEvent (1 to Activity:MaxBatch, default 5,000) |
| POST | /events/sessions | Store a JSON array of SessionEvent |
| GET | /customers/{customerId}/activity?from&to | One customer's signals per game in [from, to) |
| GET | /activity?after&from&to&size | Customers in id order, size per page (1 to 5,000, default 500), each with signals per game |
| GET | /stats | Totals, distinct customers and games, first and last event |
| DELETE | /data | Truncate 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
| Event | Rule |
|---|---|
| Both | Id not empty; CustomerId 1 to 64 characters; GameRef 1 to 128 characters |
| Transaction | Kind 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 |
| Session | EndedAt 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 field | Computed from |
|---|---|
WagerCount | count(*) of transactions with Kind = 0 |
WagerAmount | sum of wager amounts |
PayoutAmount | sum of payout amounts |
SessionCount | count(*) of sessions |
SessionSeconds | sum of DurationSeconds |
LastPlayedAt | greatest(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
| Key | Default | Purpose |
|---|---|---|
Activity:Currency | EUR | The only accepted currency |
Activity:MaxBatch | 5000 | Largest batch per request |
Service:ApiKey | required | Shared service key |