From 0202d0bb5ce19c61ce4554a0ef5a01a45274db04 Mon Sep 17 00:00:00 2001 From: Jean-Luc Makiola Date: Thu, 23 Apr 2026 13:16:15 +0200 Subject: [PATCH] docs: add superpowers-friendly state and backlog summary MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- .gitignore | 3 + docs/BACKLOG.md | 115 ++++++++++++++++++ docs/STATE.md | 95 +++++++++++++++ ...-manufacturer-entity-with-brand-details.md | 18 +++ ...ag-selector-in-global-search-searchable.md | 15 +++ 5 files changed, 246 insertions(+) create mode 100644 docs/BACKLOG.md create mode 100644 docs/STATE.md create mode 100644 docs/backlog/todos/2026-04-10-add-manufacturer-entity-with-brand-details.md create mode 100644 docs/backlog/todos/2026-04-20-make-tag-selector-in-global-search-searchable.md diff --git a/.gitignore b/.gitignore index ed4ba87..cb61b61 100644 --- a/.gitignore +++ b/.gitignore @@ -233,6 +233,9 @@ e2e/pgdata test-results/ playwright-report/ +# JetBrains IDEs (full directory) +.idea/ + # Obsidian .obsidian/ diff --git a/docs/BACKLOG.md b/docs/BACKLOG.md new file mode 100644 index 0000000..b613096 --- /dev/null +++ b/docs/BACKLOG.md @@ -0,0 +1,115 @@ +# GearBox — Backlog + +*Migrated from `.planning/` on 2026-04-23. Forward-looking only — see `STATE.md` for what's shipped.* + +Staging area for work not yet brainstormed into a superpowers plan. To start on anything here, run `superpowers:brainstorming` → `superpowers:writing-plans` → `superpowers:subagent-driven-development` (or `executing-plans`). + +--- + +## v2.4 tail — finish line + +- [ ] **Verify Phase 38 Admin Tag Management** — all 2 plans marked complete in roadmap, STATE.md says 97%. Run the phase verification and close out v2.4. +- [ ] **Manufacturer picker UI** — backend entity is shipped (`manufacturers` table, service, route, FK on `globalItems`, seeding), but the user-facing picker component (analogous to `CategoryPicker`) is not yet built. The manual add form still takes freeform brand text in places. See also the pending todo below. + +--- + +## Pending todos + +Details preserved in `docs/backlog/todos/`. Only truly-open items listed here — the older v2.3 todos (wrong modal, missing images, slow loading, auth redirect, cursor pointer) all shipped in Phase 35. + +- [ ] **Make tag selector in global search searchable** (2026-04-20, ui) — the tag selector inside `CatalogSearchOverlay.tsx` should support typing-to-filter. Currently scrollable only. +- [ ] **Add manufacturer picker UI** (from 2026-04-10 "add-manufacturer-entity" todo) — backend shipped; picker component + wiring into the manual add form and catalog enrichment is the remaining slice. + +**Dropped** (already resolved but stale in `.planning/todos/pending/`): +- `add-cursor-pointer-to-all-clickable-links` → shipped in Phase 35 (FIX-05) +- `fix-item-image-not-showing-on-collection-overview` → shipped in Phase 35 (FIX-02) +- `fix-storage-service-tests` → resolved; `withImageUrl`/`withImageUrls` both exported and test imports match +- `investigate-slow-image-loading` → shipped in Phase 35 (FIX-03, lazy loading + skeletons) +- `auth-prompt-sign-in-button-should-redirect-directly-to-logto` → shipped in Phase 35 (FIX-04) +- `fix-add-candidate-button-shows-wrong-modal-on-thread-page` → shipped in Phase 35 (FIX-01) + +--- + +## Backlog phases (pre-brainstorm) + +These are product intents, not plans. Each needs brainstorming before becoming a superpowers plan. Sourced from `.planning/ROADMAP.md` Backlog section. *Previously-listed entries 999.2, 999.3, 999.4, 999.6 were promoted to shipped phases and are omitted here.* + +### 999.1 — Rewrite E2E Tests for OIDC Auth +E2E tests expect local username/password login, but auth moved to Logto. Rewrite with a mock OIDC provider or API-key bypass. Postgres seed migration already done. + +### 999.5 — Legal Pages: ToS, Privacy Policy, Compliance +Terms of Service, Privacy Policy, and any required compliance pages. Essential before opening to real users. + +### 999.7 — User Feedback System +In-app feedback collection — bug reports, feature requests, general feedback. Simple form, widget, or external integration. + +### 999.8 — Analytics Integration +Privacy-respecting analytics (PostHog, Umami, or similar). Usage patterns, popular categories, search behavior, feature adoption. Self-hosted preferred to align with independent ethos. + +### 999.9 — Mobile App +PWA first (offline, home-screen install), then evaluate native (React Native / Flutter) for richer experience — camera for weight verification, barcode scanning, etc. + +### 999.10 — Monetization Strategy +How GearBox sustains itself. Options: sponsored/promoted items, premium features, affiliate links. Critical tension: revenue vs. credibility — GearBox's value is *unbiased* gear data. Needs deep discussion before implementation. + +### 999.11 — Marketing Website +Standalone marketing site (`www.gearbox.de`) separate from the app (`app.gearbox.de`). Hero, value prop, feature highlights, how-it-works, social proof, sign-up CTA. The public-facing front door. + +### 999.12 — Admin UX Polish (new, 2026-04-20) +Overhaul admin panel UX: TanStack Table (sortable/groupable columns), cmdk for GitLab-style composable filter bar (field→operator→value token input), hide FAB on `/admin/*`, replace tag inline form with popup modal, show tags expanded on item rows (collapse to +N when tight), group items by brand, prominent search bar on both admin list pages. + +--- + +## Near-future scope (v2.5 candidates) + +Explicitly planned for the next milestone but not yet a phase: + +- **Tag-based spec schemas on global items** — key/value typed specs per category, sub-tag hierarchy. Enables proper structured product data per gear class. +- **Global item engagement stats** — view count, likes/saves, setup appearances. Feeds future sorting/ranking. +- **ComparisonTable currency normalization** — hooks are in place; needs real multi-currency test data to prove out. + +--- + +## Deferred requirements (tracked, not scheduled) + +Not in any current or v2.5 phase. Promote to a backlog phase when timing is right. + +### Personalization +- **PERS-01** — Logged-in feed tuned to the user's collection categories +- **PERS-02** — Feed algorithm recommends by hobby interests + +### Reviews & Content +- **REVW-01/02/03** — Structured reviews on catalog items; surface in discovery feed; curated/linked external reviews +- **REV-01/02/03** — Overall star rating, dimension ratings (durability, value), average ratings on item detail +- **MOD-01/02/03** — Freeform text reviews, report inappropriate content, admin review + action *(gated on moderation infra)* + +### SEO +- **SEO-01** — Catalog pages crawlable by bots +- **SEO-02** — Meta tags + structured data + +### Catalog Seeding +- **SEED-04** — Initial seeding run populates 100+ items across key categories via agent swarm *(crawl scripts exist — this would be the production run)* + +### Aggregation +- **AGG-01** — Crowd-verified specs on item detail (manufacturer vs community-measured weight) +- **AGG-02** — "Which setups include this item" +- **AGG-03** — "Commonly paired with" setup composition insights + +### Social +- **SOCL-01** — Fork/copy a public setup as template +- **SOCL-02** — Thread candidates auto-populate from global items +- **SOCL-03** — Follow other users +- **SOCL-04** — Activity feed of followed users' content + +--- + +## Workflow + +**To start work on something here:** + +1. Pick an item above. +2. Run `superpowers:brainstorming` to turn the intent into a spec. +3. For non-trivial work, create a feature branch off `Develop` (e.g., `feature/manufacturer-picker`, `fix/tag-selector-search`). +4. Run `superpowers:writing-plans` to produce `docs/superpowers/plans/YYYY-MM-DD-.md`. +5. Execute with `superpowers:subagent-driven-development` (recommended) or `superpowers:executing-plans`. +6. Remove the item from this doc when shipped. diff --git a/docs/STATE.md b/docs/STATE.md new file mode 100644 index 0000000..d3bf3d7 --- /dev/null +++ b/docs/STATE.md @@ -0,0 +1,95 @@ +# 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). diff --git a/docs/backlog/todos/2026-04-10-add-manufacturer-entity-with-brand-details.md b/docs/backlog/todos/2026-04-10-add-manufacturer-entity-with-brand-details.md new file mode 100644 index 0000000..eab03b7 --- /dev/null +++ b/docs/backlog/todos/2026-04-10-add-manufacturer-entity-with-brand-details.md @@ -0,0 +1,18 @@ +--- +created: 2026-04-10T09:23:46.394Z +title: Add manufacturer entity with brand details +area: database +files: + - src/db/schema.ts + - src/server/services/global-item.service.ts +--- + +## Problem + +The manual item adding form doesn't include detailed manufacturer info. Currently `brand` is just a text field on items and globalItems. There's no structured manufacturer data (logo, website, country, description). Users can't select from existing manufacturers — they type freeform text which leads to inconsistencies ("Ortlieb" vs "ORTLIEB" vs "ortlieb"). + +## Solution + +Create a `manufacturers` table with fields: `id`, `name` (unique), `logoUrl`, `websiteUrl`, `country`, `description`, `createdAt`. Add a `manufacturerId` FK on `globalItems` (and potentially `items`). Build a manufacturer picker component (like CategoryPicker) with search and inline create. Update the manual add form and catalog enrichment to use the manufacturer entity. This is a significant feature — likely needs its own phase. + +Note: This would also improve the MCP agent seeding workflow — agents could create manufacturers first, then reference them when creating catalog items. diff --git a/docs/backlog/todos/2026-04-20-make-tag-selector-in-global-search-searchable.md b/docs/backlog/todos/2026-04-20-make-tag-selector-in-global-search-searchable.md new file mode 100644 index 0000000..fd276c5 --- /dev/null +++ b/docs/backlog/todos/2026-04-20-make-tag-selector-in-global-search-searchable.md @@ -0,0 +1,15 @@ +--- +created: 2026-04-20T00:00:00.000Z +title: Make tag selector in global search searchable +area: ui +files: + - src/client/components/CatalogSearchOverlay.tsx +--- + +## Problem + +The tag filter in the global search overlay (`CatalogSearchOverlay.tsx`) displays all tags as chips but provides no search/filter input. When there are many tags, users must scroll through all of them to find the one they want — not ergonomic. + +## Solution + +Add a search input inside the tag filter dropdown/section so users can type to narrow down visible tags before selecting. Similar pattern to how the admin items list (`src/client/routes/admin/items/index.tsx`) handles tag filtering.