Affiliate Management — Claude Designs specification

This is the grounded brief for a module that does not exist yet anywhere in the Claude Designs prototype: an Affiliate, Referral & Growth Rewards program. ADR-0005 found that the only trace of this today is one hardcoded "₹200 credit each side" row inside Subscriptions' Promotions tab, and an unbuilt loyalty nav-module stub in manifest.js with no screen behind it. This page is the brief that closes that gap, per that ADR's recommendation: two audiences sharing one attribution backbone, not two separate systems and not another Promotions row.

How to use

Paste the block below into Claude Designs alongside the PDPR Design Prompt and the Screen Coverage Mandate. This brief follows the same rules: no invented fields, no placeholder data, flag ambiguity rather than assume it. It reuses the vocabulary and entity names from ADR-0005 so field names stay grounded and implementation-ready rather than generic "SaaS affiliate template" language.

This closes a real gap, not a net-new invention

manifest.js's module registry already reserves {id:'loyalty', label:'Loyalty & referrals', ..., plan:'pro'} with zero screen built. Reuse that exact nav slot for the curated partner surface (Part 2b below), but do not carry the plan:'pro' gate onto the universal growth surface (Part 2a) — a free user must be able to see and use "Invite & Earn," since that's explicitly how referrals are meant to help them upgrade.

Global rules for this module (apply everything from the PDPR too)

# AFFILIATE, REFERRAL & GROWTH REWARDS PROGRAM — DESIGN BRIEF FOR CLAUDE DESIGNS

You are designing a new, first-class QRSETU capability with TWO tiers sharing one attribution backbone, and
therefore THREE sets of screens:

1. ADMIN-FACING: a new section in the existing Admin Panel (`prototype/admin-panel/`), sibling to
   Subscriptions, RBAC, Ad Manager, Tenants. File: `Affiliates.dc.html`. Follow the exact same shared sidebar
   shell, `ds-base.js`, token usage, and tab-based layout convention already used by `Subscriptions.dc.html` and
   `RBAC.dc.html` (both already exist in this project; match their structural pattern, not just their look). It
   manages both tiers from one place.

2. GROWTH-FACING (Tier 0, universal): a new "Invite & Earn" surface available to **every** QRSETU user
   (business or individual, on **any plan including Free**) the moment they have an account. No application, no
   approval. Lives inside the existing merchant/individual console, both mobile
   (`prototype/mobile-console/`) and desktop (`ui_kits/merchant-console-v2/`).

3. PARTNER-FACING (Tier 1, curated): the existing `loyalty` module slot reserved in `manifest.js`
   (`group:'customers'`, currently gated `plan:'pro'` — **keep this gate for Part 2b only**, it is the
   application-based influencer/agency/business-partner/employee program, not the universal one).

Do not invent a third, separate authentication system or a standalone affiliate-only portal. Every participant
in both tiers is an existing QRSETU profile. Agencies and business partners are also QRSETU profiles (an
individual account type is fine for a pure marketing partner who doesn't run a business on the platform).

=====================================================================
PART 0 — VOCABULARY (use these exact terms, do not invent synonyms)
=====================================================================

- **Tier 0 (Growth)**: automatic, universal, no application. Rewards are always non-cash: a subscription-time
  credit, a feature unlock, points, or a badge. Never a cash payout, never a KYC/approval step.
- **Tier 1 (Partner)**: application-based. `affiliate_type` is one of: `individual` (peer referrer),
  `influencer`, `agency` (onboards multiple businesses, recurring commission per business), `business_partner`
  (custom negotiated terms), `employee` (internal ambassador program, typically non-cash reward, admin-only
  visibility into who's enrolled). Rewards can be cash commission, and can also include the same non-cash
  reward types Tier 0 uses.
- **Tier (performance)**: a named rank (e.g., Bronze, Silver, Gold) shared by both audiences for progress bars
  and leaderboard purposes, matching the same rank-list pattern already used for `PLAN_RANK`/`ROLE_RANK`
  elsewhere in this project.
- **Reward rule**: the generalized "what you earn" definition. `trigger_type` is `per_referral` (fires every
  qualifying referral), `milestone` (fires once at a threshold, e.g. "refer 5"), `streak` (fires on N
  consecutive qualifying periods), or `leaderboard_rank` (fires for the top N at a period's close). `reward_type`
  is `cash_commission` (Tier 1 only), `subscription_credit` (N days of a named plan), `feature_unlock` (a
  specific feature flag), `points` (adds to a wallet), or `badge` (grants an achievement). Resolution order when
  more than one rule could apply: campaign-specific, then a per-affiliate custom rule (Tier 1 only, same shape
  as Subscriptions' Custom Deals tab), then the tier default.
- **Milestone**: a named threshold inside a reward campaign, e.g. "Refer 5," "Refer 10," "Share with 20 people."
  A milestone's qualifying metric can be `signups`, `paid_conversions`, or `shares_or_clicks` — the last one
  matters because "share with X people" should not require those X people to actually sign up.
- **Referral link**: the shared attribution surface for both tiers. Three equivalent forms an owner can use
  interchangeably: a referral code (typed at signup/checkout, same UI pattern as an existing coupon code
  field), a share link (`qrsetu.com/?ref=<code>`), and a QR code generated through QRSETU's own existing QR
  generator, not a separate QR system.
- **Referral event**: one attribution record: `click`, `signup`, or `paid_conversion`. A milestone reward can
  fire on `share_or_click` alone; a commission or subscription-credit reward typically fires on `signup` and/or
  `paid_conversion`.
- **Reward grant**: the non-cash settlement record (Tier 0, and Tier-1 non-cash rewards) — auto-issued the
  instant a rule's condition is met, no manual approval, but reversible if fraud is later detected
  (`granted`\|`redeemed`\|`expired`\|`revoked`).
- **Commission ledger / payout**: unchanged, cash-only (Tier 1), `pending → approved → processing → paid`
  gated by a manual approval step above a configurable threshold.
- **Points wallet**: a simple earn/redeem balance per profile. Points are earned via a `points`-type reward and
  spent via a "redeem" action that grants a `subscription_credit` or `feature_unlock` in exchange.
- **Badge**: a named achievement (catalog + grant record), never a currency amount.
- **Leaderboard**: a read-time ranking, not stored state — computed from referral/reward history over a period.
- **Reward campaign**: a named, time-boxed or region/category/organization-scoped program with its own reward
  rule overrides, usable by either tier.

=====================================================================
PART 1 — ADMIN-FACING: Affiliates.dc.html
=====================================================================

Design as a tab-based command center, matching `Subscriptions.dc.html`'s and `RBAC.dc.html`'s established
structure in this same project (grid/list toggle, search, filters, bulk actions, a detail drawer or inspector
panel, an Approvals queue, and an exportable Audit tab — reuse these exact patterns, do not reinvent them). It
covers both tiers; make the tier distinction visible via a filter/segmented control, not two separate screens.

### Tab 1 — Overview
Program health at a glance, split by tier: Tier 0 (total enrolled — i.e., every active profile — total reward
grants issued this period, top growth campaigns by conversion) and Tier 1 (total active partners by type, cash
commission accrued vs. paid). A combined conversion funnel chart (click to signup to paid) across both tiers.
Shortcut cards into the other tabs, matching `Overview.dc.html`'s existing shortcut-card pattern.

### Tab 2 — Affiliates & participants directory
Grid/list (reuse the exact grid/list toggle already in `Subscriptions.dc.html`'s Plans tab), filterable by tier
(Growth/Partner), type, performance tier, and status. For Tier 1 rows: the full application/approval detail
drawer as originally specified (profile summary, tier override, referral link/QR, referral-event history,
commission-ledger history, suspend/reactivate with a required reason). For Tier 0, this tab is a read-mostly
view of top participants (search by name, view their reward-grant history) since there's no application to
approve — most administration for Tier 0 happens in Tabs 3-4, not here. For `agency`-type Tier 1 affiliates,
show the businesses/organizations they've onboarded and the recurring commission accruing per one.

### Tab 3 — Tiers & reward rules
A performance-tier ladder editor (reuse the exact rank-order editing pattern from RBAC's Roles library:
create/clone/inherit, explicit rank reordering) shared by both audiences. Per tier: name, rank, qualifying
threshold (minimum confirmed referrals or revenue in a rolling period — phrase as an example, flag the exact
default as an open question), and its default reward rule using the exact vocabulary from Part 0
(`trigger_type`/`reward_type`/`applies_to`). A separate "Custom overrides" list for Tier-1 per-affiliate
negotiated terms, styled identically to Subscriptions' existing Custom Deals tab.

### Tab 4 — Reward campaigns (covers both cash and growth campaigns)
List of reward campaigns: name, tier(s) it applies to, status (draft/scheduled/active/ended), scope (all users /
specific performance tier / specific affiliate type / region / business category / organization for team-wide
campaigns), date window, and its reward-rule override(s). Create/edit flow mirrors Subscriptions' existing
Promotions creation modal. Within a campaign, support attaching one or more **milestones** (e.g. "Refer 5" and
"Refer 10" as two milestones inside one campaign, each with its own reward), and optionally a **streak**
definition (N consecutive qualifying weeks/months) as a distinct trigger type from a one-time milestone. Flag
exact milestone thresholds and streak lengths as open questions rather than inventing numbers.

### Tab 5 — Payouts (Tier 1, cash only)
Unchanged from the original scope: a queue table (affiliate, amount, period, status, bulk approve/reject, a
manual per-payout detail view), a two-step approval chain (ops review, then finance sign-off, as two distinct
queue states matching RBAC's own Approval-queue pattern). Tier-0 reward grants do **not** appear here — they are
auto-settled and only need a review path for fraud reversal, which lives in Tab 6.

### Tab 6 — Fraud & review (both tiers)
A flagged-events queue covering both cash commission events and Tier-0 reward grants: suspected self-referral,
device/IP fingerprint reuse, or abnormal velocity. Each row shows the triggering signal and gives the admin a
confirm (releases/keeps the grant) or reverse (Tier 1: claws back the ledger entry; Tier 0: sets the reward
grant to `revoked` and, if it was a plan upgrade, reverts the plan) action. Design the empty state ("No flagged
activity") as a positive, not broken-looking, state. Note in the design that Tier-0 volume is expected to be
much higher than Tier-1's, so this queue needs strong filtering/sorting, not just a flat list.

### Tab 7 — Insights
Charts (reuse this project's existing `createElement`-based chart pattern from Subscriptions' Insights tab):
conversion funnel over time (split by tier), cash commission accrued vs. paid over time, Tier-0 reward grants
issued by type (subscription credit / feature unlock / points / badges), and a performance-tier distribution
breakdown across all participants.

### Tab 8 — Audit
Filterable, exportable log of every admin action on this module across both tiers, matching the exact
Audit-tab pattern already in both `Subscriptions.dc.html` and `RBAC.dc.html`.

=====================================================================
PART 2A — GROWTH-FACING (Tier 0): "Invite & Earn" — universal, every plan
=====================================================================

This is a new, always-visible surface inside the existing console (mobile and desktop), reachable from every
plan including Free — do not gate it behind any plan check. It is the free-to-paid upgrade lever, so hiding it
from Free users defeats its purpose.

### Always-on entry point
A persistent, low-friction entry point — a card on the dashboard Home (matching the existing stat-card/action-
card visual pattern already on `Home.dc.html`) and/or a nav item, titled something like "Invite & Earn." Do not
require the user to hunt for this in a settings submenu.

### Invite & Earn dashboard
- **Referral link & QR code card**: the user's own code, shareable link, and a QR code they can download or
  share directly, generated through the existing QR generator/share pattern already used elsewhere in this
  console (do not design a second, separate QR flow).
- **Active campaigns list**: the current "Refer X, Get Y" offers available to them right now (e.g., "Share with
  5 people, unlock 1 month of Pro," "Refer 10 businesses, get an extended Pro subscription"), each shown as a
  card with a clear progress indicator (a progress bar or a "3 of 5" counter) toward that specific milestone.
  If more than one campaign is active, show all of them, each with its own independent progress.
- **Streak indicator**, if a streak-type reward is active: a simple visual (e.g. a week-by-week strip showing
  which recent periods qualified) so the user understands what keeps a streak alive.
- **Performance tier status**: current tier (shared with Tier 1's tier ladder), progress toward the next tier,
  and what the next tier unlocks — same progress-bar treatment as the milestone cards above.
- **Points wallet** (only if points are in scope for this phase — flag as open if not): current balance, a
  history list (earned/redeemed), and a "Redeem" action showing what the current balance can be exchanged for
  (e.g., "500 points = 1 week of Pro").
- **Badges showcase**: earned badges as a simple grid/row of icons with names, an empty state ("No badges yet,
  here's how to earn your first one") that is encouraging, not broken-looking.
- **Leaderboard** (only if enabled for this phase — the ADR flags public-vs-private as an open product question;
  design both an opt-in-public state and a private/hidden state, and a toggle for the user to choose which,
  rather than assuming one).
- **Reward history**: a simple list of past grants (date, what was earned, status: granted/redeemed/expired/
  revoked) — a revoked entry needs a plain-language explanation, never a silent disappearance.

## Design note
Every element above should feel celebratory and low-friction, consistent with this project's "instant and
forgiving" design principle — this surface exists specifically to be shared and enjoyed, not administered.

=====================================================================
PART 2B — PARTNER-FACING (Tier 1): curated affiliate/partner dashboard
=====================================================================

Reuses the `loyalty` nav slot already reserved in `manifest.js`, kept at its existing `plan:'pro'` gate (this
is the curated program, unlike Part 2A).

### Enrollment / opt-in state
For a profile not yet enrolled: an explanation of the program (what they earn, how attribution works) and an
"Apply" or "Join" action. After applying, a `pending` state (waiting on admin approval, per Part 1 Tab 2) with a
clear "we'll notify you" message, not a silent dead end.

### Enrolled dashboard
Everything from Part 2A's dashboard (referral link/QR, active campaigns, tier status, badges, leaderboard,
reward history) **plus**, since this is the cash-commission tier: a commission-ledger history (date, referred
user or business, event type, amount, status) and payout history with a "Request payout" action when one is
due, or a clear explanation of when the next one is expected if not.

### States to design for all three surfaces (admin, growth, partner)
Empty (no participants yet / no referrals yet / no rewards earned yet), loading (skeletons matching this
project's existing skeleton patterns), success, error (safe, generic messages, no internal detail), permission
(a non-admin trying to reach the admin tabs; a suspended Tier-1 affiliate trying to reach their dashboard), and
edge cases (zero activity yet, a payout stuck in `processing`, a revoked reward grant appearing in history with
a clear explanation rather than a silent negative number, a milestone campaign that ended before the user
finished it).

=====================================================================
PART 3 — WHAT NOT TO INVENT (flag these as open questions instead)
=====================================================================

1. The exact tier qualifying thresholds, milestone thresholds (how many referrals for each named milestone),
   streak lengths, and reward values/percentages — use realistic QRSETU examples (INR values and round numbers
   matching this project's existing rupee-denominated examples elsewhere) and mark them clearly as examples.
2. The exact payout threshold and cadence (Tier 1 cash only).
3. Whether a multi-level (recruitment-tree) affiliate structure exists. It does not exist in this brief's scope
   for either tier. Design only flat performance tiers and the resolution order in Part 0.
4. The specific payment rail/provider for Tier-1 payouts. Design the payout status states and approval flow; do
   not name or design a specific third-party payout provider's branded UI.
5. Whether "successful referral" for a feature-unlock milestone means a signup or a paid conversion — design
   the progress-bar UI generically enough to work either way, and flag the distinction as unresolved.
6. Whether a "Powered by QRSETU" QR-native viral loop (a small tracked mark on free-tier public QR surfaces) is
   in scope at all. Do **not** design this without being told to — it's a brand/trust decision, not a screen to
   assume.
7. Whether leaderboards and badges are public (visible to other users) or private-only. Design the toggle
   mentioned in Part 2A rather than picking one.
8. Whether points, streaks, or leaderboards are in scope for this phase at all, versus milestones/badges only.
   If a section above seems out of scope, flag it rather than building a placeholder for it.

Everything else in this brief is grounded, not speculative: build it as specified, and flag anything genuinely
missing rather than filling it with a generic affiliate-program template.

Why this shape, not a bigger or smaller one

This brief deliberately mirrors structures Claude Designs has already built well in this same project (Subscriptions' tab layout and Custom Deals pattern, RBAC's tier/rank editor and Approvals queue, the existing QR generation flow, the existing dashboard stat-card and progress patterns) rather than asking for a novel UI language. Splitting Tier 0 (universal, celebratory, zero-friction) from Tier 1 (curated, application-gated, cash-handling) as two visually distinct experiences sharing one backend model keeps both the design and the real implementation coherent: one attribution system, two settlement paths, three screens.

After this ships in Claude Designs

Once Affiliates.dc.html and both console-facing modules exist, review them the same way every other admin screen has been reviewed in this program: read the actual file, check it against this brief and against ADR-0005's entity model, fraud rules, and the specific "what not to invent" list above, log findings under a new design-system/screen-reviews/admin-panel/affiliates.md page following the same design-fixable vs. architecture-gated split used throughout this section, and update SCREENS.md and manifest.js's loyalty module gate accordingly (confirm the Tier-0 surface actually shipped ungated, since that's the one correction this revision makes to existing code, not just new code).