0017 — Affiliates: admin-issued referral codes, synced to PANGALI¶
Status: accepted (2026-09-30). Builds on 0012 (referral attribution). Not a return of the program 0010 removed.
Context¶
ADR 0012 gave every user a lazily generated share code (8 characters, no
0/O/1/I) and attributes a signup to whoever's code it used. The store now
wants named partners: an admin picks an existing user and gives them a
memorable code (e.g. GOLDKING) plus a Play Store link that carries it, so
anyone who installs through that link has the code filled in on the register
page. PANGALI must know these affiliates the same way it knows customers,
because it forwards customers to BROXI with the referral code they signed up
with — and BROXI refuses a code it doesn't know (400 REFERRAL_CODE_UNKNOWN),
which PANGALI treats as final. A referred customer can only reach BROXI once
the affiliate code has.
ADR 0010's closing rule applies: anything affiliate-shaped starts as a new design, not from the removed code. Nothing of the old program — applications, KYC, commission ledgers, payouts — comes back.
Decision¶
- Attribution only. An affiliate code is one more way to fill
users.referred_by+referral_attributionsat signup. No commission, earnings or wallet row exists anywhere in this feature, in AIM Store, PANGALI or BROXI. A reward would need its own ADR (0011, 0012). - Schema — tracked migration
094_affiliates.sql: oneaffiliatesrow per user, ever (UNIQUE user_id). The code is 6–8 capital letters (A–Z;INFINITY, BROXI's house code, is refused), immutable, and never reissued: a revoked or erased affiliate keeps its code as a tombstone, because a code that changed hands would attribute installs still in flight to the wrong person. The Play Store link is built once at creation fromPLAY_STORE_URL(…&referrer=utm_source=aimstore_affiliate&utm_medium=affiliate_link&referral_code=<CODE>) and stored. - One namespace for typed codes. Signup looks a code up among active
affiliate codes and users' share codes (
referralCodeOwnerSQL). Triggers on both tables check the other under a per-code advisory lock, so the two sets stay disjoint. The shared wire format widens to^(?:[A-HJ-NP-Z2-9]{6,10}|[A-Z]{6,8})$in the backend and the app — affiliate codes may use I and O.GET /referrals/my-codereturns an active affiliate's affiliate code, so the app's Invite Friends share carries it. - Admin surface —
GET/POST /api/v1/admin/affiliates,GET /api/v1/admin/affiliates/:id,PUT /api/v1/admin/affiliates/:id/status(active ↔ revoked), AdminOnly, audited. The portal's Affiliates page lists them with their PANGALI sync state; the Users list gains a "Make affiliate" action. - PANGALI sync is state-based. Every change bumps
affiliates.version; the worker (ProcessPendingAffiliates, first in each 5-minute cycle) sends the current state withPUT /v1/aim-store/affiliates/by-user-id/{user_id}(name, email, code, link, status, version — never a phone number) whenever PANGALI has not confirmed that version. PANGALI ignores versions older than it holds, so a resend can never undo a newer state. 400/409 are final for that version; everything else retries. Gated onPANGALI_AFFILIATE_SYNC_ENABLED(default false). - Ordering. While the flag is on, a customer registration carrying an affiliate code waits until that affiliate is confirmed by PANGALI (unless PANGALI rejected it, or it was erased unsent). PANGALI in turn holds the identity until BROXI has the affiliate. So each system always learns the affiliate before the customers it referred.
- Erasure. Deleting or anonymising the user erases the affiliate (a
trigger, so every deletion path is covered) and, if it may have reached
PANGALI, queues a by-user-id deletion on the existing outbox (source
affiliate_erased); PANGALI's customer deletion routes erase the affiliate too.
Consequences¶
- An affiliate needs a name and an email on their account; the portal refuses one without, and the worker holds (and retries) one whose email was later cleared rather than send a request PANGALI would reject for good.
- Affiliate-code installs attribute only on app builds that accept
A–Zcodes; an installed build older than this change drops codes containing I or O from the install referrer. Every new install gets the current Play build, so this closes once the new build is on the production track. - Signups attributed before an affiliate is revoked stay attributed.
Affiliates who referred anyone hit the existing
users.referred_byFK on a hard delete (409, as for any referrer) and are anonymised instead — which the trigger also handles. - Rolling back means
rollback_094.sql, which drops every affiliate and code; PANGALI keeps what it was sent. See that file before running it.