GearBox/.planning/milestones/v2.0-ROADMAP.md

Roadmap Archive: v2.0 Platform Foundation

Archived: 2026-04-08 Status: SHIPPED Phases: 14-23 (10 phases, 32 plans) Timeline: 2026-03-17 to 2026-04-08

---

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: 6/6 plans complete

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: 3/3 plans complete

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: 4/4 plans complete

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: 3/3 plans complete

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: 5/5 plans complete

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

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

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: 3/3 plans complete

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

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