GearBox/docs/superpowers/specs/2026-04-05-catalog-driven-gear-flow-design.md

Catalog-Driven Gear Flow

Date: 2026-04-05 Status: Draft Scope: Conceptual vision — how users discover, add, research, and contribute gear through the global catalog.

---

Product Focus

GearBox is focused on bikepacking, cycling, adventure, and outdoor gear. The global catalog, tags, and all curated content target this vertical. Other gear types (sim racing, etc.) may be supported later via multi-collection, but are out of scope for this design.

---

The Three Pillars

1. Collection Management — Track what you own, see weight/cost totals, organize into setups
2. Research & Purchase — Find new gear, compare options in threads, make informed decisions
3. Community & Sharing — Public profiles, shared setups, reviews, discussions (future: feed)

The global catalog is the connective tissue between all three. It's the shared source of truth for "what gear exists in the outdoor/adventure world."

---

Global Catalog

What It Is

A curated, community-contributed database of outdoor/adventure gear. Think of it as a gear encyclopedia — every item has specs, images, ratings, review links, and community data.

Data Model

Each catalog item has:

• Brand & Model — the identity (e.g., "Revelate Designs Pika")
• Specs — weight, price (MSRP), dimensions where relevant
• Image — product photo
• Description — short summary of what it is
• Tags — flexible, combinable labels (see Tag System below)
• Rating — aggregated from user reviews (future)
• Review Links — links to trusted publications (bikepacking.com, etc.)
• Owner Count — how many GearBox users have this in their collection
• Submission Status — approved, pending_review, rejected

Tag System

Tags replace rigid category hierarchies. They're flat, combinable, and natural-language friendly.

Tag types:

• Gear type: handlebar-bag, framebag, tent, stove, headlamp, wheel
• Activity: bikepacking, touring, hiking, camping, ultralight
• Property: waterproof, ultralight, budget, premium, durable
• Mounting/fit: handlebar-mount, fork-mount, seatpost, frame

How tags work:

• Each catalog item has multiple tags
• Users search with natural language — "waterproof handlebar bag under 200g" matches items tagged waterproof + handlebar-bag with weight < 200g
• Tags are suggested during search as refinement chips
• Tags are admin-curated to prevent fragmentation (users suggest, admins approve)

---

Core Flows

Flow 1: Adding Gear (FAB → Search → Add)

Entry point: The floating action button (+) on the collection view.

1. Click + → A mini menu appears near the button with two options:

   • 📦 Add to Collection — for gear you already own
   • 🔍 Start New Thread — to research a purchase

2. Full-screen search opens — regardless of which option was chosen:

   • Large search bar at top with back arrow
   • Quick tag chips below for common filters (Bags, Shelter, Lights, Cooking, etc.)
   • Context indicator: "Adding to Collection" or "Starting Thread"
   • "Add manually" link for items not in catalog

3. Type and search → Full-screen results:

   • Each result shows: name, rating badge, weight, price, owner count
   • Active tag filters shown as chips above results, with suggested refinements
   • Each result has an "+ Add" button

4. Click "+ Add" on a catalog result:

   • For Collection: Quick confirmation step — item details pre-filled from catalog, user picks their category and optionally adds notes. One tap to confirm.
   • For Thread: Instant add as candidate. No confirmation needed — it's just being added to a comparison list.

5. Item not found → "Add Manually":

   • Opens the manual entry form (existing ItemForm)
   • User fills in all fields themselves
   • After saving, a non-intrusive opt-in prompt: "Submit this to the global catalog? Other users could find it too."
   • If they dismiss it, don't ask again. The item works in their collection regardless.

Flow 2: Research Thread (Catalog-Driven)

The existing thread concept, but powered by the catalog:

1. User looks at their collection → "I need a new handlebar bag"
2. Clicks + → "Start New Thread"
3. Searches catalog: "handlebar bag"
4. Browses results — sees specs, ratings, owner counts, review links
5. Adds promising options as thread candidates (instant add)
6. Goes to thread view — candidates are there with all catalog data
7. Reads review links, compares specs, adds personal notes/pros/cons
8. Picks a winner → item moves to collection (existing resolution flow)

Flow 3: Catalog Submission

When a user manually adds an item that isn't in the catalog:

1. After saving, a subtle prompt appears: "Submit to catalog?"
2. If accepted, the item data (name, weight, price, image, etc.) becomes a pending submission
3. The item is usable in the user's collection immediately — submission is async
4. Admin reviews pending submissions — approve, reject, or merge with existing entry
5. On approval, the user's item automatically links to the new catalog entry

Submission states: pending_review → approved / rejected

Review is admin-only for now. No community moderation. Keep it simple — one person curates the catalog quality.

---

Navigation

The catalog is accessed through the add flow (FAB → search), not as a standalone page. There is no "Browse Catalog" link in the main nav. Discovery happens through:

• The add/thread flow (primary)
• Future: community feed showing what others are adding/reviewing
• Future: "Popular in category" sections

The existing /global-items route can remain as a direct URL for power users but doesn't need prominent navigation.

---

What Changes From Current State

New

• FAB mini menu (replace direct "add item" panel open)
• Full-screen catalog search overlay
• Search results page with catalog items
• Quick-add confirmation step (category picker + notes)
• Tag system on global items
• Catalog submission flow (manual entry → submit for review)
• Admin review queue for submissions
• Review links on catalog items (trusted publications)

Modified

• Thread creation — starts from catalog search instead of blank form
• Thread candidates <20><> can be added from catalog (linked to global item)
• Global items schema — add tags, rating, review links, submission status

Unchanged

• Collection view, setup management, existing item editing
• Thread comparison view, resolution flow
• Public profiles and setup sharing
• Single collection per user (multi-collection deferred)

---

Data Model Changes (Conceptual)

global_items gains:

• tags — array or join table for flexible tagging
• rating — aggregated score (future, when reviews exist)
• reviewLinks — JSON array of { title, url, source } for publication reviews
• submissionStatus — pending_review / approved / rejected
• submittedBy — user who submitted (for pending items)

New: tags table (or similar):

• Curated list of allowed tags
• Tag-to-global-item many-to-many relationship

thread_candidates gains:

• globalItemId — optional link to catalog item (like items have via itemGlobalLinks)

---

Future (Out of Scope)

These are acknowledged as part of the larger vision but not designed here:

• Community feed — Instagram/Reddit-style discovery of gear and setups
• User reviews and ratings — per-item reviews that aggregate into catalog rating
• Discussion threads — comment sections on catalog items
• Multi-collection — separate collections per activity (bikepacking, hiking, etc.)
• AI-powered search — natural language → structured query translation
• Price tracking — historical price data, deal alerts