# 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 �� 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