Loyalty Architecture & Specs
A high-performance, event-driven overlay featuring an Immutable Transaction Ledger, real-time Pub/Sub event processing, and strict duplicate-event protection.
System & Data Metrics
Ledger Immutability
Update and delete are blocked at the access-control level — points can only be adjusted with a new, auditable transaction
Event Processing
Sub-10ms rule evaluation
Idempotency
Duplicate events are guaranteed to award points exactly once
Wallet Reads
Instant balance reads via a cached balance layer, always reconcilable against the ledger
1. Immutable Ledger & Wallet Caching
Loyalty points represent a financial liability on the balance sheet. Aeion treats point transactions with the exact same rigor as monetary payments. - Append-Only Ledger: Every earned, redeemed, or expired point is a permanent transaction record. Update and delete are blocked at the access-control level — if points are awarded accidentally, an admin creates an explicit adjustment transaction to debit the balance, leaving a perfect forensic trail. - Fast, Reconcilable Balances: Summing every historical transaction on every customer login would crush performance at scale, so each wallet keeps a live cached balance for instant reads. If a race condition ever nudges it out of sync, an admin can recompute the exact balance from the immutable ledger at any time.
2. Duplicate-Safe Event Processing
Real-time systems built on an event bus can occasionally redeliver the same message. Aeion Loyalty is built to be safe against that by design. - Deterministic De-duplication: Every earning event is stamped with a unique fingerprint derived from its source. If the same event arrives twice, the second attempt is safely ignored — no double-crediting, no manual reconciliation. - Auditable Either Way: Whether an event is credited or ignored as a duplicate, the outcome is logged, so support and finance can always answer "did this customer get their points?" with certainty.
3. Cross-Module Event Architecture
The Loyalty module runs as an independent layer that listens for activity across the OS — it never reaches into or modifies another module's code. - Event-Driven Earning: When an order, stay, or other qualifying action completes elsewhere in the OS, Loyalty picks up the event, matches it against your configured earning rules, applies any tier multiplier, and deposits the points — all without the originating module knowing Loyalty exists. - Decoupled Redemption Routing: When a member redeems points for a hotel room upgrade, Loyalty deducts the points and notifies Hospitality via a dedicated event. Hospitality executes the room upgrade and confirms back, closing the loop without brittle direct dependencies between modules.
Architecture FAQ
No. Update and delete are blocked at the access-control level. If points were awarded in error, an admin writes an explicit adjustment transaction that debits the balance — the original record stays in place, preserving a complete forensic trail. Points are treated with the same rigor as monetary payments.
Every earning event carries a deterministic fingerprint derived from its source. If a duplicate arrives, the second attempt is safely ignored — points are awarded exactly once, with no double-crediting and no manual reconciliation. Both the credit and the ignored duplicate are logged so finance can always confirm the outcome.
Loyalty runs as an independent subscriber. When an order, stay, or other qualifying action completes elsewhere, Loyalty picks up the event, matches it against your configured earning rules, applies any tier multiplier, and deposits the points — the originating module never imports or calls Loyalty, and never has to know it exists.
Each wallet keeps a live cached balance for instant reads, while the append-only ledger remains the source of truth. If a race condition ever nudges the cache out of sync, an admin can recompute the exact balance from the immutable ledger at any time.
A prioritized matching strategy — email first, then phone, then account ID — recognizes inbound activity as the same human. When two distinct loyalty records turn out to represent one person, an admin merges them from the dashboard, re-linking every wallet, transaction, and tier-history entry into a single canonical identity.