Referral Program · Documentation
Overview
What Referral Program does in the ecosystem, how it connects, and what is simulated.
← Referral ProgramWhat it does
Referral Program is the marketplace's refer-a-friend growth loop: a guest mints a referral link, and when the referred friend completes their first booking, both sides earn 500 loyalty points. It is a deliberately simple, no-AI utility — the value is in showing the coupling spine in miniature, where one guest action credits loyalty and sends notifications across two other apps.
In the operator console, OPERATE shows the program funnel (referrals, completed, conversion, points issued) and the referral ledger; CONFIGURE shows the fixed prototype rules and the anti-abuse note. The guest-facing widget lives on the marketplace account surface: "Create my referral link" mints a unique code, and "Simulate friend's first booking" completes a referral end-to-end.
How it connects
Completing a referral is the spine in action: the anti-abuse first-booking gate reads the shared booking data, the reward credits the shared loyalty engine (#12) for both the referrer and the referee, and two confirmation messages are fired through the Notifications & Comms shell (#35). On the event spine it emits referral.created, referral.completed, and loyalty.accrued, so the rest of the ecosystem sees the same outcome.
The app owns the demo_eco_referral table. The data invariant holds: seeded and owner referrals are canonical (credential_id NULL); a guest or viewer's created and completed referrals are credential-scoped, ephemeral, and reset-clearing, and can never mutate a canonical row.
What is simulated, and the honesty note
There is no AI and no metered stage in this app — every action is deterministic and $0. The two reward notifications are simulated and clearly labelled (no real email/SMS is delivered); they land in the in-app sent viewer so the connection is visible. The loyalty credit itself is real on the shared synthetic loyalty data.
Anti-abuse is enforced in the adapter, not just narrated: a referral only completes on the referee's first non-cancelled booking, and a completed referral cannot be rewarded twice. All guests, bookings, points and ledger figures are synthetic and representative; no real customer data or imagery appears anywhere.