makiolaj/GearBox
1
0
Fork 0
Code Issues 8 Pull Requests Actions Packages Projects Releases 10 Wiki Activity
Files
59deaea95a090647ec8843779b65dbdabf5f33d3
GearBox/.planning/research/FEATURES.md

23 KiB
Raw Blame History

Feature Research

Domain: Multi-user gear management and discovery platform Researched: 2026-04-03 Confidence: MEDIUM-HIGH

Context

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.

Existing features (already built through v1.4):

  • Gear collection CRUD with categories, weight/price, images, quantity
  • 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)

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

Feature Landscape

Table Stakes (Users Expect These)

Features users assume exist on any multi-user gear platform. Missing these makes the platform feel broken or pointless.

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.

Differentiators (Competitive Advantage)

Features that set GearBox apart from LighterPack, GearGrams, Trailspace, and MyGear. Aligned with core value: "help people make better gear decisions."

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."

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.

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]

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.

MVP Definition

Launch With (v2.0 Platform Foundation)

  • 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

Add After Validation (v2.x)

  • 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

Future Consideration (v3+)

  • 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

Feature Prioritization Matrix

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

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)

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)

Sources

  • LighterPack -- Gear list builder, community standard for ultralight hikers. Public sharing via link, no profiles or reviews.
  • LighterPack tutorial (99Boulders) -- Feature overview including sharing, linking, limitations.
  • GearGrams -- Trip-based gear list tracker with weight classification.
  • Trailspace -- User gear reviews with structured Summary/Pros/Cons format and Review Corps program.
  • Trailspace Review Form -- Details on structured review fields with category-specific suggestions.
  • MyGear -- Social app for sports gear with Locker, feed, AI gear recognition, challenges.
  • Outdoor Gear Lab -- Professional structured gear reviews with side-by-side comparison methodology.
  • Ultralight App -- LighterPack alternative analysis showing community pain points.
  • Ready Set Sim -- Sim racing gear profiles and build sharing (cross-domain reference for hobby-agnostic patterns).
  • GetStream Social Feed Architecture -- Feed implementation patterns and anti-patterns.

Feature research for: GearBox v2.0 Platform Foundation -- multi-user gear discovery platform Researched: 2026-04-03

Reference in New Issue View Git Blame Copy Permalink