> ## Documentation Index > Fetch the complete documentation index at: https://docs.highailabs.com/llms.txt > Use this file to discover all available pages before exploring further. # Community Badges > A new 10th badge category rewarding sharing and referral achievements, integrated with IQ Points and the existing badge progression system. **Status:** Planned **Phase:** Phase 3 | **Tier:** Free + Pro ## Overview High IQ's badge system is one of the app's stickiest features. Users currently earn badges across 9 categories -- Balanced, Curator, Dispensary Explorer, Premium Strain, Stash Manager, Streak, and others -- with 36+ badges spanning 4 rarity levels (Common, Rare, Epic, Legendary). Community Badges introduces a 10th category that rewards the social dimension of the app: sharing content and referring friends. This is not a standalone feature. It is an extension of the existing badge system, using the same infrastructure (`useBadgeProgress`, `getExtendedBadgeProgress`), the same rarity levels, the same display components, and the same "earned" notification flow. The only new elements are the badge definitions themselves and the tracking of share/referral counts as progress metrics. Community Badges serve as the visible, collectible layer of the growth system. While the Referral System (Phase 2) handles the mechanics of inviting friends and tracking conversions, and IQ Points (Phase 4) handle the economic rewards, Community Badges provide the emotional payoff -- the moment of achievement, the badge card glow, the rarity upgrade. These three systems are designed to work in concert, with each reinforcing the others. ## Current Badge System For context, here is the existing badge architecture that Community Badges integrate with: | Property | Current State | | --------------------- | ----------------------------------------------------------------------------------------------- | | **Categories** | 9 (Balanced, Curator, Dispensary Explorer, Premium Strain, Stash Manager, Streak, and 3 others) | | **Total Badges** | 36+ | | **Rarity Levels** | Common, Rare, Epic, Legendary | | **Progress Tracking** | `useBadgeProgress` hook, `getExtendedBadgeProgress` function | | **Display** | Badge grid on profile, badge detail cards, earned notifications | | **Storage** | Convex | Community Badges adds the 10th category with 8 new badges, bringing the total to 44+. ## New Community Badges **Rarity:** Common **Requirement:** Share any content 1 time **IQ Points:** 50 The gateway badge. Most users will earn this naturally after their first order sync or report generation. **Rarity:** Common **Requirement:** Share content 10 times **IQ Points:** 50 Consistent sharing behavior. 10 shares over the lifetime of the account demonstrates that the user finds the share feature genuinely useful. **Rarity:** Rare **Requirement:** 1 confirmed referral **IQ Points:** 100 The first referral badge. "Confirmed" means the referred user created an account AND uploaded at least one order. This is the same confirmation threshold used by the Referral System. **Rarity:** Rare **Requirement:** 3 confirmed referrals **IQ Points:** 100 Consistent referral behavior. 3 confirmed referrals means 3 real people who downloaded the app, created accounts, and imported orders -- all because of this user. **Rarity:** Epic **Requirement:** 5 confirmed referrals **IQ Points:** 200 This is where referral behavior transitions from casual to intentional. Users at this tier are actively evangelizing the app. **Rarity:** Epic **Requirement:** 10 confirmed referrals **IQ Points:** 200 10 real, confirmed referrals is a significant achievement. These users have meaningfully grown the High IQ community and deserve visible recognition. **Rarity:** Legendary **Requirement:** 25 confirmed referrals **IQ Points:** 500 The second-highest referral badge. At 25 confirmed referrals, this user has single-handedly created a small community of High IQ users. This badge is designed to be extremely rare. **Rarity:** Legendary **Requirement:** Among the first 100 users to make a confirmed referral **IQ Points:** 500 A **limited edition** badge. Only the first 100 users who ever confirm a referral receive this badge. Once 100 OG Referrers exist, the badge is permanently closed. This creates urgency and rewards early adopters who believe in the product before it has a large user base. ## Badge Progression Path The Community badge category has a clear progression from casual sharing to dedicated community building: ``` First Share (Common) → Social Spark (Common) → Connector (Rare) → Networker (Rare) → Influencer (Epic) → Community Builder (Epic) → Cannabis Ambassador (Legendary) ``` The OG Referrer badge sits outside the main progression as a limited-edition bonus. ### Progress Visibility Each badge shows its progress toward completion: * **First Share:** "0/1 shares" -- binary, earned on first share * **Social Spark:** "3/10 shares" -- progress bar fills as user shares * **Connector:** "0/1 confirmed referrals" -- tied to referral confirmation events * **Networker:** "1/3 confirmed referrals" -- updates in real time as referrals confirm * **OG Referrer:** "87/100 slots remaining" -- countdown creates urgency ## IQ Points Integration When a Community Badge is earned, IQ Points are awarded automatically. The points are tied to the badge rarity level, matching the rates defined in the IQ Points system: | Rarity | IQ Points Awarded | | --------- | ----------------- | | Common | 50 | | Rare | 100 | | Epic | 200 | | Legendary | 500 | If a user earns the Connector badge (Rare, 100 IQ) and simultaneously triggers the referral reward (100 IQ from the Referral System), **only the higher value is awarded** to prevent double-dipping. In this case, both are 100 IQ, so the user receives 100 IQ total, not 200. The badge's IQ Points take priority because they are the visible reward. The IQ Points integration depends on the IQ Points system (Phase 4). If Community Badges ship before IQ Points, the badges still function -- they just do not award points yet. Points can be retroactively credited when the IQ Points system launches. ## User Value Community Badges make growth-driving behavior feel like personal achievement rather than marketing -- earning the "Influencer" badge for 5 referrals feels like leveling up, not like being a salesperson. ## Technical Approach ### Integration with Existing Badge System Community Badges use the same infrastructure as all other badges: | Component | Reuse Level | Changes Needed | | -------------------------- | ----------- | ----------------------------------------------- | | `useBadgeProgress` hook | Full reuse | Add Community category to badge definitions | | `getExtendedBadgeProgress` | Full reuse | Add Community progress calculation logic | | Badge display grid | Full reuse | New category appears in grid automatically | | Badge detail card | Full reuse | Community badges use same card layout | | Earned notification | Full reuse | Same notification flow, same animation | | Badge rarity styling | Full reuse | Common/Rare/Epic/Legendary styles already exist | ### New Tracking Requirements The existing badge system tracks order counts, strain variety, dispensary visits, and streaks. Community Badges require two new metrics: | Metric | Source | Storage | | ---------------------------- | ------------------------------------------------------------------ | -------------------------------------- | | **Lifetime share count** | Incremented each time a share is completed via the iOS share sheet | Convex `user_stats.shareCount` | | **Confirmed referral count** | Incremented when a referred user uploads their first order | Convex `user_stats.confirmedReferrals` | ### OG Referrer Implementation The limited-edition OG Referrer badge requires special handling: 1. A Convex counter tracks total OG Referrer badges awarded (starts at 0, caps at 100) 2. When a user makes their first confirmed referral, check the counter 3. If counter \< 100, award the badge and increment the counter (atomic operation) 4. If counter >= 100, the badge is permanently unavailable 5. The badge progress display shows remaining slots in real time The atomic check-and-increment must be handled carefully to prevent race conditions. A Convex mutation with optimistic concurrency control ensures that exactly 100 badges are awarded, even under concurrent referral confirmations. ### Badge Definition Schema Each Community Badge follows the existing badge definition format: ```typescript theme={null} { id: "community-connector", category: "community", name: "Connector", description: "Referred 1 friend who created an account and imported their first order.", rarity: "rare", icon: "link", threshold: 1, metric: "confirmedReferrals", iqPoints: 100, } ``` ## Tier Impact | Tier | Access | | ---- | -------------------------------------------------------------------------------------------------------------------------------- | | Free | Earn all Community Badges, see progress, display on profile | | Pro | All Free benefits + badge-earned IQ Points (when IQ system launches), animated badge card effects, badge sharing via Share Cards | Badges themselves are never gated behind Pro. Every user can earn every badge. The Pro tier adds cosmetic enhancements (animations, sharing) and economic rewards (IQ Points). ## Dependencies * [x] Badge system with rarity levels and progress tracking -- **built and live** * [x] `useBadgeProgress` and `getExtendedBadgeProgress` hooks -- **built and live** * [x] Badge display grid and detail cards -- **built and live** * [ ] Share Cards (Phase 1) -- provides share count tracking * [ ] Referral System (Phase 2) -- provides confirmed referral count tracking * [ ] Share count tracking in Convex (`user_stats.shareCount`) * [ ] Referral count tracking in Convex (`user_stats.confirmedReferrals`) * [ ] Community badge definitions added to badge registry * [ ] OG Referrer counter with atomic increment logic * [ ] IQ Points integration (Phase 4) -- for point awards on badge earn (can be retroactive) ## Open Questions 1. **Badge display fix** -- The current badge display has known issues (per brainstorm notes). How much work is needed to fix the existing badge display before adding a 10th category? Should the display fix be a prerequisite or can both ship together? 2. **Category ordering** -- Where does "Community" appear in the badge grid? Last (since it is newest) or first (since it drives growth)? First position gives it visibility but may feel out of place next to consumption-based categories. 3. **OG Referrer window** -- Should the 100-slot cap be announced publicly to create urgency, or should it be a surprise for early referrers? Public announcement drives faster referral behavior but may feel manipulative. 4. **Share quality threshold** -- Should "First Share" count any share sheet open, or only completed shares? iOS does not reliably report whether a share was completed vs. dismissed. 5. **Retroactive credit** -- When Community Badges launch, should existing users who have previously shared content or referred friends (via informal channels) receive retroactive credit? This rewards early adopters but may be impossible to verify. ## Related Features * [Referral System](/planning/growth/referral-system) -- Provides the confirmed referral data that powers Connector through Ambassador badges * [IQ Points](/planning/growth/iq-points) -- Badges trigger IQ Point awards at rarity-scaled rates * [Share Cards](/planning/growth/share-cards) -- Badge-earned share cards become a Community Badge earning mechanism (circular reinforcement) * [Challenges & Leaderboards](/planning/growth/challenges-leaderboards) -- Monthly challenges may reference Community Badge progress as objectives