277 lines
17 KiB
Markdown
277 lines
17 KiB
Markdown
# 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** <20><> 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)
|
||
- [x] **Phase 22: Add-from-Catalog & Thread Integration** — Add catalog items to collection and threads, resolution creates reference items (completed 2026-04-06)
|
||
- [x] **Phase 23: Manual Entry Fallback** — Manual add for items not in catalog, non-functional submission prompt (completed 2026-04-06)
|
||
|
||
## 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:** 2/2 plans complete
|
||
Plans:
|
||
- [x] 22-01-PLAN.md -- UIStore + sonner + AddToCollectionModal + overlay/detail page collection wiring
|
||
- [x] 22-02-PLAN.md -- AddToThreadModal with thread picker + new thread flow + CATFLOW-06 verification
|
||
**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:** 1/1 plans complete
|
||
Plans:
|
||
- [x] 23-01-PLAN.md -- ManualEntryForm + CatalogSearchOverlay wiring
|
||
**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 | 2/2 | Complete | 2026-04-06 |
|
||
| 23. Manual Entry Fallback | v2.0 | 1/1 | Complete | 2026-04-06 |
|