Referral Link
Data Entity
Description
A personalized, trackable invite link owned by a peer mentor or coordinator used to recruit new members to the Meander platform. Each link carries a unique signed token that allows the backend to attribute registrations and conversion events back to the originating user. Links have a configurable expiry and can be shared as URLs or as QR codes. The entity is the root of the referral attribution graph — all referral_trackings records hang off it.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Surrogate primary key. Generated server-side (UUID v4) at link creation time. | PKrequiredunique |
user_id |
uuid |
Foreign key to users table. Identifies the peer mentor or coordinator who owns this referral link. Immutable after creation. | required |
organization_id |
uuid |
Foreign key to organizations table. Denormalized from the owning user for efficient org-scoped recruitment dashboard queries without joining through users. | required |
token |
string |
Cryptographically random, URL-safe token embedded in the referral URL. Used as the lookup key when a new user arrives via the link. Generated using CSPRNG (crypto.randomBytes(24) encoded as base64url). Immutable after creation. | requiredunique |
url |
string |
Full canonical deep-link URL including token, e.g. https://meander.app/join?ref=<token>. Stored pre-built to avoid reconstruction on every read. Treated as immutable — regenerating the link creates a new record. | requiredunique |
is_active |
boolean |
Soft-deactivation flag. Set to false when the link is explicitly revoked by the user or the backend, or when a replacement link is issued. Inactive links reject attribution even if not yet expired. | required |
expires_at |
datetime |
UTC timestamp after which the referral link is no longer valid for attribution. NULL indicates a link with no expiry (legacy or admin-issued links). When set, evaluated server-side on every inbound referral attribution attempt. | - |
click_count |
integer |
Denormalized running total of all inbound clicks on this link. Atomically incremented each time the referral token is resolved (including unauthenticated visits). Used for quick dashboard display without aggregating referral_trackings. Not a substitute for full tracking records. | required |
created_at |
datetime |
UTC timestamp when the referral link record was created. Set once at insert, never mutated. | required |
updated_at |
datetime |
UTC timestamp of the last mutation to this record (e.g. is_active toggled, click_count incremented). Maintained by an ON UPDATE trigger or application layer. | required |
Database Indexes
idx_referral_link_token
Columns: token
idx_referral_link_user_id
Columns: user_id
idx_referral_link_organization_id
Columns: organization_id
idx_referral_link_user_active
Columns: user_id, is_active
idx_referral_link_org_active
Columns: organization_id, is_active
idx_referral_link_expires_at
Columns: expires_at
Validation Rules
token_format
error
Validation failed
url_format
error
Validation failed
expires_at_future
error
Validation failed
user_id_exists
error
Validation failed
organization_id_matches_user
error
Validation failed
token_uniqueness
error
Validation failed
Business Rules
single_active_link_per_user
A user may have at most one active referral link at any time. When a new link is generated, the backend deactivates all prior active links for that user before inserting the new record. This prevents parallel attribution splits that would corrupt recruiter performance metrics.
only_peer_mentor_or_coordinator_can_generate
Only users with the Peer Mentor or Coordinator role may request a referral link. Org Admin and Global Admin roles are excluded — their purpose is administrative, not recruiting. Enforced at the REST endpoint by permission-validation-middleware.
expired_link_no_attribution
When an inbound referral token is resolved and expires_at is set and in the past, the attribution is rejected with a 410 Gone response. No referral_trackings record is created. The mobile deep-link handler presents a 'link expired' message and routes the user to the standard onboarding flow.
inactive_link_no_attribution
When is_active is false, the link rejects all inbound attribution attempts regardless of expiry. This allows immediate revocation (e.g. user account deactivation, policy violation) without waiting for natural expiry.
tenant_isolation
All read operations on referral_links must be scoped to the authenticated user's organization_id. The recruitment dashboard for coordinators must only surface links and tracking events belonging to the same organization. Global admins have no default access to org referral data.
click_count_atomic_increment
click_count must be incremented using an atomic SQL UPDATE (click_count = click_count + 1) to prevent lost updates under concurrent link resolutions. Application-level read-modify-write is prohibited for this field.
deactivate_on_user_offboarding
When a user account is deactivated or deleted, all referral_links owned by that user must be deactivated (is_active = false) in the same transaction. This prevents orphaned active links from accumulating referral_trackings after the referrer leaves the platform.