# Roadmap: GearBox

## Milestones

- ✅ **v1.0 MVP** — Phases 1-3 (shipped 2026-03-15)
- ✅ **v1.1 Fixes & Polish** — Phases 4-6 (shipped 2026-03-15)
- ✅ **v1.2 Collection Power-Ups** — Phases 7-9 (shipped 2026-03-16)
- ✅ **v1.3 Research & Decision Tools** — Phases 10-13 (shipped 2026-04-08)
- ✅ **v2.0 Platform Foundation** — Phases 14-23 (shipped 2026-04-08)
- ✅ **v2.1 Public Discovery** — Phases 24-27 (shipped 2026-04-12)
- 🚧 **v2.2 User Experience Polish** — Phases 28-31 (in progress)
- 📋 **v2.3 Global & Social Ready** — Phases 32-34 (planned)

## Phases

<details>
<summary>✅ v1.0 MVP (Phases 1-3) — SHIPPED 2026-03-15</summary>

- [x] Phase 1: Foundation and Collection (4/4 plans) — completed 2026-03-14
- [x] Phase 2: Planning Threads (3/3 plans) — completed 2026-03-15
- [x] Phase 3: Setups and Dashboard (3/3 plans) — completed 2026-03-15

</details>

<details>
<summary>✅ v1.1 Fixes & Polish (Phases 4-6) — SHIPPED 2026-03-15</summary>

- [x] Phase 4: Database & Planning Fixes (2/2 plans) — completed 2026-03-15
- [x] Phase 5: Image Handling (2/2 plans) — completed 2026-03-15
- [x] Phase 6: Category Icons (3/3 plans) — completed 2026-03-15

</details>

<details>
<summary>✅ v1.2 Collection Power-Ups (Phases 7-9) — SHIPPED 2026-03-16</summary>

- [x] Phase 7: Weight Unit Selection (2/2 plans) — completed 2026-03-16
- [x] Phase 8: Search, Filter, and Candidate Status (2/2 plans) — completed 2026-03-16
- [x] Phase 9: Weight Classification and Visualization (2/2 plans) — completed 2026-03-16

</details>

<details>
<summary>✅ v1.3 Research & Decision Tools (Phases 10-13) — SHIPPED 2026-04-08</summary>

- [x] Phase 10: Schema Foundation + Pros/Cons Fields (1/1 plans) — completed 2026-03-16
- [x] Phase 11: Candidate Ranking (2/2 plans) — completed 2026-03-16
- [x] Phase 12: Comparison View (1/1 plans) — completed 2026-03-17
- [x] Phase 13: Setup Impact Preview (2/2 plans) — completed 2026-04-08

</details>

<details>
<summary>✅ v2.0 Platform Foundation (Phases 14-23) — SHIPPED 2026-04-08</summary>

- [x] Phase 14: PostgreSQL Migration (6/6 plans) — completed 2026-04-05
- [x] Phase 15: External Authentication (3/3 plans) — completed 2026-04-05
- [x] Phase 16: Multi-User Data Model (4/4 plans) — completed 2026-04-05
- [x] Phase 17: Object Storage (3/3 plans) — completed 2026-04-05
- [x] Phase 18: Global Items & Public Profiles (5/5 plans) — completed 2026-04-05
- [x] Phase 19: Reference Item Model & Tags Schema (3/3 plans) — completed 2026-04-05
- [x] Phase 20: FAB & Full-Screen Catalog Search (2/2 plans) — completed 2026-04-06
- [x] Phase 21: Item & Catalog Detail Pages (3/3 plans) — completed 2026-04-06
- [x] Phase 22: Add-from-Catalog & Thread Integration (2/2 plans) — completed 2026-04-06
- [x] Phase 23: Manual Entry Fallback (1/1 plans) — completed 2026-04-06

</details>

<details>
<summary>✅ v2.1 Public Discovery (Phases 24-27) — SHIPPED 2026-04-12</summary>

- [x] Phase 24: Public Access & Infrastructure (2/2 plans) — completed 2026-04-10
- [x] Phase 25: Catalog Enrichment & Agent Tools (2/2 plans) — completed 2026-04-10
- [x] Phase 26: Discovery Landing Page (3/3 plans) — completed 2026-04-10
- [x] Phase 27: Top Nav Restructure & Search Bar Rethink (4/4 plans) — completed 2026-04-12

</details>

### v2.2 User Experience Polish (In Progress)

**Milestone Goal:** Fix broken user-facing features and polish the experience for real users — working profiles, better image handling, refreshed onboarding, and mobile refinements.

- [x] **Phase 28: Profile & Logto Integration** — Fix profile page, integrate Logto for profile management, customize login branding, configure email verification (completed 2026-04-12)
- [x] **Phase 29: Image Presentation** — Fit-within framing with letterbox/pillarbox instead of hard crops, optional crop positioning (completed 2026-04-12)
- [x] **Phase 30: Onboarding Redesign** — Catalog-driven onboarding replacing manual entry, visual refresh to match current UI (promotes 999.2) (completed 2026-04-12)
- [x] **Phase 31: Mobile Polish** — Icon-based action buttons on item views, small UX improvements (completed 2026-04-12)

### v2.3 Global & Social Ready (Planned)

**Milestone Goal:** Make GearBox work for a global audience with setup sharing, multi-currency support, and localization infrastructure.

- [ ] **Phase 32: Setup Sharing System** — Visibility toggle (private/link/public), link sharing, schema future-proofed for likes, friends, and collaborative editing
- [ ] **Phase 33: Currency System** — Multi-currency support (USD/EUR/GBP), price display per user preference
- [ ] **Phase 34: i18n Foundation** — Translation framework, string extraction, locale-aware formatting

## Phase Details

### Phase 24: Public Access & Infrastructure
**Goal**: Anyone can browse the catalog, public setups, and user profiles without logging in
**Depends on**: Phase 23 (v2.0 complete)
**Requirements**: PUBL-01, PUBL-02, PUBL-03, PUBL-04, PUBL-05, INFR-01
**Success Criteria** (what must be TRUE):
  1. Visiting the app without a session shows the app content immediately — no auth spinner, no redirect to login
  2. An unauthenticated visitor can browse the global item catalog and open a catalog detail page
  3. An unauthenticated visitor can view a public setup and see its items and totals
  4. An unauthenticated visitor can view a user's public profile page
  5. Attempting to create, edit, or delete any item/setup/thread while unauthenticated redirects to login
**Plans**: 2 plans

Plans:
- [x] 24-01-PLAN.md — Rate limit factory and tiered public endpoint protection
- [x] 24-02-PLAN.md — Client-side public access (render-first root, auth prompt, setup/catalog guards)

**UI hint**: yes

### Phase 25: Catalog Enrichment & Agent Tools
**Goal**: Global items carry attribution metadata and can be bulk-populated by an MCP agent swarm
**Depends on**: Phase 24
**Requirements**: CATL-01, CATL-02, CATL-03, CATL-04, CATL-05, SEED-01, SEED-02, SEED-03
**Success Criteria** (what must be TRUE):
  1. A catalog item detail page displays image credit and a link to the image source
  2. Attempting to import two items with the same brand and model updates the existing record rather than creating a duplicate
  3. A single API call with an array of items imports them all, upserting on (brand, model) conflict
  4. An MCP agent can call `upsert_catalog_item` with attribution fields and the item appears in the catalog
  5. An MCP agent can call `bulk_upsert_catalog` with a batch of items and all are persisted with attribution
**Plans**: 2 plans

Plans:
- [x] 25-01-PLAN.md — Schema migration (attribution columns + unique constraint) and upsert service layer
- [ ] 25-02-PLAN.md — HTTP upsert routes, MCP catalog tools, and client attribution display

### Phase 26: Discovery Landing Page
**Goal**: The app opens to a public discovery feed with prominent catalog search, not a personal dashboard
**Depends on**: Phase 25
**Requirements**: DISC-01, DISC-02, DISC-03, DISC-04, DISC-05, INFR-02
**Success Criteria** (what must be TRUE):
  1. The root URL shows a landing page with a catalog search bar at the top, visible without logging in
  2. Below the search bar, a feed of popular public setups is visible with titles, creator names, and item counts
  3. The landing page shows a section of recently added catalog items
  4. The landing page shows a section of trending categories
  5. A logged-in user sees a "Go to Collection" link or button on the landing page that navigates to their personal collection
**Plans**: 3 plans

Plans:
- [x] 26-01-PLAN.md — Discovery service layer with cursor pagination (TDD)
- [x] 26-02-PLAN.md — Discovery routes, server registration, and client hooks
- [x] 26-03-PLAN.md — Landing page UI and PublicSetupCard enhancement
**UI hint**: yes

### Phase 27: Top Nav Restructure & Search Bar Rethink
**Goal**: Replace the minimal TotalsBar with a persistent top navigation bar (logo, section links, catalog search, user avatar) and move mobile navigation to a bottom tab bar — elevating Setups to top-level and removing the landing page hero
**Depends on**: Phase 26
**Requirements**: NAV-01, NAV-02, NAV-03, NAV-04, NAV-05
**Success Criteria** (what must be TRUE):
  1. A persistent top nav bar shows logo, Home/Collection/Setups links, catalog search, and user avatar on desktop
  2. Clicking Collection or Setups while anonymous triggers AuthPromptModal instead of navigating
  3. On mobile, navigation appears as a fixed bottom tab bar with Home, Collection, Setups, and Search icons
  4. The landing page no longer has a hero section — content starts with Popular Setups
  5. Setups has its own top-level route accessible from the nav bar, not nested in Collection tabs
**Plans**: 4 plans

Plans:
- [x] 27-00-PLAN.md — Wave 0: E2E test scaffolding for nav restructure
- [x] 27-01-PLAN.md — TopNav and BottomTabBar components
- [x] 27-02-PLAN.md — Setups top-level route and Collection tab simplification
- [x] 27-03-PLAN.md — Root layout wiring, hero removal, and visual verification
**UI hint**: yes

### Phase 28: Profile & Logto Integration
**Goal**: Users have a working profile page with account management powered by Logto, branded login screens, and email verification
**Depends on**: Phase 27 (v2.1 complete)
**Requirements**: TBD (discuss phase)
**Success Criteria** (what must be TRUE):
  TBD (discuss phase)
**Plans**: TBD

### Phase 29: Image Presentation
**Goal**: Images display within the fixed aspect ratio using fit-within framing (letterbox/pillarbox) instead of hard crops, preserving the full image
**Depends on**: Phase 28
**Requirements**: TBD (discuss phase)
**Success Criteria** (what must be TRUE):
  TBD (discuss phase)
**Plans**: TBD

### Phase 30: Onboarding Redesign
**Goal**: New users experience a polished, catalog-driven onboarding flow that matches the current UI style and guides them through their first setup
**Depends on**: Phase 28
**Requirements**: TBD (discuss phase)
**Success Criteria** (what must be TRUE):
  TBD (discuss phase)
**Plans**: TBD
**UI hint**: yes

### Phase 31: Mobile Polish
**Goal**: Mobile item views use icon-based action buttons instead of text labels, with small UX refinements across touch interactions
**Depends on**: None
**Requirements**: TBD (discuss phase)
**Success Criteria** (what must be TRUE):
  TBD (discuss phase)
**Plans**: TBD
**UI hint**: yes

### Phase 32: Setup Sharing System
**Goal**: Setup owners can toggle visibility between private, link-shared, and public, with schema designed for future likes, friends, and collaborative editing
**Depends on**: Phase 28 (profiles working)
**Requirements**: TBD (discuss phase)
**Success Criteria** (what must be TRUE):
  TBD (discuss phase)
**Plans**: TBD
**UI hint**: yes

### Phase 33: Currency System
**Goal**: Users can select their preferred currency (USD/EUR/GBP) and all prices display accordingly
**Depends on**: Phase 32
**Requirements**: TBD (discuss phase)
**Success Criteria** (what must be TRUE):
  TBD (discuss phase)
**Plans**: TBD

### Phase 34: i18n Foundation
**Goal**: Translation framework in place with string extraction, locale-aware formatting, and at least English + one additional language
**Depends on**: Phase 33
**Requirements**: TBD (discuss phase)
**Success Criteria** (what must be TRUE):
  TBD (discuss phase)
**Plans**: TBD

## Progress

| Phase | Milestone | Plans Complete | Status | Completed |
|-------|-----------|----------------|--------|-----------|
| 1. Foundation and Collection | v1.0 | 4/4 | Complete | 2026-03-14 |
| 2. Planning Threads | v1.0 | 3/3 | Complete | 2026-03-15 |
| 3. Setups and Dashboard | v1.0 | 3/3 | Complete | 2026-03-15 |
| 4. Database & Planning Fixes | v1.1 | 2/2 | Complete | 2026-03-15 |
| 5. Image Handling | v1.1 | 2/2 | Complete | 2026-03-15 |
| 6. Category Icons | v1.1 | 3/3 | Complete | 2026-03-15 |
| 7. Weight Unit Selection | v1.2 | 2/2 | Complete | 2026-03-16 |
| 8. Search, Filter, and Candidate Status | v1.2 | 2/2 | Complete | 2026-03-16 |
| 9. Weight Classification and Visualization | v1.2 | 2/2 | Complete | 2026-03-16 |
| 10. Schema Foundation + Pros/Cons Fields | v1.3 | 1/1 | Complete | 2026-03-16 |
| 11. Candidate Ranking | v1.3 | 2/2 | Complete | 2026-03-16 |
| 12. Comparison View | v1.3 | 1/1 | Complete | 2026-03-17 |
| 13. Setup Impact Preview | v1.3 | 2/2 | Complete | 2026-04-08 |
| 14. PostgreSQL Migration | v2.0 | 6/6 | Complete | 2026-04-05 |
| 15. External Authentication | v2.0 | 3/3 | Complete | 2026-04-05 |
| 16. Multi-User Data Model | v2.0 | 4/4 | Complete | 2026-04-05 |
| 17. Object Storage | v2.0 | 3/3 | Complete | 2026-04-05 |
| 18. Global Items & Public Profiles | v2.0 | 5/5 | Complete | 2026-04-05 |
| 19. Reference Item Model & Tags Schema | v2.0 | 3/3 | Complete | 2026-04-05 |
| 20. FAB & Full-Screen Catalog Search | v2.0 | 2/2 | Complete | 2026-04-06 |
| 21. Item & Catalog Detail Pages | v2.0 | 3/3 | Complete | 2026-04-06 |
| 22. Add-from-Catalog & Thread Integration | v2.0 | 2/2 | Complete | 2026-04-06 |
| 23. Manual Entry Fallback | v2.0 | 1/1 | Complete | 2026-04-06 |
| 24. Public Access & Infrastructure | v2.1 | 2/2 | Complete | 2026-04-10 |
| 25. Catalog Enrichment & Agent Tools | v2.1 | 2/2 | Complete | 2026-04-10 |
| 26. Discovery Landing Page | v2.1 | 3/3 | Complete | 2026-04-10 |
| 27. Top Nav Restructure & Search Bar Rethink | v2.1 | 4/4 | Complete | 2026-04-12 |
| 28. Profile & Logto Integration | v2.2 | 3/3 | Complete    | 2026-04-12 |
| 29. Image Presentation | v2.2 | 4/4 | Complete    | 2026-04-12 |
| 30. Onboarding Redesign | v2.2 | 3/3 | Complete    | 2026-04-12 |
| 31. Mobile Polish | v2.2 | 2/2 | Complete    | 2026-04-12 |
| 32. Setup Sharing System | v2.3 | TBD | Pending | — |
| 33. Currency System | v2.3 | TBD | Pending | — |
| 34. i18n Foundation | v2.3 | TBD | Pending | — |

## Backlog

### Phase 999.1: Rewrite E2E Tests for OIDC Auth (BACKLOG)
**Goal**: E2E tests currently expect local username/password login but auth moved to external OIDC (Logto). Rewrite with mock OIDC provider or API-key-based auth bypass. Seed migration to Postgres is already done.
**Requirements**: TBD
**Plans**: TBD

Plans:
- [ ] TBD (promote with /gsd:review-backlog when ready)

### Phase 999.2: Revamp Onboarding Flow (BACKLOG)
**Goal**: Redesign the onboarding experience to match the current app style and flow. Replace the manual item edit form with the catalog search function. Visual refresh to align with the newer UI patterns.
**Status**: Promoted to Phase 30 (v2.2)
**Requirements**: TBD
**Plans**: TBD

Plans:
- [ ] TBD (promote with /gsd:review-backlog when ready)

### Phase 999.5: Legal Pages — ToS, Privacy Policy, and Compliance (BACKLOG)
**Goal**: Create Terms of Service, Privacy Policy, and any other required legal/compliance pages for a public-facing platform. Essential before opening to real users.
**Requirements**: TBD
**Plans**: TBD

Plans:
- [ ] TBD (promote with /gsd:review-backlog when ready)

### Phase 999.6: Admin Panel (BACKLOG)
**Goal**: Build an admin panel for reviewing user-submitted items (catalog submissions), managing global/reference items, and general platform administration. Includes approval workflows for community contributions.
**Requirements**: TBD
**Plans**: TBD

Plans:
- [ ] TBD (promote with /gsd:review-backlog when ready)

### Phase 999.7: User Feedback System (BACKLOG)
**Goal**: Add an in-app feedback collection mechanism so users can report bugs, suggest features, and share general feedback. Could be a simple form, widget, or integration with an external tool.
**Requirements**: TBD
**Plans**: TBD

Plans:
- [ ] TBD (promote with /gsd:review-backlog when ready)

### Phase 999.8: Analytics Integration (BACKLOG)
**Goal**: Integrate privacy-respecting analytics (PostHog, Umami, or similar) to understand usage patterns, popular categories, search behavior, and feature adoption. Self-hosted preferred to align with independent ethos.
**Requirements**: TBD
**Plans**: TBD

Plans:
- [ ] TBD (promote with /gsd:review-backlog when ready)

### Phase 999.9: Mobile App (BACKLOG)
**Goal**: Bring GearBox to mobile. Start with a PWA for quick wins (offline support, home screen install), then evaluate dedicated native apps (React Native / Flutter) for richer experience — camera for weight verification, barcode scanning, etc.
**Requirements**: TBD
**Plans**: TBD

Plans:
- [ ] TBD (promote with /gsd:review-backlog when ready)

### Phase 999.10: Monetization Strategy (BACKLOG)
**Goal**: Define how GearBox sustains itself financially. Options to explore: sponsored/promoted items (brand X promotes product Y), premium features, affiliate links. Critical tension: revenue vs. independent credibility — GearBox's value is unbiased gear data, so monetization must not compromise trust. Needs deep discussion before implementation.
**Requirements**: TBD
**Plans**: TBD

Plans:
- [ ] TBD (promote with /gsd:review-backlog when ready)

### Phase 999.11: Marketing Website (BACKLOG)
**Goal**: Build a separate marketing/brand website (www.gearbox.de) distinct from the app (app.gearbox.de). Hero section with search bar, value proposition, feature highlights, how-it-works, social proof, and sign-up CTA. This is the public-facing front door — the first thing people see before they enter the app. The current discovery page is the in-app experience; this is the standalone website around it.
**Requirements**: TBD
**Plans**: TBD

Plans:
- [ ] TBD (promote with /gsd:review-backlog when ready)
