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

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

4.5 KiB Raw Blame History