GearBox/.planning/milestones/v1.0-phases/02-planning-threads/02-CONTEXT.md

Phase 2: Planning Threads - Context

Gathered: 2026-03-15 Status: Ready for planning

## Phase Boundary

Purchase research workflow: create planning threads, add candidate products, compare them, and resolve a thread by picking a winner that moves into the collection. No setups, no dashboard, no impact preview — those are later phases or v2.

## Implementation Decisions

Thread List View

• Card-based layout, same visual pattern as collection items
• Thread card shows: name prominent, then pill/chip tags for candidate count, creation date, price range
• Flat list, most recent first (no grouping)
• Resolved/archived threads hidden by default with a toggle to show them

Candidate Display & Management

• Candidates displayed as card grid within a thread (same card style as collection items)
• Slide-out panel for adding/editing candidates (reuses existing SlideOutPanel component)
• Candidates share the exact same fields as collection items: name, weight, price, category, notes, product link, image
• Same data shape means resolution is seamless — candidate data maps directly to a collection item

Thread Resolution Flow

• Picking a winner auto-creates a collection item from the candidate's data (no review/edit step)
• Confirmation dialog before resolving ("Pick [X] as winner? This will add it to your collection.")
• After resolution, thread is archived (removed from active list, kept in history)
• Confirmation dialog reuses the existing ConfirmDialog component pattern

Navigation

• Tab within the collection page: "My Gear" | "Planning" tabs
• Top navigation bar always visible for switching between major sections
• Thread list and collection share the same page with tab-based switching

Claude's Discretion

• Exact "pick winner" UX (button on card vs thread-level action)
• Thread detail page layout (how the thread view is structured beyond the card grid)
• Empty state for threads (no threads yet) and empty thread (no candidates yet)
• How the tab switching integrates with TanStack Router (query params vs nested routes)
• Thread card image (first candidate's image, thread-specific image, or none)

## Specific Ideas

• Visual consistency is important — threads and candidates should look and feel like the collection, not a separate app
• Pill/chip tag pattern carries over: candidate count, date, price range displayed as compact tags
• The slide-out panel pattern from Phase 1 should be reused directly for candidate add/edit
• Thread resolution is a one-step action: confirm → item appears in collection, thread archived

<code_context>

Existing Code Insights

Reusable Assets

• SlideOutPanel.tsx: Right-side slide panel — reuse for candidate add/edit
• ConfirmDialog.tsx: Confirmation modal — reuse for resolution confirmation
• ItemCard.tsx: Card component with tag chips — pattern reference for thread/candidate cards
• ItemForm.tsx: Form with category picker — candidate form shares the same fields
• CategoryPicker.tsx: ARIA combobox — reuse for candidate category selection
• ImageUpload.tsx: Image upload component — reuse for candidate images
• TotalsBar.tsx: Sticky totals — could adapt for thread-level candidate totals

Established Patterns

• Service layer with DB injection for testability (item.service.ts, category.service.ts)
• Hono routes with Zod validation via @hono/zod-validator
• TanStack Query hooks for data fetching (useItems, useCategories, useTotals)
• Zustand store for UI state (uiStore.ts)
• API client utilities (apiGet, apiPost, apiPut, apiDelete, apiUpload)
• Shared Zod schemas in src/shared/schemas.ts
• Weight stored in grams, price in cents (integer math)

Integration Points

• Database: Need new tables for threads and thread_candidates (src/db/schema.ts)
• Shared schemas: Need thread and candidate Zod schemas (src/shared/schemas.ts)
• Server: New routes mounted in src/server/index.ts
• Client: New route/tab integrated via TanStack Router
• Resolution creates items via existing item.service.ts createItem function

</code_context>

## Deferred Ideas

• Linking existing collection items as reference candidates in a thread — nice-to-have, not v1
• Side-by-side comparison view (columns instead of cards) — could be v2 enhancement (THRD-05)
• Status tracking on candidates (researching → ordered → arrived) — v2 (THRD-06)
• Impact preview showing how a candidate affects setup weight/cost — v2 (THRD-08)

---

Phase: 02-planning-threads Context gathered: 2026-03-15