From e59e724d840e608ba41339c283042882490534a2 Mon Sep 17 00:00:00 2001 From: Jean-Luc Makiola Date: Sun, 5 Apr 2026 18:25:39 +0200 Subject: [PATCH] docs: add catalog-driven gear flow design spec MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- ...6-04-05-catalog-driven-gear-flow-design.md | 187 ++++++++++++++++++ 1 file changed, 187 insertions(+) create mode 100644 docs/superpowers/specs/2026-04-05-catalog-driven-gear-flow-design.md diff --git a/docs/superpowers/specs/2026-04-05-catalog-driven-gear-flow-design.md b/docs/superpowers/specs/2026-04-05-catalog-driven-gear-flow-design.md new file mode 100644 index 0000000..49e52db --- /dev/null +++ b/docs/superpowers/specs/2026-04-05-catalog-driven-gear-flow-design.md @@ -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 �� 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