> ## 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. # Achievement System Flow > The complete achievement system flow — earning, progress tracking, celebrations, identity titles, level progression, and the gamification loop. ## Overview The achievement system is High IQ's gamification engine — driving engagement through 40 achievements across 10 tracks, a level system capping at Level 25, and a dynamic Cannabis Identity title. This flow documents how achievements are earned, how celebrations trigger, and how the system creates retention loops. ## Achievement Earning Flow ```mermaid theme={null} sequenceDiagram participant U as User participant App as High IQ participant DB as Convex U->>App: Perform action (add order, favorite, etc.) App->>DB: Save action DB->>DB: Achievement progress check DB-->>App: Progress update alt Achievement Threshold Met App->>App: Calculate XP earned App->>App: Check level progression App->>App: Update identity title if needed App->>DB: Save achievement + level App->>U: Show celebration else Progress Made (< threshold) App->>App: Update progress bar opt Near Threshold (80%+) App->>U: Show contextual nudge end end ``` ## Achievement Track Progression ```mermaid theme={null} graph TD A[Achievement Track] --> B[Tier 1: Common] B --> C[Tier 2: Rare] C --> D[Tier 3: Epic] D --> E[Tier 4: Legendary] B --> B1[Entry Level] B --> B2[Most users earn in first weeks] B --> B3[Low XP reward] C --> C1[Moderate effort] C --> C2[Weeks to months] C --> C3[Medium XP reward] D --> D1[Significant dedication] D --> D2[Months of active use] D --> D3[High XP reward] E --> E1[Mastery level] E --> E2[Exceptional commitment] E --> E3[Maximum XP reward] ``` ## Cross-Feature Achievement Triggers ```mermaid theme={null} graph TD A{User Action} --> B[Add to Stash] A --> C[Upload Order] A --> D[Favorite a Strain] A --> E[Visit Dispensary] A --> F[View Daily Story] A --> G[Generate Notebook] A --> H[Log Activity] B --> I[Stash Manager Track] B --> J[Core Collection Track] C --> K[Order Milestones Track] C --> L[Spending Milestones Track] C --> M[Dispensary Explorer Track] C --> J D --> N[Collection Curator Track] E --> M F --> O[Daily Stories Track] G --> P[Notebook Mastery Track] H --> Q[Activity Streaks Track] B --> R[Strain Variety Track] C --> R style I fill:#e5e7eb style J fill:#e5e7eb style K fill:#e5e7eb style L fill:#e5e7eb style M fill:#e5e7eb style N fill:#e5e7eb style O fill:#e5e7eb style P fill:#e5e7eb style Q fill:#e5e7eb style R fill:#e5e7eb ``` ## Celebration System ```mermaid theme={null} graph TD A[Achievement Earned] --> B{How Many at Once?} B -->|1 Achievement| C[Toast Notification] C --> C1[Slides in from top] C --> C2[Achievement name + rarity] C --> C3[Haptic tap] C --> C4[Auto-dismiss after 3s] B -->|2-3 Achievements| D[Swipeable Modal] D --> D1[Card per achievement] D --> D2[Confetti effects] D --> D3[Swipe to see each] D --> D4[User dismisses] B -->|4+ Achievements| E[Batch Summary Screen] E --> E1[Grid of all unlocked] E --> E2[Total XP counter] E --> E3[Common with Gmail imports] E --> E4[User taps Done] ``` **When batch unlocks happen:** | Trigger | Typical Unlocks | | ------------------------------- | ------------------------------------------------------------------------------ | | Large Gmail import (50+ orders) | Order Milestones, Spending, Core Collection, Dispensary Explorer — 4-8 at once | | First dispensary receipt | Order Milestones T1, potentially Stash Manager T1 | | Daily Story streak milestone | Daily Stories track + Activity Streaks | ## Level Progression System ```mermaid theme={null} graph LR A[Level 1-5] --> B[Level 6-12] B --> C[Level 13-20] C --> D[Level 21-25] A --> A1[Newcomer] A --> A2[Basic milestones] B --> B1[Intermediate] B --> B2[Multiple tracks engaged] C --> C1[Advanced] C --> C2[Rare/Epic achievements] D --> D1[Expert] D --> D2[Legendary achievements] ``` ## Identity Title Flow ```mermaid theme={null} graph TD A[Achievement XP Earned] --> B[Calculate XP Per Track] B --> C{Which Track Has Most XP?} C -->|Core Collection| D[The Connoisseur] C -->|Spending| E[The Investor] C -->|Orders| F[The Regular] C -->|Dispensary| G[The Navigator] C -->|Strain Variety| H[The Explorer] C -->|Activity Streaks| I[The Dedicated] C -->|Collection Curator| J[The Curator] C -->|Stash Manager| K[The Organizer] C -->|Notebook Mastery| L[The Scholar] C -->|Daily Stories| M[The Storyteller] D --> N[Title Displayed on Profile] E --> N F --> N G --> N H --> N I --> N J --> N K --> N L --> N M --> N N --> O[Auto-updates when dominant track changes] ``` ## Active Quests Flow ```mermaid theme={null} graph TD A[User Opens Profile] --> B[Active Quests Section] B --> C[Scan All Achievements] C --> D{Progress >= 80%?} D -->|Yes| E[Display as Active Quest] E --> E1[Achievement Name + Track] E --> E2[Current / Required count] E --> E3[Progress Bar] E --> E4[Rarity Tier Badge] D -->|No| F[Not shown as Quest] E --> G[User Taps Quest] G --> H[Navigate to Achievement Detail] H --> I[Full Track View] I --> J[See All Tiers + Progress] ``` ## Featured Achievements Flow ```mermaid theme={null} graph TD A[User Opens Profile] --> B[Featured Achievements Section] B --> C{Has Featured?} C -->|Yes| D[Display Pinned Achievements] C -->|No| E[Empty Slots with Prompt] D --> F[Tap Edit] E --> F F --> G[Browse Earned Achievements] G --> H[Tap to Pin - Max 5] H --> I[Drag to Reorder] I --> J[Save Featured Set] J --> K[Displayed on Profile] ``` ## Progress Nudge System ```mermaid theme={null} graph TD A[User Completes Action] --> B{Relevant Achievement Near?} B -->|Progress >= 80%| C[Contextual Nudge] C --> C1[Brief banner at screen bottom] C --> C2[Shows remaining count] C --> C3[Example: Just 1 more favorite!] B -->|Progress < 80%| D[No Nudge] A --> E[Home Dashboard Check] E --> F{Any Achievement >= 80%?} F -->|Yes| G[Achievement Nudge Card] G --> G1[Shows nearest goal] G --> G2[Progress bar] G --> G3[Tap to view details] F -->|No| H[Card Hidden] ``` ## Gamification Retention Loop ```mermaid theme={null} graph TD A[User Action] --> B[Progress Update] B --> C{Achievement Earned?} C -->|Yes| D[Celebration] D --> E[XP + Level Up] E --> F[New Active Quests Appear] F --> G[User Sees Next Goals] G --> A C -->|No| H{Near Achievement?} H -->|Yes| I[Nudge Shown] I --> G H -->|No| J[Silent Progress] J --> K[Quest Card Updates] K --> G ``` ## Edge Cases | Scenario | Behavior | | ---------------------------------------- | ------------------------------------------------------- | | Earn achievement while offline | Achievement saved locally, celebration on next app open | | Delete data that drops below threshold | Achievement NOT revoked — once earned, always earned | | Earn multiple Legendary achievements | Each still celebrated individually over time | | Identity title tie (two tracks equal XP) | First earned track wins the tie | | All 40 achievements earned | "100% Complete" banner, Level 25 max | | Streak broken (Activity/Daily Stories) | Counter resets, achievement tiers preserved | | Gmail import earns 10+ achievements | Batch summary screen handles gracefully | | No achievements near 80% | Active Quests section shows encouraging message | ## Related Flows Achievements as a progression mechanism. Achievement progress driving retention. Orders triggering multiple achievement tracks. Notebook Mastery achievement track.