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>
96 lines
7.3 KiB
Markdown
96 lines
7.3 KiB
Markdown
# 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 and `BACKLOG.md` are 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).
|