208 lines
15 KiB
Markdown
208 lines
15 KiB
Markdown
# 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 market-aware pricing helps users make informed purchase decisions. Multi-user with granular setup sharing (private/link/public), multi-currency support, and a fully internationalized UI (English + German).
|
|
|
|
## 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 Milestone: v2.4 Admin Foundation
|
|
|
|
**Goal:** Clear the v2.3 bug backlog and ship a catalog admin panel as the foundation for managing global catalog content in future milestones.
|
|
|
|
**Target features:**
|
|
- Bug fixes: wrong add-candidate modal, missing item images on collection overview, slow image loading, auth prompt direct Logto redirect, cursor-pointer on all clickable elements
|
|
- Catalog admin panel: admin-gated route, global item management (browse/edit/delete), tag management (create/rename/parent-child hierarchy/delete), admin role flag on users
|
|
|
|
## 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
|
|
- ✓ Catalog attribution fields (sourceUrl, imageCredit, imageSourceUrl) on global items — v2.1
|
|
- ✓ Unique constraint on (brand, model) preventing catalog duplicates — v2.1
|
|
- ✓ Bulk import API with upsert semantics for catalog enrichment — v2.1
|
|
- ✓ MCP catalog tools (upsert_catalog_item, bulk_upsert_catalog) for agent seeding — v2.1
|
|
- ✓ Discovery landing page with catalog search, popular setups feed, recent items, trending categories — v2.1
|
|
|
|
- ✓ Profile page with Logto-powered account management (display name, bio, avatar, email, password, delete) — v2.2
|
|
- ✓ Image fit-within framing with dominant color background fill and crop editor — v2.2
|
|
- ✓ Catalog-driven onboarding flow with hobby picker, category-grouped item browser, and batch collection creation — v2.2
|
|
- ✓ Mobile icon-based action buttons on detail pages — v2.2
|
|
|
|
- ✓ Setup visibility toggle (private/link/public) with shares table, 128-bit token entropy, deactivate/reactivate on transition — v2.3
|
|
- ✓ ShareModal with Google Docs-style UX: visibility picker, link creation/expiry, revoke, deactivation warning — v2.3
|
|
- ✓ Shared setup viewer: `/s/:token` short URL, read-only mode, inline "Shared setup" banner — v2.3
|
|
- ✓ Multi-currency support: market_prices + community_prices tables, ECB exchange rates (24h cache), conversion service — v2.3
|
|
- ✓ Community price aggregation: ownership-validated submissions, median with 3-report minimum, market-aware MSRP on catalog detail — v2.3
|
|
- ✓ i18n foundation: react-i18next, 7 namespaces, English + German translations, language picker, locale-aware formatting — v2.3
|
|
|
|
### Active (v2.4)
|
|
|
|
- [ ] Fix wrong modal on Add Candidate button (thread page) — v2.4
|
|
- [ ] Fix item images not showing on collection overview — v2.4
|
|
- [ ] Resolve slow image loading — v2.4
|
|
- [ ] Auth prompt sign-in redirects directly to Logto — v2.4
|
|
- [ ] Cursor pointer on all clickable/interactive elements — v2.4
|
|
- [ ] Admin role flag on users table — v2.4
|
|
- [ ] Admin-gated /admin panel route — v2.4
|
|
- [ ] Admin: browse/edit/delete global catalog items — v2.4
|
|
- [ ] Admin: create/rename/delete tags with parent-child hierarchy — v2.4
|
|
|
|
### Future
|
|
|
|
- [ ] Tag-based spec schemas on global items (key/value typed specs per category, sub-tag hierarchy) — v2.5
|
|
- [ ] Global item engagement stats (view count, likes/saves, setup appearances) — v2.5
|
|
- [ ] Freeform reviews with moderation system
|
|
- [ ] Comments on setups
|
|
- [ ] Follow users / activity feeds
|
|
- [ ] OAuth / social login providers
|
|
- [ ] User-to-user messaging
|
|
- [ ] ComparisonTable currency normalization (hooks available, needs real multi-currency test data)
|
|
|
|
### 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.3 with 34 phases across 7 milestones. All milestones v1.0-v2.3 complete.
|
|
Tech stack: React 19, Hono, Drizzle ORM, PostgreSQL, TanStack Router/Query, Tailwind CSS v4, Lucide React, Recharts, framer-motion, react-i18next, 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 (21 tools), global item catalog with attribution/bulk import/market prices, user profiles with Logto account management, granular setup sharing (private/link/public) with share tokens, multi-currency pricing (USD/EUR/GBP) with ECB rates and community aggregation, i18n (English + German, 7 namespaces), catalog-driven onboarding, fit-within image framing with crop editor, item/candidate detail pages, candidate ranking/comparison/impact preview. Public discovery landing page with catalog search, popular setups feed, recent items, and trending categories. Top nav + mobile bottom tab bar.
|
|
20+ 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**: Top nav bar (desktop) + bottom tab bar (mobile), discovery landing page for unauthenticated users
|
|
- **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 |
|
|
| visibility text column (not boolean) | Future-proofs for additional sharing modes, readable in queries | ✓ Good |
|
|
| shares table separate from setups | Enables future per-person shares, write permissions, and revocation | ✓ Good |
|
|
| 128-bit base64url share tokens | URL-safe, sufficient entropy, no external dep | ✓ Good |
|
|
| Deactivate/reactivate on visibility change | Share links survive visibility round-trips, not destroyed | ✓ Good |
|
|
| EUR default price currency | Matches existing data assumption from early single-user era | ✓ Good |
|
|
| Module-level ECB rate cache | Simple, single-process, avoids DB or Redis for rate storage | ✓ Good |
|
|
| Community price median with 3-report floor | Prevents manipulation from single-user submissions | ✓ Good |
|
|
| i18next namespace-per-feature | Matches TanStack Router file-based routing, lazy-loadable | ✓ Good |
|
|
| localStorage language key (gearbox-language) | User preference wins over browser default in detection order | ✓ 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-19 after v2.4 milestone start — Admin Foundation*
|