docs: add catalog-driven gear flow design spec
Conceptual vision for integrating the global catalog into the add/edit flow — search-first UX, tag system, catalog submission with review, and thread-driven research from catalog items. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,187 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user