makiolaj/GearBox
1
0
Fork 0
Code Issues 8 Pull Requests Actions Packages Projects Releases 10 Wiki Activity

docs: complete project research

Browse Source
This commit is contained in:
Jean-Luc Makiola
2026-04-09 14:44:12 +02:00
parent f9c69a1366
commit c4ad5c1b2a
4 changed files with 910 additions and 1592 deletions
Download Patch File Download Diff File Expand all files Collapse all files

356
.planning/research/FEATURES.md
View File

@@ -1,28 +1,26 @@
# Feature Research
**Domain:** Multi-user gear management and discovery platform
**Researched:** 2026-04-03
**Domain:** Public-first gear discovery platform with catalog enrichment
**Researched:** 2026-04-09
**Confidence:** MEDIUM-HIGH
**Milestone scope:** v2.1 Public Discovery — builds on v2.0 multi-user foundation
---
## Context
## Context: What Already Exists (v2.0)
This is the feature research for **v2.0 Platform Foundation** -- transforming GearBox from a single-user gear tracker into a multi-user platform with discovery, global item database, structured reviews, and setup sharing.
These are shipped. New features below only mention them when v2.1 extends them:
**Existing features (already built through v1.4):**
- Gear collection CRUD with categories, weight/price, images, quantity
- Full gear collection CRUD with weight/price tracking, categories, images
- Planning threads with candidate comparison, ranking, pros/cons, impact preview
- Named setups (loadouts) with classification, donut chart visualization
- Search/filter, CSV import/export, item duplication
- Dashboard home page, onboarding wizard
- Single-user auth (cookie sessions + API keys), MCP server (19 tools)
- Named setups with classification, donut chart, weight breakdowns
- PostgreSQL multi-user data model, Logto OIDC external auth
- S3 image storage (MinIO), global item catalog with tags and search
- User profiles with avatar/bio, public setup sharing
- Catalog-driven add flow, global FAB, item/catalog detail pages
- MCP server (19 tools), API key + OAuth auth methods
**Key project constraints:**
- No freeform UGC until moderation infrastructure exists (structured input only)
- Discovery-first, not social-first
- External auth provider (self-hosted, open-source)
- Postgres for multi-user platform
All features below are **new for v2.1** unless explicitly marked "extend existing."
---
@@ -30,150 +28,113 @@ This is the feature research for **v2.0 Platform Foundation** -- transforming Ge
### Table Stakes (Users Expect These)
Features users assume exist on any multi-user gear platform. Missing these makes the platform feel broken or pointless.
Features that public-first gear discovery platforms are expected to provide. Missing these makes the product feel broken or hostile to new visitors.
| Feature | Why Expected | Complexity | Notes |
|---------|--------------|------------|-------|
| **User registration and authentication** | Cannot have multi-user without accounts. Every platform has sign-up/login. | HIGH | External auth provider integration (Authentik, Keycloak, or similar). Replaces current single-user cookie auth. All existing entities need userId FK. |
| **User profiles (public)** | Every community platform has profiles. Users need identity to share and be discovered. | LOW | Minimal: display name, avatar URL, bio text, joined date. Public profile page lists user's public setups. No follower counts needed. |
| **Setup visibility controls** | Users will not share setups if they cannot control what is public. Privacy is table stakes for any sharing platform. | LOW | Binary public/private toggle per setup. Default to private (opt-in sharing). Existing setups migrated as private. |
| **Public setup detail pages** | Shared setup links must resolve to a readable page. If sharing is a feature, the shared thing must be viewable. | MEDIUM | Read-only view with item list, weight/cost totals, donut chart, creator attribution. No auth required for public setups. Extends existing setup detail view. |
| **Global item database (searchable)** | Users expect to find gear by name rather than entering specs from scratch every time. LighterPack's weakness is fully manual data entry. | HIGH | Central product catalog with brand, model, category, manufacturer weight, MSRP, product URL, image. Users search and link rather than re-enter. Seed with 200-500 items in core categories to bootstrap. This is the foundational dependency for reviews, aggregation, and item detail pages. |
| **Link personal items to global items** | Once a global DB exists, users expect to connect their gear to canonical entries for richer data. | MEDIUM | Optional FK from user items to global items. Enables aggregation (owner count, avg weight, reviews). Must handle items not yet in global DB gracefully. |
| **Item detail page (aggregated)** | When browsing gear, clicking an item should show consolidated info: specs, who owns it, ratings. Standard on any product platform. | HIGH | Aggregated view combining: manufacturer specs from global DB, owner count, setup appearances, average ratings, crowd-reported weights. This is the integration hub for all platform features. |
| **Structured reviews (ratings)** | Any product-oriented community needs evaluation. Users expect to rate gear and see what others think. | MEDIUM | Overall 1-5 star rating plus 3-5 dimension ratings (varies by product category). Attached to global items, not personal items. One review per user per global item. No freeform text per project constraint. |
| **Discovery browse page** | Users expect a way to find interesting setups and gear beyond their own collection. Without this, multi-user adds no value. | MEDIUM | Not algorithmic for v2.0. Three sections: recent public setups, recently reviewed items, popular gear (most owned). Simple sorted lists with pagination. |
| **Search global items** | Must be able to find products by name/brand in the global database. Powers linking, browsing, and review discovery. | MEDIUM | Full-text search on name, brand, category. Used in "link my item" flow, discovery browsing, and review lookup. Postgres full-text search or trigram index. |
| Browse catalog and setups without login | All comparable platforms (Lighterpack shared lists, BikeGearDatabase, RTINGS) allow full read access. Forcing login before browse kills SEO and casual discovery. | LOW | Middleware change: lift auth guard from all GET /api/* endpoints. Public setup sharing already exists at v2.0 — generalize to all read routes. Session-optional pattern already proven. |
| Discovery landing page with catalog search prominent | RTINGS, Wirecutter, and BikeGearDatabase all lead with search or category browse above the fold. Users arriving from search engines expect to search immediately, not to log in. | MEDIUM | Replace dashboard for unauthenticated visitors. Search bar + tag chips already exist as FAB overlay — promote to inline page hero. Authenticated users still see their dashboard. Route-level auth split. |
| Contextual auth prompt only on write actions | Users must understand the access model without reading documentation. "Browse freely, sign in to save" must be self-evident. Confusing this causes drop-off. | LOW | Inline "Sign in to add to your collection" CTA on catalog item detail pages. No login wall on any browse action. |
| Product attribution: brand and manufacturer fields | Any gear database users trust shows where a product originates. Missing attribution makes catalog look scraped or unverifiable. | LOW | Add `brand`, `manufacturer` fields to catalog items schema. Already has `name` — add structured attribution alongside. Display prominently on detail pages and cards. |
| Image source attribution display | Legal requirement and trust signal. Gear Patrol, BikeGearDatabase, and manufacturer catalogs all credit image source. Omitting creates IP risk on manufacturer-supplied images. | LOW | Add `imageCredit` (display text, e.g. "Apidura") and `imageSourceUrl` fields to catalog items. Display as "Photo: [credit]" beneath product images on detail pages. |
| Community usage signal on catalog items | Users expect to see "owned by N people" or "in N setups" to gauge real-world adoption. Lighterpack shows this per shared list. RTINGS shows review counts. | LOW | `ownerCount` already exists on catalog items in v2.0. Surface it prominently on catalog cards and detail pages. Add "appears in N setups" count derived from setupItems. |
| Shareable catalog item and setup URLs resolve without login | Public-first means deep-linking works. If a setup or catalog item URL is shared, it must render for anyone — no login redirect. | LOW | Detail pages already exist at v2.0. Verify: unauthenticated API responses work end-to-end, meta tags render, no auth redirect on page load. Likely already 90% working given public setup sharing. |
### Differentiators (Competitive Advantage)
Features that set GearBox apart from LighterPack, GearGrams, Trailspace, and MyGear. Aligned with core value: "help people make better gear decisions."
Features that set GearBox apart from Lighterpack (lists only, no catalog), BikeGearDatabase (editorial, not user collections), and generic wishlist tools.
| Feature | Value Proposition | Complexity | Notes |
|---------|-------------------|------------|-------|
| **Crowd-verified specs** | LighterPack trusts user-entered data blindly. GearBox can show "manufacturer says 450g, 12 owners measured avg 478g." Real-world weight verification is unique and high-value for weight-conscious users. | MEDIUM | Aggregate weightGrams from all user items linked to a global item. Compare against manufacturer spec. Display on item detail page. Needs sufficient linked items to be meaningful (threshold: 3+ owners). |
| **Review dimensions per product category** | Trailspace and OutdoorGearLab use editorial ratings with fixed dimensions. GearBox crowd-sources structured ratings with category-specific dimensions: a tent gets "weather protection, ventilation, setup ease" while a stove gets "boil time, fuel efficiency, packability." More relevant than one-size-fits-all. | MEDIUM | Define 3-5 rating dimensions per product category via admin config. Store dimension ratings alongside overall rating. Display as radar chart or bar chart on item detail page. |
| **"X people own this" social proof** | Shows popularity and real adoption. No gear tracker does this because they lack a global item database. Simple count, powerful signal. | LOW | Count of users who linked a collection item to this global item. Displayed prominently on item detail page and in search results. Zero implementation complexity once linking exists. |
| **Setup composition insights** | "This item appears in 47 bikepacking setups, commonly paired with Y and Z." Cross-setup analysis no competitor offers. Answers "what do people use this with?" | MEDIUM | Query across all public setups containing a given global item. Show co-occurrence patterns. Powerful but can be deferred to v2.x if query performance is a concern. |
| **Setup impact preview with global items** | Already built for personal items. Extending to global items lets users preview "adding this from the store to my setup changes weight by X." Bridges research and collection management. | LOW | Already exists for personal items. Add "preview in my setup" button on global item detail pages. Reuse existing impact preview logic. |
| **Planning threads with global item integration** | Research threads that pull in specs, reviews, and owner data from the global DB. Candidates link to global items for richer comparison than manual data entry. | MEDIUM | Add optional globalItemId to thread candidates. Auto-populate weight, price, image from global item. Show community ratings and owner count inline on candidates. |
| **Real-world weight distribution** | Histogram showing "owners report weights between 440g-490g" for a product. Beats a single manufacturer number. Valuable for ultralight community. | LOW | Aggregate weightGrams from all linked items. Display min/max/avg. Histogram if 10+ data points. |
| **Copy/fork public setups** | Use someone else's setup as a starting template. LighterPack has clunky CSV-based copying. One-click fork is much better UX. | LOW | Create new setup copying all items from a public setup. Items must exist in user's collection (or be linked to same global items). Clear UX for "items you do not own yet." |
| Discovery landing feed (community setups + catalog items) | No direct competitor combines a global gear catalog with user setup feeds. Lighterpack has no discovery page. BikeGearDatabase is editorial, not community-driven. GearBox can show real user gear choices with weight data. | MEDIUM | Two feed sections: (a) recently shared public setups sorted by recency, filterable by category; (b) popular/new catalog items by ownerCount. No algorithm needed at launch — recency + ownerCount is sufficient and honest. |
| Agent-powered catalog seeding via MCP tools | Unique to GearBox. No other gear platform has agent-friendly structured import. Enables rapid catalog population by Claude agent swarms without manual data entry. Programmatic SEO value compounds with catalog size. | HIGH | Requires: bulk create MCP tool, structured import with dry-run/preview mode, attribution tracking on agent-inserted records. GearBox already has MCP server and API key auth — foundation exists. |
| Catalog enrichment infrastructure with provenance tracking | Enables crowd + agent contributions with full source tracking. Comparable to Wikipedia's citation model but structured. Builds long-term trust in catalog data quality. | MEDIUM | New schema fields: `sourceUrl`, `sourceType` (enum: manufacturer / community / agent / import), `contributedBy` (userId or agent identifier string), `verifiedAt`. Migration only, lightweight UI needed initially. |
| SEO-indexable catalog pages ranking for product searches | Public catalog pages that rank for "[product name] weight specs" are a major organic acquisition channel. RTINGS built a durable traffic moat this way via programmatic SEO. GearBox can do the same for gear. | MEDIUM | Pages already exist. Add: `<title>` tags with product name + category, OG meta tags, JSON-LD Product schema markup. Primary complexity: TanStack Router is client-rendered — crawlers need either SSR or static prerender for bots. This is the phase's primary technical risk. |
| Setup impact preview teaser on public catalog pages | Showing "add this to your setup and base weight changes by +Xg" is unique. No other gear catalog does this. Showing the feature on public pages teases value and drives sign-up intent. | MEDIUM | Extend existing impact preview (v1.3) to show a teaser CTA on unauthenticated catalog detail pages: "See how this affects your setup → [Sign in to try]". Requires no new backend work — frontend auth-conditional render. |
### Anti-Features (Commonly Requested, Often Problematic)
| Feature | Why Requested | Why Problematic | Alternative |
|---------|---------------|-----------------|-------------|
| **Freeform text reviews** | Users want to explain their experience in detail | Requires moderation, spam filtering, content policy, reporting infrastructure. PROJECT.md explicitly defers until moderation exists. | Structured ratings with predefined dimensions. Short predefined tags for pros/cons (e.g., "lightweight", "durable", "runs small"). |
| **Comments on setups** | Social engagement, questions about gear choices | Moderation burden, notification system, spam, harassment risk. Deferred in PROJECT.md. | Link to user profile. Contact happens outside platform. |
| **Follow users / activity feed** | Social graph, staying updated on people | Turns a gear tool into a social network. Notification infrastructure, feed ranking, engagement metrics, retention loops. Project decision: discovery-first, not social-first. | Discovery feed shows popular/recent content without requiring social connections. |
| **Marketplace / buy-sell** | Users want to trade used gear | Payment processing, fraud prevention, disputes, shipping logistics, tax compliance. Massive liability. | Link to product URLs on global items. Users buy through retailers. |
| **AI gear recommendations** | "What tent should I buy for bikepacking?" | Training data requirements, bias, liability for bad recommendations, hallucination risk. | Global item pages with ratings, owner counts, and setup co-occurrence do implicit recommendation. "People who own X also own Y." |
| **Wiki-style open item editing** | Community wants to correct/enrich global item specs | Edit wars, vandalism, quality degradation, dispute resolution. PROJECT.md explicitly rules this out. | Structured contributions only: report measured weight, submit rating. Admin approval for spec corrections. Trusted contributor program later. |
| **Price tracking / deal alerts** | Users want to know when gear goes on sale | Requires scraping retailer sites, fragile, legal gray area, maintenance burden. PROJECT.md rules this out. | Store product URL so users can check prices manually. |
| **Real-time collaborative setups** | "Plan a group trip together" | WebSocket infrastructure, conflict resolution, permissions model, presence indicators. Massive complexity for niche use case. | Each user builds their own setup. Fork public setups as templates. |
| **Gamification (badges, points, levels)** | Drive engagement and contributions | Incentivizes quantity over quality. Users game systems for points rather than providing genuine data. Creates toxic dynamics. | Soft social proof: "contributed X reviews" on profile. No points, no leaderboards. |
| **Instagram-style infinite scroll feed** | Addictive browsing experience | Engagement-maximizing design conflicts with utility-focused tool. Users come to research decisions, not scroll endlessly. | Paginated, filterable discovery page. Browse with intent, not addiction. |
| Algorithmic feed ranking using engagement signals | "Show popular content" feels natural | Requires engagement data volume that does not exist at v2.1 scale. Empty or manipulated feed is worse than no feed. Gaming and spam risk immediately. | Simple recency + ownerCount sort. Add engagement signals only when data volume and moderation infrastructure justify it. |
| Open wiki-style catalog editing (anyone edits any item) | Fastest path to catalog enrichment | Data quality collapses without moderation. Adversarial edits, edit wars. Requires revert/history infrastructure. Already decided out-of-scope in PROJECT.md. | Structured contributions: users submit items, agents bulk-seed with attribution, admins verify. provenance fields track every change. |
| Bulk catalog import from scraped external sources | "Just import all BikeGearDB items" | Copyright risk. Data quality issues. Stale data. Attribution impossible — you do not know who owns the content. Legal exposure. | Agent-seeding via MCP with explicit source tracking. Manual + agent creates clean provenance chain with `sourceUrl` per item. |
| Real-time "X users viewing this" presence indicators | Social proof, FOMO feeling | Zero signal value at current traffic scale, adds WebSocket complexity, privacy concern for a utility tool. | ownerCount ("X people own this") is sufficient social proof without live presence tracking. |
| Comments on catalog items or setups | Community enrichment, Q&A | Freeform UGC explicitly blocked in PROJECT.md until moderation infrastructure exists. Moderation requires policy, tooling, reporting. | Structured fields only: tags, ratings, attribution. Defer freeform to future milestone after moderation is designed. |
| Social follow / activity feed | "See what friends added" | Social graph is a separate product. Deferred explicitly in PROJECT.md. Notification infrastructure, feed ranking, retention loops all out of scope. | Public setup browsing by category or recency is sufficient discovery without requiring a follow graph. |
| Infinite scroll personalized feed | "Netflix for gear" | Personalization requires user history. Unauthenticated visitors have no history. Personalized recommendations require ML infrastructure far beyond v2.1 scope. | Category-filtered browse + search. Personalization post-login once collection data exists is a v3+ feature. |
---
## Feature Dependencies
```
[External Auth Provider]
|
v
[Multi-User Data Model (userId FK on all entities)]
|
+---> [Postgres Migration] (concurrent access, auth provider needs Postgres)
|
+---> [User Profiles (public)]
| |
| +---> [Public Profile Pages]
| | |
| | +---> [Discovery Feed (browse users' public content)]
| |
| +---> [Setup Visibility Controls (public/private)]
| |
| +---> [Public Setup Detail Pages]
| |
| +---> [Copy/Fork Public Setups]
|
+---> [Global Item Database]
|
+---> [Search Global Items]
|
+---> [Link Personal Items to Global Items]
| |
| +---> [Owner Count ("X people own this")]
| |
| +---> [Crowd-Verified Specs (aggregated weight)]
| |
| +---> [Setup Appearances Count]
| |
| +---> [Real-World Weight Distribution]
|
+---> [Structured Reviews]
| |
| +---> [Review Dimensions per Category]
| |
| +---> [Average Ratings Display]
|
+---> [Item Detail Pages (aggregated hub)]
| |
| +---> [Setup Composition Insights]
|
+---> [Planning Thread Global Item Integration]
|
+---> [Candidate Auto-populate from Global DB]
Public browse without login
└──prerequisite for──> Discovery landing page (needs unauth API render)
└──prerequisite for──> SEO-indexable catalog pages (bots must reach pages)
└──prerequisite for──> Setup impact preview teaser on public pages
└──prerequisite for──> Shareable URLs confirmed working without auth
Catalog enrichment schema (attribution fields)
└──prerequisite for──> Agent-powered MCP catalog seeding (tools write into these fields)
└──prerequisite for──> Image attribution display (imageCredit field must exist)
└──prerequisite for──> Source provenance display on detail pages
Agent-powered MCP catalog seeding tools
└──requires──> Catalog enrichment schema (attribution fields must exist first)
└──enhances──> Discovery landing feed (more items = richer feed)
└──enhances──> SEO surface area (more pages = more potential rankings)
Discovery landing page
└──requires──> Public browse without login
└──requires──> Feed query API (popular setups + recent catalog items)
└──uses existing──> Catalog search (FAB overlay promoted to page hero)
SEO metadata on catalog pages
└──requires──> Public browse without login (bots must reach pages)
└──depends on──> Crawlability solution (SSR or prerender for TanStack Router)
└──enhances──> Agent-seeded catalog (more items = more indexed pages)
Setup impact preview teaser (public)
└──requires──> Public browse without login
└──depends on existing──> Impact preview feature (v1.3, already shipped)
```
### Dependency Notes
- **Multi-user data model is the absolute foundation.** Every feature depends on userId ownership. Items, setups, threads, categories, reviews -- all need user scoping. This is the biggest single migration.
- **Postgres migration is coupled with auth.** The external auth provider (Authentik, Keycloak) needs Postgres. Migrating the app DB at the same time avoids running two databases. Do these together.
- **Global item database is the second foundation.** Reviews, item detail pages, owner counts, crowd-verified specs, and planning thread integration all depend on canonical global item records. Without this, multi-user is just "LighterPack with accounts."
- **Structured reviews require global items.** Reviews attach to global items, not personal collection items. Otherwise reviews fragment across duplicate user-entered items with no way to aggregate.
- **Item detail pages are the integration point.** They combine global item specs, aggregated user data, reviews, owner count, and setup appearances. Should be built after all data sources exist.
- **Discovery feed requires profiles + public content.** Cannot browse without user identity and visibility controls producing public content to show.
- **Linking is the bridge.** Personal items link to global items. This single FK enables owner count, crowd-verified specs, weight distribution, and setup appearances. Prioritize this flow.
- **Public browse is the prerequisite for everything.** Auth middleware change must land first. All other v2.1 features depend on unauthenticated API access working correctly.
- **Catalog enrichment schema must precede agent MCP tools.** The bulk create and import MCP tools write attribution fields. Building tools before schema means schema-breaking changes later.
- **SEO crawlability is the primary technical risk.** TanStack Router renders client-side. Search engine bots do not execute JavaScript. Without SSR or a static prerender pass, catalog pages will not be indexed. This is a known gap with the current stack — needs a solution before SEO-targeted work makes sense. Defer SEO metadata work to P2 until crawlability is resolved.
- **Agent seeding is high complexity but high leverage.** It is both a catalog population tool and a v2.1 launch enabler. Without sufficient catalog items, the discovery feed is thin and the platform feels empty. Prioritize MCP tooling early so catalog seeding can run in parallel with UI work.
---
## MVP Definition
### Launch With (v2.0 Platform Foundation)
This is a subsequent milestone on an existing shipped product. MVP here means minimum to deliver the v2.1 goal: public-first discovery platform.
- [ ] **External auth provider integration** -- Nothing works without multi-user identity
- [ ] **Postgres migration** -- Required for concurrent access; auth provider dependency
- [ ] **Multi-user data model** -- userId on items, setups, threads, categories; data isolation
- [ ] **User profiles (minimal)** -- Display name, avatar, bio; public profile page
- [ ] **Setup visibility controls** -- Public/private toggle, default private
- [ ] **Public setup detail pages** -- Shareable read-only view with attribution
- [ ] **Global item database with seed data** -- Schema, admin seeding, search
- [ ] **Link personal items to global items** -- Association flow in collection UI
- [ ] **Structured reviews** -- Overall rating + dimension ratings on global items
- [ ] **Item detail pages** -- Aggregated specs, owner count, average ratings
- [ ] **Discovery browse page** -- Recent public setups, recently reviewed, popular items
### Launch With (v2.1 core)
### Add After Validation (v2.x)
- [ ] Public browse without login — lift auth guard from all GET routes. Every other feature depends on this.
- [ ] Discovery landing page — replaces dashboard for unauthenticated visitors. Catalog search hero + two feed sections (recent setups, popular catalog items). Recency + ownerCount sort, no algorithm.
- [ ] Catalog enrichment schema migration — add `brand`, `manufacturer`, `sourceUrl`, `sourceType`, `imageCredit`, `imageSourceUrl`, `contributedBy` fields. Schema first, UI follows.
- [ ] Image attribution display on catalog detail pages — "Photo: [credit]" below product images, sourced from new `imageCredit` field.
- [ ] Agent MCP catalog seeding tools — bulk create endpoint/tool, structured import with attribution, dry-run/preview mode, batch result reporting.
- [ ] Initial catalog population via agent — run agent seeding for 3-5 priority categories (bikepacking bags, tents, sleeping bags, navigation devices, cycling computers). Target: 100+ catalog items with attribution.
- [ ] Community usage signals surfaced — ownerCount and "appears in N setups" count prominent on catalog cards and detail pages.
- [ ] **Crowd-verified specs display** -- "Manufacturer: 450g, Community avg: 478g" (needs 3+ owners per item to be meaningful)
- [ ] **Setup composition insights** -- "Commonly paired with" co-occurrence analysis
- [ ] **Planning thread global item integration** -- Candidates auto-populate from global DB
- [ ] **Popular gear rankings by category** -- Most owned, highest rated per category
- [ ] **Copy/fork public setups** -- One-click template from public setups
- [ ] **Review dimension customization** -- Admin configures rating dimensions per product category
- [ ] **Real-world weight distribution** -- Histogram on item detail pages
- [ ] **Global item suggestion workflow** -- Users propose new items for admin review
### Add After Core is Stable (v2.1.x)
### Future Consideration (v3+)
- [ ] Contextual "See how this affects your setup" CTA on public catalog pages — setup impact preview teaser with login prompt. Add once public browse is confirmed stable.
- [ ] Manufacturer/brand filter on catalog browse — add brand as a filterable facet. Only valuable once catalog volume justifies filtering (target: after initial seeding).
- [ ] SEO metadata on catalog pages — `<title>`, OG tags, JSON-LD Product schema. Add after crawlability solution is determined.
- [ ] **Freeform reviews with moderation** -- After moderation infrastructure exists
- [ ] **Comments on setups** -- After moderation infrastructure exists
- [ ] **Follow users / activity feed** -- After discovery model is validated
- [ ] **OAuth / social login** -- After external auth provider is stable
- [ ] **Trusted contributor program** -- Verified users can edit global item specs
### Future Consideration (v2.2+)
- [ ] Personalized discovery feed post-login — requires collection data volume and recommendation design.
- [ ] Verified catalog item badge — admin-marked verified items. Requires admin tooling.
- [ ] User-submitted catalog enrichment — structured form to suggest corrections or add missing items. Requires contribution review workflow.
- [ ] Engagement signals in feed — view count, saves. Requires data volume to be meaningful.
---
@@ -181,122 +142,57 @@ Features that set GearBox apart from LighterPack, GearGrams, Trailspace, and MyG
| Feature | User Value | Implementation Cost | Priority |
|---------|------------|---------------------|----------|
| External auth provider | HIGH | HIGH | P1 |
| Postgres migration | HIGH | HIGH | P1 |
| Multi-user data model (userId on entities) | HIGH | HIGH | P1 |
| User profiles (basic) | HIGH | LOW | P1 |
| Setup visibility controls | HIGH | LOW | P1 |
| Public setup detail pages | HIGH | MEDIUM | P1 |
| Global item database (schema + seed) | HIGH | HIGH | P1 |
| Link personal items to global items | HIGH | MEDIUM | P1 |
| Search global items | HIGH | MEDIUM | P1 |
| Structured reviews | HIGH | MEDIUM | P1 |
| Item detail pages (aggregated) | HIGH | HIGH | P1 |
| Discovery browse page | MEDIUM | MEDIUM | P1 |
| Crowd-verified specs | HIGH | LOW | P2 |
| Setup composition insights | MEDIUM | MEDIUM | P2 |
| Planning thread global DB integration | MEDIUM | MEDIUM | P2 |
| Copy/fork public setups | MEDIUM | LOW | P2 |
| Popular gear rankings | MEDIUM | LOW | P2 |
| Freeform reviews + moderation | MEDIUM | HIGH | P3 |
| Follow users | LOW | MEDIUM | P3 |
| Setup comments | LOW | MEDIUM | P3 |
| Public browse without login | HIGH | LOW | P1 |
| Discovery landing page | HIGH | MEDIUM | P1 |
| Catalog enrichment schema (attribution fields) | HIGH | LOW | P1 |
| Image attribution display | MEDIUM | LOW | P1 |
| Agent MCP catalog seeding tools | HIGH | HIGH | P1 |
| Initial catalog population (agent run) | HIGH | MEDIUM (depends on MCP tools) | P1 |
| Community usage signals (ownerCount visible) | MEDIUM | LOW | P1 |
| Shareable URL audit (confirm unauth render) | HIGH | LOW | P1 |
| Setup impact preview teaser (public) | MEDIUM | MEDIUM | P2 |
| Brand/manufacturer filter on catalog browse | LOW | LOW | P2 |
| SEO metadata on catalog pages | MEDIUM | MEDIUM (crawlability dependency) | P2 |
| Personalized discovery feed | MEDIUM | HIGH | P3 |
| Verified catalog badge | LOW | MEDIUM | P3 |
| User-submitted enrichment form | LOW | MEDIUM | P3 |
**Priority key:**
- P1: Must have for v2.0 platform launch
- P2: Should have, add in v2.x once core is validated
- P3: Future consideration, requires new infrastructure (moderation, notifications)
- P1: Required for v2.1 milestone goal
- P2: Add once v2.1 core is validated
- P3: Future consideration, requires new infrastructure
---
## Competitor Feature Analysis
| Feature | LighterPack | GearGrams | Trailspace | MyGear | GearBox v2.0 |
|---------|-------------|-----------|------------|--------|-------------|
| Gear lists/setups | Yes, drag-and-drop | Yes, trip-based | No (review only) | Yes, "Locker" | Yes, named setups with classification |
| Weight tracking | Base/worn/consumable | Carried/worn/consumable | No | Basic | Base/worn/consumable + unit conversion + donut charts |
| User profiles | Minimal (no bio) | Minimal | Review history page | Full social profile | Display name, avatar, bio, public setups |
| Sharing | Public link, embed code | Public link | N/A | Social feed posts | Public/private toggle, shareable URLs |
| Global item database | No (all user-entered) | No | Yes (editorial catalog) | No | Yes, seeded + crowd-enriched with verified specs |
| Structured reviews | No | No | Yes (summary/pros/cons + rating) | Basic star rating | Dimension ratings per product category |
| Item aggregation | No | No | Editorial scores only | No | Owner count, avg weight, setup appearances, crowd specs |
| Discovery/browse | No | No | Browse by category | AI-tagged social feed | Browse setups, items, popular gear (intent-driven, not feed) |
| Purchase research | No | No | Price comparison links | No | Planning threads with candidates, ranking, impact preview |
| Crowd-verified specs | No | No | No | No | Manufacturer vs. community-measured weight comparison |
| Mobile app | No | Yes (iOS/Android) | No | Yes (iOS/Android) | No (responsive web, per project constraint) |
### Competitive Positioning
GearBox occupies a unique niche: the only platform combining **gear management** (LighterPack's strength), **structured community reviews** (Trailspace's strength), and **crowd-verified specs** (nobody does this). The planning threads feature has no direct competitor equivalent in the gear domain.
**Key advantages over each competitor:**
- **vs. LighterPack:** Global item database eliminates manual spec entry. Multi-user with profiles and sharing. Structured reviews provide community intelligence.
- **vs. GearGrams:** Richer comparison tools (planning threads). Crowd-verified specs. Item detail pages with aggregated data.
- **vs. Trailspace:** Not just reviews -- full gear management and setup composition. Users own and track their gear, not just review it. Crowd ratings, not editorial-only.
- **vs. MyGear:** Not social-first (no engagement loops, no AI tagging gimmicks). Utility-focused: research decisions, verify specs, compare options. Hobby-agnostic data model.
**Accepted gaps:**
- No mobile native app (web-first, responsive design sufficient per project constraints)
- No social feed in the Instagram sense (intentional: discovery-first, not social-first)
- No freeform text content (intentional: structured input only until moderation exists)
---
## Implementation Notes for Key Features
### Global Item Database Schema
The global item table is distinct from user items. It represents canonical products:
- `globalItems`: id, brand, model, name (display), categoryId, manufacturerWeightGrams, manufacturerPriceCents, productUrl, imageFilename, description, createdAt, updatedAt, createdByUserId
- User items get optional `globalItemId` FK for linking
- Admin-seeded initially; later users can suggest additions via a proposal workflow
### Structured Review Schema
- `reviews`: id, userId, globalItemId, overallRating (1-5), createdAt, updatedAt
- `reviewDimensionRatings`: id, reviewId, dimensionId, rating (1-5)
- `reviewDimensions`: id, categoryId, name (e.g., "durability", "packability"), sortOrder
- Unique constraint: one review per user per global item
- Dimensions are per-category, admin-defined
### Discovery Feed Approach
Not a personalized algorithmic feed. Three content streams, each a simple sorted query:
1. **Recent public setups** -- ORDER BY createdAt DESC, paginated
2. **Recently reviewed items** -- Global items with recent reviews, ORDER BY latest review date
3. **Popular gear** -- Global items ORDER BY linked owner count DESC
No recommendation engine. No engagement scoring. Users browse with intent.
### User Profile Data
Minimal profile extending the auth provider's user record:
- Display name (from auth provider or custom)
- Avatar URL (from auth provider or uploaded)
- Bio (short text, 280 char limit)
- Joined date
- Public setups list (derived from setup visibility)
- Review count (derived)
- Collection size (count of items, public stat)
| Feature | Lighterpack | BikeGearDatabase | RTINGS | GearBox v2.1 |
|---------|-------------|------------------|--------|--------------|
| Browse without login | Yes (shared list links only) | Yes (all content public) | Yes (fully public) | Yes — all catalog + setups public |
| Discovery landing page | No (login required to see anything) | Yes (editorial feed + categories) | Yes (category browse + new/updated) | Yes — catalog search hero + community feed |
| Global gear catalog | No (fully user-entered) | Editorial reviews only | Product test database | Yes — crowd + agent-seeded with attribution |
| Image attribution | N/A (no images) | Editorial photo credit | Manufacturer-supplied images | Explicit imageCredit + imageSourceUrl fields |
| Community setups visible publicly | Yes (shared list links) | No | No | Yes — public setups with weight data |
| Setup weight analysis | Yes (per list) | No | No | Yes + impact preview |
| Agent-friendly catalog API (MCP) | No | No | No | Yes — unique differentiator |
| SEO catalog pages | No | Yes (editorial articles) | Yes (programmatic product pages) | Target for v2.1.x after crawlability resolved |
| Provenance / source tracking | No | Editorial byline only | "Tested by RTINGS staff" | Yes — sourceType enum, contributedBy, sourceUrl |
---
## Sources
- [LighterPack](https://lighterpack.com/) -- Gear list builder, community standard for ultralight hikers. Public sharing via link, no profiles or reviews.
- [LighterPack tutorial (99Boulders)](https://www.99boulders.com/lighterpack-tutorial) -- Feature overview including sharing, linking, limitations.
- [GearGrams](https://www.geargrams.com/) -- Trip-based gear list tracker with weight classification.
- [Trailspace](https://www.trailspace.com/) -- User gear reviews with structured Summary/Pros/Cons format and Review Corps program.
- [Trailspace Review Form](https://www.trailspace.com/blog/2012/02/29/new-gear-review-form.html) -- Details on structured review fields with category-specific suggestions.
- [MyGear](https://mygear.world/) -- Social app for sports gear with Locker, feed, AI gear recognition, challenges.
- [Outdoor Gear Lab](https://www.outdoorgearlab.com/) -- Professional structured gear reviews with side-by-side comparison methodology.
- [Ultralight App](https://trailsmag.net/blogs/hiker-box/ultralight-the-gear-tracking-app-i-m-leaving-lighterpack-for) -- LighterPack alternative analysis showing community pain points.
- [Ready Set Sim](https://www.readysetsim.com/) -- Sim racing gear profiles and build sharing (cross-domain reference for hobby-agnostic patterns).
- [GetStream Social Feed Architecture](https://getstream.io/blog/social-media-feed/) -- Feed implementation patterns and anti-patterns.
- [LighterPack](https://lighterpack.com/) — public list sharing model, community usage patterns. Public browse only via shared links, no general discovery. (MEDIUM confidence, WebSearch)
- [Bike Gear Database](https://www.bikegeardatabase.com/) — public editorial gear catalog, category browse patterns, ~30k monthly visitors. (MEDIUM confidence, WebSearch)
- [RTINGS SEO Case Study — Ahrefs](https://ahrefs.com/blog/rtings-seo-case-study/) — programmatic SEO via catalog pages, category-based navigation, discovery-oriented layout. (MEDIUM confidence)
- [NN/G E-commerce Homepages and Listing Pages](https://www.nngroup.com/articles/ecommerce-homepages-listing-pages/) — subcategory surfacing above listings improves discoverability; 30-50% of product interactions come from unintended category navigation. (HIGH confidence)
- [Sales Layer MCP Server for catalog enrichment](https://www.saleslayer.com/ai-pim/mcp) — agent-powered product information management, bulk update patterns, audit and quality scoring via MCP tools. (MEDIUM confidence)
- [Creative Commons Attribution Best Practices](https://wiki.creativecommons.org/wiki/Recommended_practices_for_attribution) — TASL attribution standard; attribution must be visible and associated with the image. (HIGH confidence)
- [Pixsy Image Credits Guide](https://www.pixsy.com/image-licensing/image-credits) — legal requirements and UX placement for image credits; "image courtesy of" as standard phrasing. (HIGH confidence)
- [GS1 Image Standards](https://orbitvu.com/blog/gs1-image-standards-how-automation-can-help-effective-product-representation/) — product image metadata standards including GTIN linkage and consistent attribution for catalog platforms. (MEDIUM confidence)
- PROJECT.md — existing feature set, out-of-scope decisions, constraints, v2.1 milestone definition. (HIGH confidence, first-party)
---
*Feature research for: GearBox v2.0 Platform Foundation -- multi-user gear discovery platform*
*Researched: 2026-04-03*
*Feature research for: GearBox v2.1 Public Discovery — public-first gear discovery platform*
*Researched: 2026-04-09*