> ## 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. # Shopping Agent Flow > The complete Shopping Agent user flow — from dispensary selection through live menu scanning, strain matching, personalized recommendations, and new strain discovery. ## Overview The Shopping Agent bridges the gap between a user's cannabis preferences and what is available at their local dispensary right now. This flow documents the complete journey from selecting a dispensary to receiving personalized product recommendations. ## End-to-End Flow ```mermaid theme={null} sequenceDiagram participant U as User participant App as High IQ participant API as Hono API participant FC as Firecrawl participant DB as Supabase participant Convex as Convex DB U->>App: Open Dispensary Detail U->>App: Tap "Shop Now" App->>API: POST /shopping-agent/scan API->>DB: Check scan cache (4hr TTL) alt Cache Hit DB-->>API: Cached results API-->>App: Instant results else Cache Miss API->>FC: Scrape dispensary menu URL FC-->>API: Raw menu data API->>API: Parse products from menu API->>DB: Batch match strains (exact → slug → trigram) DB-->>API: Matched strain profiles API->>Convex: Fetch user data (favorites, stash, orders) Convex-->>API: User personalization data API->>API: Rank and tag products API->>API: Generate AI recommendations (Claude) API->>DB: Cache results (4hr TTL) API-->>App: Full results end App->>U: Display categorized results ``` ## Pre-Scan Requirements ```mermaid theme={null} graph TD A[User Wants to Shop] --> B{Dispensary Saved?} B -->|No| C[Add Dispensary First] C --> C1[Enter Name + Address] C --> C2[Add Menu URL - Critical] B -->|Yes| D{Menu URL Set?} D -->|No| E[Add Menu URL Prompt] E --> E1[Enter Dutchie/Leafly/Weedmaps URL] D -->|Yes| F[Ready to Scan] C2 --> D E1 --> F F --> G[Tap Shop Now] ``` ## Scan Progress Flow ```mermaid theme={null} stateDiagram-v2 [*] --> CacheCheck: Start Scan CacheCheck --> InstantResults: Cache Hit (< 4hrs old) CacheCheck --> Scraping: Cache Miss Scraping --> Matching: Products Extracted Matching --> Personalizing: Strains Matched Personalizing --> Saving: Recommendations Generated Saving --> Complete: Results Cached Scraping --> Error: Scrape Failed Matching --> Error: Matching Error Error --> [*]: Show Error Message Complete --> [*]: Display Results InstantResults --> [*]: Display Results ``` **Progress stages with percentages:** | Stage | Progress | Time | What Happens | | ------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | Cache Check | 5% | `<1s` | Check Supabase for recent scan | | Scraping | 10-40% | 5-60s | Multi-tool extraction with cascading fallback: Extract (multi-page wildcard) → Scrape+JSON → Scrape+AI (Claude fallback) → Sitemap Discovery | | Matching | 40-60% | 2-5s | Products matched to 16,000+ strain DB | | Personalizing | 60-85% | 3-8s | Claude generates personalized rankings | | Saving | 85-95% | 1s | Cache results for 4 hours | | Complete | 100% | Instant | Results displayed | ## Results Screen Navigation ```mermaid theme={null} graph TD A[Results Screen] --> B[AI Recommendations Section] B --> B1[Top 3-5 Picks] B --> B2[Plain-English Explanations] B --> B3[Personalization Tags] A --> C{Category Tabs} C --> C1[Flower] C --> C2[Concentrates] C --> C3[Edibles] C --> C4[Vapes] C --> C5[Pre-Rolls] C --> C6[Other] A --> D[New Discoveries Tab] D --> D1[Unmatched Products] D --> D2[Queue for Research Button] C1 --> E[Product Cards] E --> E1[Strain Name + Match Confidence] E --> E2[Price if Available] E --> E3[Personalization Tags] E --> E4[High Family Badge] E --> F{Card Actions} F --> F1[Tap: View Strain Profile] F --> F2[Tap Tag: See Why] ``` ## Personalization Tag Logic ```mermaid theme={null} graph TD A[Product Matched to Strain] --> B{Check User Data} B --> C[Check Favorites] C --> C1{Is Favorite?} C1 -->|Yes| C2[Tag: Favorite in Stock] B --> D[Check Stash] D --> D1{In Stash + Running Low?} D1 -->|Yes| D2[Tag: Running Low] B --> E[Check Order History] E --> E1{Purchased Before?} E1 -->|Yes| E2[Tag: Bought Before] B --> F[Check Similarity] F --> F1{Similar to Favorite?} F1 -->|Yes| F2[Tag: Similar to Favorite] B --> G[Check Preferences] G --> G1{Matches Preferences?} G1 -->|Yes| G2[Tag: Matches Preferences] B --> H[Check History] H --> H1{Never Tried?} H1 -->|Yes| H2[Tag: New Discovery] B --> I[Check Price] I --> I1{On Sale?} I1 -->|Yes| I2[Tag: Great Deal] C2 --> J[Ranked Product Card] D2 --> J E2 --> J F2 --> J G2 --> J H2 --> J I2 --> J ``` ## New Strain Discovery Flow ```mermaid theme={null} graph TD A[Scan Results] --> B{Products Without DB Match} B -->|Some Found| C[New Discoveries Tab] C --> D[List Unmatched Products] D --> E[User Reviews Each] E --> F{Queue for Research?} F -->|Yes| G[Tap Add to Research Queue] G --> H[Trigger.dev Pipeline Queued] H --> I[Processing: Hours] I --> J[Full Strain Profile Available] J --> K[Next Scan Shows Match] F -->|No| L[Skip] B -->|None| M[All Products Matched] ``` ## Edge Cases | Scenario | Behavior | | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | Dispensary has no online menu | Error: "No menu URL found" with setup instructions | | Menu behind login wall | Error: "Unable to access menu" with explanation | | Menu has 200+ products | All extracted, categorized, may take 60-90s | | Zero products matched | All appear in New Discoveries tab | | User has no data (new user) | Tags limited to price-based, no personalization | | Menu URL changed | Old cache invalidated, fresh scan triggered | | Extraction fails | Cascading fallback: multi-page Extract → Scrape+JSON → Scrape+AI (Claude) → Sitemap Discovery. Error shown only if all stages fail. | | Same product listed multiple times | Deduplicated by name | | Strain name with special characters | Normalized for matching | | User closes app during scan | Scan continues, results on return | | Cache expired mid-browsing | Results still visible, refresh available | | Dispensary menu empty (holiday/closed) | "No products found" with retry option | ## Related Flows Setting up dispensaries with menu URLs. Exploring matched strains further. Adding purchased strains to stash. Wishlisted strains flagged in results.