docs: start milestone v2.0 Platform Foundation
This commit is contained in:
@@ -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*
|
||||
|
||||
@@ -1,16 +1,16 @@
|
||||
---
|
||||
gsd_state_version: 1.0
|
||||
milestone: v1.3
|
||||
milestone_name: Research & Decision Tools
|
||||
milestone: v2.0
|
||||
milestone_name: Platform Foundation
|
||||
status: planning
|
||||
stopped_at: Completed 12-comparison-view/12-01-PLAN.md
|
||||
last_updated: "2026-03-17T14:35:39.075Z"
|
||||
last_activity: 2026-03-16 — Roadmap created for v1.3 milestone
|
||||
stopped_at: null
|
||||
last_updated: "2026-04-03"
|
||||
last_activity: 2026-04-03 — Milestone v2.0 started
|
||||
progress:
|
||||
total_phases: 4
|
||||
completed_phases: 3
|
||||
total_plans: 4
|
||||
completed_plans: 4
|
||||
total_phases: 0
|
||||
completed_phases: 0
|
||||
total_plans: 0
|
||||
completed_plans: 0
|
||||
percent: 0
|
||||
---
|
||||
|
||||
@@ -18,19 +18,17 @@ progress:
|
||||
|
||||
## Project Reference
|
||||
|
||||
See: .planning/PROJECT.md (updated 2026-03-16)
|
||||
See: .planning/PROJECT.md (updated 2026-04-03)
|
||||
|
||||
**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.
|
||||
**Current focus:** v1.3 Research & Decision Tools — Phase 10 ready to plan
|
||||
**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.
|
||||
**Current focus:** v2.0 Platform Foundation — Defining requirements
|
||||
|
||||
## Current Position
|
||||
|
||||
Phase: 10 of 13 (Schema Foundation + Pros/Cons Fields)
|
||||
Phase: Not started (defining requirements)
|
||||
Plan: —
|
||||
Status: Ready to plan
|
||||
Last activity: 2026-03-16 — Roadmap created for v1.3 milestone
|
||||
|
||||
Progress: [░░░░░░░░░░] 0%
|
||||
Status: Defining requirements
|
||||
Last activity: 2026-04-03 — Milestone v2.0 started
|
||||
|
||||
## Performance Metrics
|
||||
|
||||
@@ -39,43 +37,19 @@ Progress: [░░░░░░░░░░] 0%
|
||||
- Average duration: —
|
||||
- Total execution time: —
|
||||
|
||||
**By Phase:**
|
||||
|
||||
| Phase | Plans | Total | Avg/Plan |
|
||||
|-------|-------|-------|----------|
|
||||
| - | - | - | - |
|
||||
|
||||
**Recent Trend:**
|
||||
- Last 5 plans: —
|
||||
- Trend: —
|
||||
|
||||
*Updated after each plan completion*
|
||||
| Phase 10-schema-foundation-pros-cons-fields P01 | 6min | 2 tasks | 9 files |
|
||||
| Phase 11-candidate-ranking P01 | 4min | 2 tasks | 8 files |
|
||||
| Phase 11-candidate-ranking P02 | 4min | 3 tasks | 7 files |
|
||||
| Phase 12-comparison-view P01 | 2min | 2 tasks | 3 files |
|
||||
|
||||
## Accumulated Context
|
||||
|
||||
### Decisions
|
||||
|
||||
Cleared at milestone boundary. v1.2 decisions archived in milestones/v1.2-ROADMAP.md.
|
||||
|
||||
Key v1.3 research findings (see research/SUMMARY.md):
|
||||
- framer-motion@12.37.0 (already installed) handles drag-to-reorder via Reorder component — no new deps
|
||||
- sort_order must use REAL (float) type, not INTEGER, to avoid bulk writes on every drag
|
||||
- Impact preview must distinguish add-mode vs replace-mode by category match — pure addition misleads
|
||||
- [Phase 10-schema-foundation-pros-cons-fields]: Empty string for pros/cons stored as-is (not normalized to null); test accepts either empty string or null as cleared state
|
||||
- [Phase 10-schema-foundation-pros-cons-fields]: Pros/Cons badge uses purple color to distinguish from weight (blue), price (green), category (gray), and status badges
|
||||
- [Phase 10-schema-foundation-pros-cons-fields]: Field-addition ladder pattern: schema -> migration -> test helper -> service -> Zod -> types -> hook -> form -> card indicator
|
||||
- [Phase 11-candidate-ranking]: sortOrder uses REAL type for future fractional midpoint insertions without bulk rewrites
|
||||
- [Phase 11-candidate-ranking]: 1000-gap sort_order strategy: first=1000, append=max+1000, reorder resets to (index+1)*1000
|
||||
- [Phase 11-candidate-ranking]: Applied sort_order migration via sqlite3 CLI directly to avoid Drizzle data-loss warning on existing rows
|
||||
- [Phase 11-candidate-ranking]: Resolved thread list view uses plain div (not Reorder.Group) — no drag, rank badges visible
|
||||
- [Phase 11-candidate-ranking]: RankBadge exported from CandidateListItem for reuse in CandidateCard grid view
|
||||
- [Phase 12-comparison-view]: ATTRIBUTE_ROWS declarative array pattern for ComparisonTable keeps JSX clean and row reordering trivial
|
||||
- [Phase 12-comparison-view]: Compare toggle only shown for 2+ candidates; Add Candidate hidden in compare view (read-only intent)
|
||||
- [Phase 12-comparison-view]: Weight/price highlight color takes priority over amber winner tint when both apply (more informative)
|
||||
Key decisions made during v2.0 planning:
|
||||
- Platform pivot: single-user → multi-user with discovery-first approach
|
||||
- External auth provider (self-hosted, open-source) — avoid in-house auth burden
|
||||
- SQLite → Postgres migration — multi-user concurrency + auth provider dependency
|
||||
- Structured UGC only — ratings and predefined fields, no freeform text until moderation exists
|
||||
- Global item database seeded from manufacturer data, enriched by user contributions
|
||||
- Single-user SQLite mode diverges at v2.0 boundary
|
||||
|
||||
### Pending Todos
|
||||
|
||||
@@ -87,6 +61,6 @@ None active.
|
||||
|
||||
## Session Continuity
|
||||
|
||||
Last session: 2026-03-17T14:32:04.702Z
|
||||
Stopped at: Completed 12-comparison-view/12-01-PLAN.md
|
||||
Last session: 2026-04-03
|
||||
Stopped at: Defining requirements for v2.0
|
||||
Resume file: None
|
||||
|
||||
Reference in New Issue
Block a user