Reactor Catalogue

A generic "some entity changed" signal was designed and then removed. A bulk import of 500 participants would emit 500 signals; even squashed by entity type, the table becomes noise, and the remote APIs that would consume it are better served by batched updates. Change detection for sync already exists as timestamp comparison, which is a sweep by another name. See DataSyncReactor — sweep-only.

If a future integration genuinely needs near-real-time push, add a target-specific signal type rather than resurrecting a generic one.

Handles registration and payment communications. Two decisions shape it:

Order-level, not participant-level. One email per order, addressed to the billing email. An order with seventeen participants sends one message, not seventeen to the same inbox. Order and participant emails carry genuinely different content — an order email is buyer-facing (reference, total, payment status, one pay link, a summary of who is entered), a participant email is athlete-facing (their category, race number, start group, event-day logistics). They are separate templates, not one template with a different recipient. Per-participant email is a later addition.

Direct, not via Fluxnova — for now. The framework routes single-step reactions in-process and reserves Fluxnova for multi-step orchestration. Order confirmation is single-step, and Fluxnova remains deployed but unconfigured, so the reactor calls the email service directly. Multi-step escalation — a payment reminder sequence with channel fallback — remains the Fluxnova case and will be added as a separate path rather than by rewriting this one.

Idempotency is a hard prerequisite. A reactor that sends email will be retried by the framework after a transient SMTP failure. Without a dedup guard in communication_log, that retry sends a second real email to a real customer. The guard must be in place before this reactor is enabled anywhere. See Email Service.

The bi-directional sync framework already detects change by comparing lastModifiedMain and lastModifiedRemote timestamps. That is a sweep. Adding reactive signals on top would duplicate the detection, flood the signal table during bulk imports, and turn efficient batch API calls into chatty per-entity ones.

The sweep runs every five minutes, collects everything changed since the last watermark, and submits it in one batch. See Data Synchronisation.

Closes the loop on the DETACH-and-reconcile cascade introduced by Feature #473. When an admin reassigns a race number, the system nulls number_id on the same participant’s future same-type event participants. Those sit unassigned until something reconciles them — this reactor.

It selects event participants with a null number on future events whose event type requires one, then calls the pool service per participant in its own transaction, so one failure does not block the rest. Assignment obeys ADR-0006: prefer the participant’s latest used number of that subtype, else draw from stock; if their latest is UNFIT_FOR_SERVICE, leave it unassigned and surface it as a validation error rather than auto-assigning.

Until this reactor exists, reconciliation is manual via the event-finalisation gate.

Recalculates leaderboard standings when race results change, and retries the ones whose last recalculation failed. Built under US #409.

What it replaced. LeaderboardSynchronizationService listened for a Spring ResultSetChangedEvent and debounced it in an in-memory map drained by a @Scheduled poll on every pod. A restart lost whatever was pending, and a failure was logged and forgotten. The migration was deferred until the standings were actually persisted (#1379–#1381); until then, a recalculation computed a standing and discarded it, so moving it onto the framework would have validated nothing. ResultSetChangedEvent and LeaderboardFailureNotificationService are retired; the signal is the only trigger.

Keyed per event, not per series. The catalogue originally keyed RESULT_SET_CHANGED on series:{id}. A squash keeps the first signal’s entity and replaces its payload, so under a series key the reactor cannot tell which events changed and would have to recalculate every one. That restates every published standing of the series on any change anywhere in it, and clones every approved one — the reason recalculation became per-event in #1380. Keyed on event:{id}, a bulk import still squashes to one signal, because an import covers one event.

Failure. Each leaderboard is recalculated in its own transaction. One that fails writes nothing, and the others still commit. Its published standings are left as they were; beside each one it would have rewritten, it gets an inactive FAILED draft carrying the cause, which the next attempt writes into and promotes on success (#1466). See the FAILED draft. When the leaderboard had no FAILED draft before, a configured operator is emailed once (US #1463; see the operator email). The reactor then throws, so the framework records the failure against it and retries with backoff. handleSignal and sweep both suspend the caller’s transaction: joined to the processor’s, a failed write would mark it rollback-only and lose the very record of the failure.

The sweep retries; it does not reconcile. Every ten minutes it recalculates the leaderboards that have a FAILED draft, for the organisations the reactor is scoped to. It does not find a standing that is merely stale: nothing records when a race result last changed, so a change that emitted no signal — written outside RaceResultServiceEx, or consumed while the reactor was disabled or not scoped to the organisation — is not caught. Recalculating everything instead would restate published standings. The manual recalculation endpoints cover that case.

Rollout. Enabled by default, because it replaces behaviour that was always on, but organisation-scoped like every reactor that writes tenant data. Until an environment names the organisations that run leaderboards in ems.signal-sweep.reactors.leaderboard.organisations, no standing is recalculated automatically there. A service on the dev profile has the whole framework switched off, so it recalculates nothing automatically either unless the framework is enabled for it.

Not yet handled. PERSON_MERGED and PARTICIPANT_CATEGORY_CHANGED have no emitter. A category change does move a rider into or out of a leaderboard’s linked categories, and so changes a school standing; so does changing a participant’s school. Neither raises a signal today.