# 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).