Jean-Luc Makiola
0202d0bb5c
Summarize current v2.4 state and forward-looking backlog in docs/ as a parallel entry point to the active .planning/ GSD workspace. Lets superpowers skills (brainstorming → writing-plans → executing-plans) work from a clean starting point without retiring the existing workflow. Also ignore .idea/ so JetBrains project files stay local. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
7.3 KiB
GearBox — Project State
Snapshot: 2026-04-23. Migrated from .planning/ (PROJECT.md, ROADMAP.md, STATE.md, REQUIREMENTS.md).
What GearBox Is
A gear management and discovery platform. Users catalog their gear (bikepacking, sim racing, any hobby), track weight, price, and source details, research purchases via planning threads with side-by-side comparison, and compose named setups (loadouts) with weight classification. A global item database with crowd-verified specs, market-aware pricing, and manufacturer attribution helps users make informed purchase decisions.
Multi-user, public-read, authenticated-write. Granular setup sharing (private / link / public), multi-currency (USD/EUR/GBP) with ECB rates, i18n (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.
Where We Are
- Current milestone: v2.4 Admin Foundation — executing (Phases 35–38 all complete, pending final verification)
- Latest activity: 2026-04-20 — quick task
260420-vk0(image fetch-from-URL, crop, tag routing, tag-form UX fixes) - Position in GSD tracker: "stopped at Completed 38-02-PLAN.md — admin tag management client UI"
- Legacy planning data:
.planning/remains the live GSD workspace. This doc andBACKLOG.mdare the superpowers-friendly summary.
Shipped (v1.0 → v2.4)
v1.0 MVP — Collection CRUD, images, categories with totals, planning threads, thread resolution, named setups, dashboard, onboarding.
v1.1 Fixes & Polish — Thread creation modal, planning tab, image display polish, Lucide icon picker (119 icons), emoji→icon migration.
v1.2 Collection Power-Ups — Search + category filter, weight units (g/oz/lb/kg), per-setup classification (base/worn/consumable), donut chart, candidate status tracking.
v1.3 Research & Decision Tools — Pros/cons annotation, candidate ranking with drag-reorder, side-by-side comparison with deltas, setup impact preview.
v2.0 Platform Foundation — Postgres migration with PGlite test infra, Logto OIDC auth, multi-user isolation, MinIO/S3 storage, global item catalog, user profiles + public setup sharing, reference-item COALESCE merge, tag system, FAB + catalog search overlay, item/catalog detail pages, add-from-catalog flow.
v2.1 Public Discovery — Public read with rate limiting, catalog attribution + unique (brand, model), bulk import with upsert, MCP catalog tools (upsert_catalog_item, bulk_upsert_catalog), discovery landing page, top-nav + mobile bottom tab bar, Setups elevated to top-level route.
v2.2 User Experience Polish — Profile page with Logto-backed account management (name/bio/avatar/email/password/delete), fit-within image framing with dominant-color background and crop editor, catalog-driven onboarding (hobby picker → category-grouped item browser → batch create), mobile icon-based action buttons on detail pages.
v2.3 Global & Social Ready — Setup visibility (private/link/public) with shares table and 128-bit tokens, ShareModal (Google-Docs-style UX), /s/:token shared-setup viewer, multi-currency (market_prices + community_prices, ECB rates cached 24h), ownership-validated community price aggregation (median, 3-report minimum), react-i18next foundation with 7 namespaces and German translations, language picker.
v2.4 Admin Foundation (in verification) — Phase 35 bug-fix sweep (wrong modal, missing images, slow loading, auth redirect, cursor-pointer audit), isAdmin flag on users + CLI grant/revoke script, gated /admin route with requireAdmin middleware, admin global-item management (browse/edit/delete with search + tag filter), admin tag management (CRUD + parent-child hierarchy with cycle detection). Also during v2.4: manufacturer backend entity (table, FK, service, route, seeding; picker UI still missing), catalog ingestion agent scripts (crawl-manufacturer, crawl-all).
Tech Stack
React 19, Hono, Drizzle ORM, PostgreSQL, TanStack Router/Query, Tailwind CSS v4, Lucide React, Recharts, framer-motion, react-i18next, Sharp (image processing), react-easy-crop — all on Bun. MinIO for S3-compatible image storage. Docker Compose for dev/prod. Logto (self-hosted OIDC) for auth; API keys for programmatic; OAuth 2.1 + PKCE for Claude mobile/web. MCP server exposes 21+ tools over streamable HTTP.
Active Constraints
- Runtime: Bun (package manager + runtime)
- Design: Light, airy, minimalist — white/light backgrounds, lots of whitespace
- Navigation: Top nav (desktop) + bottom tab bar (mobile); public discovery landing page for unauth users
- Auth: External self-hosted (Logto) — no in-house auth maintenance
- DB: PostgreSQL + Drizzle; prices stored as cents; timestamps as unix epoch integers
- UGC: Structured input only (ratings, predefined fields) — no freeform until moderation exists
- Scope: Multi-user platform with public discovery; SQLite single-user path diverged at v2.0
Load-Bearing Decisions (current)
| Decision | Rationale |
|---|---|
| External OIDC (Logto) | Avoid in-house auth burden |
| Postgres over SQLite | Multi-user concurrency + provider needs it |
| Structured UGC only (no freeform) | Minimize moderation burden |
| Discovery-first, not social-first | Users come to research decisions |
| COALESCE merge for reference items | Global base + personal overlay, no duplication |
| Catalog-first add with manual fallback | Encourages catalog usage, preserves flexibility |
| Detail pages over slide-out panels | Better UX + shareable URLs |
| Setups as top-level route | Promoted out of Collection tabs (Phase 27) |
visibility text column (not boolean) |
Future-proofs for additional sharing modes |
shares table separate from setups |
Enables per-person shares, write permissions, revocation |
| 128-bit base64url share tokens | URL-safe entropy, no external dep |
| Deactivate/reactivate on visibility change | Share links survive round-trips |
| EUR default currency | Matches early single-user data assumption |
| Module-level ECB rate cache (24h) | Single-process; avoids Redis |
isAdmin boolean flag on users |
Simplest; no Logto role claims needed |
| Admin grant via CLI script | No public UI for privilege escalation |
| Manufacturers as dedicated entity (FK, not text) | Avoids "Ortlieb" vs "ORTLIEB" drift; enables logos/URLs |
Explicitly Out of Scope
- Personalized feed algorithm (needs usage data)
- SSR / static prerendering (TanStack Router research needed; defer)
- Freeform reviews / comments (no moderation infra)
- Image scraping automation (legal gray area)
- User-to-user messaging (moderation burden)
- Wiki-style open item editing (quality risk)
- Marketplace / buy-sell (payment + fraud + legal)
- AI gear recommendations (training data + hallucination)
- Gamification (incentivizes quantity over quality)
- Price tracking / deal alerts (scraping fragility + legal)
- Native mobile app (web-first, responsive; PWA considered — see 999.9)
- Custom comparison parameters (complexity trap; weight/price covers 80%)
- Barcode scanning (poor UX vs catalog search)
- Maintaining SQLite single-user path in parallel (diverged at v2.0)
Next Up
See BACKLOG.md for the forward-looking list (pending todos, unfinished v2.4 verification, backlog phases, deferred requirements).