Beacon overview

Beacon materializes trusted player state from explicit Kafka event contracts. It stores current operational state for fast downstream decisions; Kafka remains the event history.

The first projector tracks casino presence:

online-services-front -> Heimdall edge -> Heimdall Kafka route -> Beacon -> Mongo
                                                |                |
                         player.casino-presence.v1                +-> per-input DLQ

Current contract

Concern	Value
Input topic	heimdall.player-casino-presence.v1
Event type	player.casino-presence.v1
Trusted source value	online-services-front
Consumer group	beacon.player-state.v1
DLQ topic	beacon.player-casino-presence.dlq.v1
Mongo namespace	beacon.presence_state
Document identity	tenant_id + player_id
Per-site identity	site_id inside the document's sites array

Heimdall resolves tenant, site, and player identity before publishing and uses a stable hash of those values as the Kafka partition key. The source field is a validation rule, not producer authentication; Kafka listener access and ACLs must enforce the real producer boundary.

Projection behavior

• opened and heartbeat make one site online and refresh its expiry.
• heartbeat may create missing state, so a lost opened event heals on the next heartbeat.
• closed applies only to the active presence session.
• A player is online when at least one site is online.
• Event ID, Kafka position, trusted receive time, and session guards turn known replays or stale records into successful no-ops.
• Mongo version comparison preserves concurrent updates to different sites and resolves heartbeat-versus-expiry races without lost updates.

Beacon stores one current document per tenant and player. It does not store raw analytics history and currently exposes no player-state read API.

Extension boundary

Future state types belong in explicit code-owned routes. Each route names its input topic, event type, per-input DLQ, decoder, projector, and collection. Keep the same beacon database unless the new workload needs independent credentials or lifecycle. Use another collection when identity, query shape, or retention differs; use another service or consumer group only when replay, scaling, credentials, release cadence, or failure isolation must be independent.

Do not subscribe Beacon to a catch-all analytics topic.

Read next

• Beacon operations covers event and state contracts, idempotency, DLQ replay, configuration, metrics, security, and deployment.
• The service README contains the local smoke and load commands.