# 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 (in progress)
- 📋 **v2.0 Platform Foundation** �� Phases 14-23 (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>

### v1.3 Research & Decision Tools (In Progress)

**Milestone Goal:** Give users the tools to actually decide between candidates — compare details side-by-side, see how a pick impacts their setup, and rank/annotate their options.

- [x] **Phase 10: Schema Foundation + Pros/Cons Fields** — Migrate schema and deliver pros/cons annotation UI (completed 2026-03-16)
- [x] **Phase 11: Candidate Ranking** — Drag-to-reorder priority ranking with rank badges (completed 2026-03-16)
- [x] **Phase 12: Comparison View** — Side-by-side tabular comparison with relative deltas (completed 2026-03-17)
- [ ] **Phase 13: Setup Impact Preview** — Per-candidate weight and cost delta against a selected setup

### v2.0 Platform Foundation (Planned)

**Milestone Goal:** Transform GearBox from a single-user gear tracker into a multi-user platform where people discover gear, research purchases using crowd-verified data, and share their setups.

- [ ] **Phase 14: PostgreSQL Migration** — Replace SQLite with Postgres, make all operations async, establish new test infrastructure
- [ ] **Phase 15: External Authentication** — Integrate self-hosted OIDC auth provider for user registration and login
- [ ] **Phase 16: Multi-User Data Model** — Add user ownership to all entities with cross-user data isolation
- [ ] **Phase 17: Object Storage** — Move images from local filesystem to MinIO (S3-compatible)
- [x] **Phase 18: Global Items & Public Profiles** — Global item catalog, user profiles, and public setup sharing (completed 2026-04-05)
- [x] **Phase 19: Reference Item Model & Tags Schema** — Collection items as references to global catalog, tag system for discovery (completed 2026-04-05)
- [x] **Phase 20: FAB & Full-Screen Catalog Search** — Global FAB with mini menu, full-screen catalog search with tag filtering (completed 2026-04-06)
- [x] **Phase 21: Item & Catalog Detail Pages** — Full detail pages for collection items and catalog entries, replacing slide-out panels (completed 2026-04-06)
- [ ] **Phase 22: Add-from-Catalog & Thread Integration** — Add catalog items to collection and threads, resolution creates reference items
- [ ] **Phase 23: Manual Entry Fallback** — Manual add for items not in catalog, non-functional submission prompt

## Phase Details

### Phase 10: Schema Foundation + Pros/Cons Fields
**Goal**: Candidates can be annotated with pros and cons, and the database is ready for ranking
**Depends on**: Phase 9
**Requirements**: RANK-03
**Success Criteria** (what must be TRUE):
  1. User can open a candidate edit form and see pros and cons text fields
  2. User can save pros and cons text; the text persists across page refreshes
  3. CandidateCard shows a visual indicator when a candidate has pros or cons entered
  4. All existing tests pass after the schema migration (no column drift in test helper)
**Plans:** 1/1 plans complete
Plans:
- [x] 10-01-PLAN.md — Add pros/cons fields through full stack (schema, service, Zod, form, card indicator)

### Phase 11: Candidate Ranking
**Goal**: Users can drag candidates into a priority order that persists and is visually communicated
**Depends on**: Phase 10
**Requirements**: RANK-01, RANK-02, RANK-04, RANK-05
**Success Criteria** (what must be TRUE):
  1. User can drag a candidate card to a new position within the thread's candidate list
  2. The reordered sequence is still intact after navigating away and returning
  3. The top three candidates display gold, silver, and bronze rank badges respectively
  4. Drag handles and rank badges are absent on a resolved thread; candidates render in static order
**Plans:** 2/2 plans complete
Plans:
- [ ] 11-01-PLAN.md — Schema migration, reorder service/route, sort_order persistence + tests
- [ ] 11-02-PLAN.md — Drag-to-reorder UI, list/grid toggle, rank badges, resolved-thread guard

### Phase 12: Comparison View
**Goal**: Users can view all candidates for a thread side-by-side in a table with relative weight and price deltas
**Depends on**: Phase 11
**Requirements**: COMP-01, COMP-02, COMP-03, COMP-04
**Success Criteria** (what must be TRUE):
  1. User can toggle a "Compare" mode on a thread detail page to reveal a tabular view showing weight, price, images, notes, links, status, pros, and cons for every candidate in columns
  2. The lightest candidate column is highlighted and all other columns show their weight difference relative to it; the cheapest candidate is highlighted similarly for price
  3. The comparison table scrolls horizontally on a narrow viewport without breaking layout; the attribute label column stays fixed on the left
  4. A resolved thread shows the comparison table in read-only mode with the winning candidate visually marked
**Plans:** 1/1 plans complete
Plans:
- [ ] 12-01-PLAN.md — ComparisonTable component + compare toggle wiring in thread detail

### Phase 13: Setup Impact Preview
**Goal**: Users can select any setup and see exactly how much weight and cost each candidate would add or subtract
**Depends on**: Phase 12
**Requirements**: IMPC-01, IMPC-02, IMPC-03, IMPC-04
**Success Criteria** (what must be TRUE):
  1. User can select a setup from a dropdown in the thread header and each candidate displays a weight delta and cost delta below its name
  2. When the selected setup contains an item in the same category as the thread, the delta reflects replacing that item (negative delta is possible) rather than pure addition
  3. When no category match exists in the selected setup, the delta shows a pure addition amount clearly labeled as "add"
  4. A candidate with no weight recorded shows a "-- (no weight data)" indicator instead of a zero delta
**Plans:** 2 plans
Plans:
- [ ] 13-01-PLAN.md — TDD pure impact delta computation, uiStore state, ThreadWithCandidates type fix, useImpactDeltas hook
- [ ] 13-02-PLAN.md — SetupImpactSelector + ImpactDeltaBadge components, wire into thread detail and all candidate views

### Phase 14: PostgreSQL Migration
**Goal**: The application runs entirely on PostgreSQL with async operations, and all existing tests pass against the new database
**Depends on**: Phase 13
**Requirements**: DB-01, DB-02, DB-03, DB-04, DB-05
**Success Criteria** (what must be TRUE):
  1. Application starts and serves all existing features using PostgreSQL as the sole database
  2. All service-level and route-level tests pass using PGlite in-memory Postgres (no SQLite test infrastructure remains)
  3. A one-time migration script converts existing SQLite data into the Postgres database without data loss
  4. Docker Compose brings up Postgres alongside the app with a single command for local development
**Plans**: TBD

### Phase 15: External Authentication
**Goal**: Users can register and log in via a self-hosted OIDC auth provider, replacing the built-in single-user auth system
**Depends on**: Phase 14
**Requirements**: AUTH-01, AUTH-02, AUTH-03, AUTH-04, AUTH-05
**Success Criteria** (what must be TRUE):
  1. A new user can register an account through the external auth provider and land on their empty GearBox dashboard
  2. A returning user can log in via the auth provider and see their previously saved data
  3. API keys continue to work for MCP tools and programmatic access without involving the auth provider
  4. E2E tests run successfully using API key authentication, with no dependency on the external auth provider being available
  5. The auth provider runs self-hosted in Docker Compose alongside Postgres and the application
**Plans**: TBD

### Phase 16: Multi-User Data Model
**Goal**: Every piece of user-created data is owned by a specific user, with complete isolation between users
**Depends on**: Phase 15
**Requirements**: MULTI-01, MULTI-02, MULTI-03, MULTI-04, MULTI-05, MULTI-06
**Success Criteria** (what must be TRUE):
  1. User A cannot see or modify items, categories, threads, or setups created by User B
  2. Two users can each have a category with the same name without conflict
  3. Existing data from the single-user era is assigned to the original user account after migration
  4. MCP tools return only data belonging to the authenticated API key's owner
  5. Each user has independent settings (weight unit, onboarding state) that do not affect other users
**Plans**: TBD

### Phase 17: Object Storage
**Goal**: Images are stored in and served from MinIO instead of the local filesystem
**Depends on**: Phase 16
**Requirements**: IMG-01, IMG-02, IMG-03, IMG-04
**Success Criteria** (what must be TRUE):
  1. Uploading an image for an item or candidate stores it in MinIO, not on the local filesystem
  2. All previously uploaded images are accessible after migration to MinIO (no broken images)
  3. Image URLs work correctly in all views (collection, planning, setups, comparison table)
  4. Docker Compose includes MinIO for local development with no manual bucket setup required
**Plans**: TBD

### Phase 18: Global Items & Public Profiles
**Goal**: Users can discover gear through a global catalog and share their setups publicly via profile pages
**Depends on**: Phase 17
**Requirements**: GLOB-01, GLOB-02, GLOB-03, GLOB-04, GLOB-05, PROF-01, PROF-02, PROF-03, PROF-04, PROF-05
**Success Criteria** (what must be TRUE):
  1. A global item catalog exists with brand, model, category, specs, and images, seeded with initial manufacturer data
  2. User can search the global catalog by name or brand and link a personal collection item to a global entry
  3. A global item page shows basic info and how many users own it
  4. User can edit their profile (display name, avatar, bio) and view their own public profile page
  5. User can toggle a setup between public and private; public setups are viewable by anyone without logging in and appear on the owner's public profile
**Plans**: TBD
**UI hint**: yes

### Phase 19: Reference Item Model & Tags Schema
**Goal**: Collection items can be references to global catalog entries, and global items support tags for discovery
**Depends on**: Phase 18
**Requirements**: CATFLOW-03, CATFLOW-04, CATFLOW-05, CATFLOW-06, TAG-01, TAG-02
**Success Criteria** (what must be TRUE):
  1. A collection item can reference a global item and displays merged data (global base + personal fields)
  2. Global items can have multiple tags, searchable via API
  3. Thread candidates can link to a global item via globalItemId
  4. Resolving a thread with a catalog-linked candidate creates a reference item with auto-link
**Plans:** 3/3 plans complete
Plans:
- [x] 19-01-PLAN.md — Schema, migration, Zod schemas, types, seed script
- [x] 19-02-PLAN.md — Item service COALESCE merge, thread resolution, route cleanup
- [x] 19-03-PLAN.md — Global item tag filtering, secondary service merge propagation

### Phase 20: FAB & Full-Screen Catalog Search
**Goal**: Users discover and add gear through a catalog-first search experience with tag filtering
**Depends on**: Phase 19
**Requirements**: CATFLOW-01, CATFLOW-02
**Success Criteria** (what must be TRUE):
  1. FAB visible on all pages with mini menu showing "Add to Collection" and "Start Thread"
  2. "New Setup" option appears in FAB on setups page only
  3. Full-screen catalog search overlay opens from either add option
  4. Search results display catalog items with name, weight, price, owner count
  5. Tag chips filter search results
**Plans:** 2/2 plans complete
Plans:
- [x] 20-01-PLAN.md — Tags endpoint, global-items route registration, UIStore extension, useTags hook
- [x] 20-02-PLAN.md — FabMenu component, CatalogSearchOverlay component, root layout wiring
**UI hint**: yes

### Phase 21: Item & Catalog Detail Pages
**Goal**: Collection items and catalog entries have full detail pages, replacing the slide-out panel pattern
**Depends on**: Phase 20
**Requirements**: DETAIL-01, DETAIL-02, DETAIL-03, DETAIL-04, DETAIL-05
**Success Criteria** (what must be TRUE):
  1. Clicking a collection item card navigates to `/items/:id` showing full item details with edit toggle
  2. Clicking a catalog search result card navigates to `/global-items/:id` showing public catalog details with "Add to Collection" button
  3. Thread candidates navigate to detail pages instead of opening slide-out panels
  4. Item slide-out panel and candidate slide-out panel are removed from the root layout
  5. No visual distinction between reference items and standalone items — same layout, some fields may be empty
**Plans**: TBD
**UI hint**: yes

### Phase 22: Add-from-Catalog & Thread Integration
**Goal**: Users can add catalog items to their collection and to threads directly from search
**Depends on**: Phase 21
**Requirements**: CATFLOW-03, CATFLOW-05, CATFLOW-06
**Success Criteria** (what must be TRUE):
  1. User can add a catalog item to collection with one confirmation step (category picker + notes)
  2. User can add catalog items as thread candidates instantly from search
  3. Resolving a catalog-linked candidate creates a properly linked reference item in collection
**Plans**: TBD
**UI hint**: yes

### Phase 23: Manual Entry Fallback
**Goal**: Users can still add items not found in the catalog via manual entry
**Depends on**: Phase 22
**Requirements**: CATFLOW-07, CATFLOW-08
**Success Criteria** (what must be TRUE):
  1. User can fall back to manual entry from catalog search via "Add Manually" link
  2. Manual entry saves a standalone collection item (no globalItemId)
  3. "Submit to catalog?" prompt appears after manual save but takes no backend action
**Plans**: TBD
**UI hint**: yes

## 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 | 0/2 | Not started | - |
| 14. PostgreSQL Migration | v2.0 | 0/? | Not started | - |
| 15. External Authentication | v2.0 | 0/? | Not started | - |
| 16. Multi-User Data Model | v2.0 | 0/? | Not started | - |
| 17. Object Storage | v2.0 | 0/? | Not started | - |
| 18. Global Items & Public Profiles | v2.0 | 4/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 | 1/1 | Complete    | 2026-04-06 |
| 22. Add-from-Catalog & Thread Integration | v2.0 | 0/? | Not started | - |
| 23. Manual Entry Fallback | v2.0 | 0/? | Not started | - |
