# GearBox

## What This Is

A gear management and discovery platform. Users catalog their gear collections (bikepacking, sim racing, or any hobby), track weight, price, and source details, research purchases through planning threads with side-by-side comparison, and compose named setups (loadouts) with weight classification and visualization. A global item database with crowd-verified specs and structured reviews helps users make informed purchase decisions. Multi-user with public setup sharing and gear discovery.

## Core Value

Help people make better gear decisions — discover what others use, compare real-world data, and see how a potential buy affects your setup before committing.

## Requirements

### Validated

- ✓ Gear collection with item CRUD (name, weight, price, category, notes, product link) — v1.0
- ✓ Image uploads for gear items — v1.0
- ✓ User-defined categories with automatic weight/cost totals — v1.0
- ✓ Planning threads for purchase research with candidate products — v1.0
- ✓ Thread resolution: pick a winner, it moves to collection — v1.0
- ✓ Named setups (loadouts) composed from collection items — v1.0
- ✓ Live weight and cost totals per setup — v1.0
- ✓ Dashboard home page with summary cards — v1.0
- ✓ Onboarding wizard for first-time setup — v1.0
- ✓ Thread creation with category assignment via modal dialog — v1.1
- ✓ Planning tab with educational empty state and pill tab navigation — v1.1
- ✓ Image display on item detail views and gear cards with placeholders — v1.1
- ✓ Hero image upload area with preview and click-to-upload — v1.1
- ✓ Lucide icon picker for categories (119 curated icons, 8 groups) — v1.1
- ✓ Automatic emoji-to-Lucide icon migration for existing categories — v1.1
- ✓ Search items by name with instant filtering — v1.2
- ✓ Filter collection items by category with icon-aware dropdown — v1.2
- ✓ Combined text search with category filter and result count — v1.2
- ✓ One-action filter clear — v1.2
- ✓ Weight unit selection (g, oz, lb, kg) with persistence — v1.2
- ✓ All weight displays respect selected unit across entire app — v1.2
- ✓ Per-setup item classification (base weight, worn, consumable) — v1.2
- ✓ Setup weight subtotals by classification — v1.2
- ✓ Donut chart visualization with category/classification toggle — v1.2
- ✓ Chart hover tooltips with weight and percentage — v1.2
- ✓ Candidate status tracking (researching/ordered/arrived) — v1.2
- ✓ Planning category filter with Lucide icons — v1.2
- ✓ Candidate pros/cons annotation and ranking with drag-to-reorder — v1.3
- ✓ Side-by-side candidate comparison table with weight/price deltas — v1.3
- ✓ Setup impact preview for candidates (replacement vs addition detection) — v1.3
- ✓ PostgreSQL database with async operations, PGlite test infra, Docker Compose — v2.0
- ✓ External OIDC auth via Logto with three-way auth middleware — v2.0
- ✓ Multi-user data model with userId isolation on all entities — v2.0
- ✓ S3 object storage (MinIO) for images replacing local filesystem — v2.0
- ✓ Global item catalog with search, owner count, and 18-item seed — v2.0
- ✓ User profiles with avatar/bio, public setup sharing — v2.0
- ✓ Reference item model with COALESCE merge for global-to-personal overlay — v2.0
- ✓ Tag system for catalog discovery with AND-filtered search — v2.0
- ✓ Global FAB with catalog search overlay and tag chip filtering — v2.0
- ✓ Item and catalog detail pages replacing slide-out panels — v2.0
- ✓ Add-from-catalog flow for collection items and thread candidates — v2.0
- ✓ Manual entry fallback with catalog submission prompt stub — v2.0

### Active

## Current Milestone: v2.1 Public Discovery

**Goal:** Transform GearBox from a login-first tool into a public-first discovery platform with always-on catalog search and a browsable feed of community content.

**Target features:**
- Public access auth model — browse everything without login, auth only gates collection management
- Discovery landing page replacing dashboard — catalog search bar at top, feed of popular setups/items/categories below
- Catalog enrichment infrastructure — attribution fields, source tracking, agent-friendly import tools
- Initial catalog seeding — populate key categories via MCP agent swarm

### Future

- [ ] Freeform reviews with moderation system
- [ ] Comments on setups
- [ ] Follow users / activity feeds
- [ ] OAuth / social login providers
- [ ] User-to-user messaging

### Out of Scope

- Custom comparison parameters — complexity trap, weight/price covers 80% of cases
- Mobile native app — web-first, responsive design sufficient
- Price tracking / deal alerts — requires scraping, fragile
- Barcode scanning — poor UX, manual entry is fine with global database
- Real-time weather integration — only outdoor-specific, GearBox is hobby-agnostic
- Freeform UGC (reviews, comments) — defer until moderation infrastructure exists
- User-to-user messaging — high moderation burden, not core to discovery
- Wiki-style open item editing — structured contributions only for data quality
- Maintaining SQLite single-user mode in parallel — diverged at v2.0

## Context

Shipped through v2.0 with 23,970 LOC TypeScript across 210+ files. All milestones v1.0-v2.0 complete.
Tech stack: React 19, Hono, Drizzle ORM, PostgreSQL, TanStack Router/Query, Tailwind CSS v4, Lucide React, Recharts, framer-motion, all on Bun.
Primary use case is bikepacking gear but data model is hobby-agnostic.
Auth: External OIDC via Logto (browser sessions) + API keys (programmatic) + MCP OAuth (Claude).
Infrastructure: PostgreSQL, MinIO (S3-compatible image storage), Docker Compose for dev/prod.
Features: MCP server (19 tools), global item catalog, user profiles, public setup sharing, catalog-driven gear flow, item/candidate detail pages, candidate ranking/comparison/impact preview.
18+ test files (service-level, route-level integration, MCP). E2E tests pending rewrite for OIDC auth (backlog 999.1).

## Constraints

- **Runtime**: Bun — used as package manager and runtime
- **Design**: Light, airy, minimalist — white/light backgrounds, lots of whitespace, no visual clutter
- **Navigation**: Dashboard-based home page, not sidebar or top-nav tabs
- **Auth**: External self-hosted provider — no in-house auth maintenance
- **Database**: PostgreSQL with Drizzle ORM
- **UGC**: Structured input only (ratings, predefined fields) — no freeform text until moderation exists
- **Scope**: Multi-user platform with public discovery

## Key Decisions

| Decision | Rationale | Outcome |
|----------|-----------|---------|
| Cookie/API key auth | Single user, public read + authenticated write | ✓ Good |
| Generic data model | Support any hobby, not just bikepacking | ✓ Good |
| Dashboard navigation | Clean entry point, not persistent nav | ✓ Good |
| Bun runtime | User preference | ✓ Good |
| Service layer with DI | Accept db as first param for testability | ✓ Good |
| Hono context variables for DB | Enables in-memory SQLite integration tests | ✓ Good |
| Prices stored as cents | Avoids float rounding issues | ✓ Good |
| Vite proxy dev setup | Required by TanStack Router plugin | ✓ Good |
| drizzle-kit needs better-sqlite3 | bun:sqlite not supported by CLI | ✓ Good |
| Tab navigation via URL params | Shareable URLs between gear/planning | ✓ Good |
| Setup item sync: delete-all + re-insert | Simpler than diffing, atomic in transaction | ✓ Good |
| Onboarding state in SQLite settings | Source of truth in DB, not Zustand | ✓ Good |
| Stay with SQLite | Single-user app, no need for Postgres complexity | ✓ Good |
| Lucide Icons for categories | Best outdoor/gear icon coverage, tree-shakeable, clean style | ✓ Good |
| categoryId on threads (NOT NULL FK) | Every thread belongs to a category | ✓ Good |
| Modal dialog for thread creation | Cleaner UX, supports category selection | ✓ Good |
| Hero image area at top of forms | Image-first UX, 4:3 aspect ratio consistent with cards | ✓ Good |
| Emoji-to-icon automatic migration | One-time schema rename + data conversion via Drizzle migration | ✓ Good |
| ALTER TABLE RENAME COLUMN for SQLite | Simpler than table recreation for column rename | ✓ Good |
| Platform pivot at v2.0 | Single-user model proven, now build for multi-user discovery | ✓ Good |
| External auth provider (Logto) | Avoid in-house auth security burden, self-hosted + open-source | ✓ Good |
| SQLite to Postgres | Multi-user platform needs proper concurrent DB; auth provider needs Postgres anyway | ✓ Good |
| Single-user mode diverges at v2.0 | Platform features irrelevant for solo use; maintained as separate artifact if needed | ✓ Good |
| Structured UGC only (no freeform) | Minimize moderation burden; ratings + predefined fields cover 80% of value | ✓ Good |
| Discovery-first, not social-first | Users come to research gear decisions, not to build social graphs | ✓ Good |
| COALESCE merge for reference items | Global base + personal overlay without data duplication | ✓ Good |
| Catalog-first add flow with manual fallback | Encourages catalog usage while preserving flexibility | ✓ Good |
| Detail pages replacing slide-out panels | Better UX for complex data, shareable URLs | ✓ Good |
| Weight conversion precision: g=0dp, oz=1dp, lb=2dp, kg=2dp | Matches common usage conventions | ✓ Good |
| Unit toggle in TotalsBar (not settings page) | Visible, quick access for frequent switching | ✓ Good |
| CategoryFilterDropdown separate from CategoryPicker | Filter vs form concerns are different | ✓ Good |
| No debounce on search input | Collection under 1000 items, instant feedback | ✓ Good |
| StatusBadge popup with click-outside dismiss | Consistent with CategoryPicker pattern | ✓ Good |
| Classification on setupItems join table | Same item can have different roles per setup | ✓ Good |
| Click-to-cycle for ClassificationBadge | Only 3 values, simpler than popup | ✓ Good |
| Classification-preserving sync via Map | Save metadata before delete, restore after re-insert | ✓ Good |
| Recharts for charting | Mature React chart library, composable API | ✓ Good |

## Evolution

This document evolves at phase transitions and milestone boundaries.

**After each phase transition** (via `/gsd:transition`):
1. Requirements invalidated? → Move to Out of Scope with reason
2. Requirements validated? → Move to Validated with phase reference
3. New requirements emerged? → Add to Active
4. Decisions to log? → Add to Key Decisions
5. "What This Is" still accurate? → Update if drifted

**After each milestone** (via `/gsd:complete-milestone`):
1. Full review of all sections
2. Core Value check — still the right priority?
3. Audit Out of Scope — reasons still valid?
4. Update Context with current state

---
*Last updated: 2026-04-09 after v2.1 milestone start*