docs: start milestone v2.0 Platform Foundation

.planning/PROJECT.md

@@ -2,11 +2,11 @@
 
 ## What This Is
 
-A web-based gear management and purchase planning app. Users catalog their gear collections (bikepacking, sim racing, or any hobby), track weight, price, and source details, search and filter by name or category, and use planning threads to research and compare new purchases with status tracking. Named setups let users compose loadouts with weight classification (base/worn/consumable), donut chart visualization, and live totals in selectable units. Built as a single-user app with a clean, minimalist interface.
+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
 
-Make it effortless to manage gear and plan new purchases — see how a potential buy affects your total setup weight and cost before committing.
+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
 
@@ -42,45 +42,58 @@ Make it effortless to manage gear and plan new purchases — see how a potential
 
 ### Active
 
-## Current Milestone: v1.3 Research & Decision Tools
+## Current Milestone: v2.0 Platform Foundation
 
-**Goal:** Give users the tools to actually decide between candidates — compare details side-by-side, see how a pick impacts their setup, and rank/annotate their options.
+**Goal:** Transform GearBox from a single-user gear tracker into a multi-user platform where people discover gear, research purchases using crowd-verified data, and share their setups.
 
 **Target features:**
-- Full-detail side-by-side candidate comparison (weight, price, images, notes, links, status)
-- Impact preview: pick a setup, see +/- weight and cost delta for each candidate
-- Candidate ranking (drag-to-reorder) with pros/cons text fields per candidate
+- External auth provider (self-hosted, open-source) for multi-user registration
+- Migrate from SQLite to Postgres
+- Multi-user data model (user ownership on all entities, public/private visibility)
+- Global item database (seeded from manufacturer data, enrichable by users)
+- Public user profiles with shared setups
+- Structured item reviews (ratings + predefined fields, not freeform text)
+- Discovery feed (browse setups, new items, popular gear)
+- Item detail pages with aggregated specs, owner count, setup appearances
 
 ### Future
 
-- [ ] CSV import/export for gear collections
-- [ ] Multi-user accounts with authentication
-- [ ] Collection sharing and social features (public profiles, shared setups)
-- [ ] Auto-fill product information (price, weight, images) from external sources
+- [ ] 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 / product database — requires external database
-- Community gear database — requires moderation, accounts
+- 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 v1.2 with 7,310 LOC TypeScript. Starting v1.3 to enhance thread decision workflow.
-Tech stack: React 19, Hono, Drizzle ORM, SQLite, TanStack Router/Query, Tailwind CSS v4, Lucide React, Recharts, all on Bun.
+Shipped through v1.4 with 11,333 LOC TypeScript across 90 files. Starting v2.0 platform transformation.
+Tech stack: React 19, Hono, Drizzle ORM, SQLite (migrating to Postgres), 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.
-Replaces spreadsheet-based gear tracking workflow.
-121 tests (service-level and route-level integration).
+Existing auth: single-user with cookie sessions + API keys. Will be replaced by external auth provider.
+Existing features: MCP server (19 tools), E2E tests (Playwright), CSV import/export, item comparison, candidate ranking, setup impact preview.
+21 test files (service-level, route-level integration, and E2E).
 
 ## 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
-- **Scope**: Single user with cookie/API key auth
+- **Auth**: External self-hosted provider — no in-house auth maintenance
+- **Database**: Postgres for platform deployment
+- **UGC**: Structured input only (ratings, predefined fields) — no freeform text until moderation exists
+- **Scope**: Multi-user platform with public discovery
 
 ## Key Decisions
 
@@ -105,6 +118,12 @@ Replaces spreadsheet-based gear tracking workflow.
 | 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 | — Pending |
+| External auth provider | Avoid in-house auth security burden, self-hosted + open-source | — Pending |
+| SQLite → Postgres | Multi-user platform needs proper concurrent DB; auth provider needs Postgres anyway | — Pending |
+| Single-user mode diverges at v2.0 | Platform features irrelevant for solo use; maintain as separate artifact if needed | — Pending |
+| Structured UGC only (no freeform) | Minimize moderation burden; ratings + predefined fields cover 80% of value | — Pending |
+| Discovery-first, not social-first | Users come to research gear decisions, not to build social graphs | — Pending |
 | 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 |
@@ -115,5 +134,22 @@ Replaces spreadsheet-based gear tracking workflow.
 | 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-03-16 after v1.3 milestone start*
+*Last updated: 2026-04-03 after v2.0 milestone start*