docs: add superpowers-friendly state and backlog summary
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>
This commit is contained in:
3
.gitignore
vendored
3
.gitignore
vendored
@@ -233,6 +233,9 @@ e2e/pgdata
|
||||
test-results/
|
||||
playwright-report/
|
||||
|
||||
# JetBrains IDEs (full directory)
|
||||
.idea/
|
||||
|
||||
# Obsidian
|
||||
.obsidian/
|
||||
|
||||
|
||||
115
docs/BACKLOG.md
Normal file
115
docs/BACKLOG.md
Normal file
@@ -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-<name>.md`.
|
||||
5. Execute with `superpowers:subagent-driven-development` (recommended) or `superpowers:executing-plans`.
|
||||
6. Remove the item from this doc when shipped.
|
||||
95
docs/STATE.md
Normal file
95
docs/STATE.md
Normal file
@@ -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).
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user