GearBox/.planning/milestones/v1.0-phases/03-setups-and-dashboard/03-CONTEXT.md

Phase 3: Setups and Dashboard - Context

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

## Phase Boundary

Named loadouts composed from collection items with live weight/cost totals, plus a dashboard home page with summary cards linking to collection, threads, and setups. No setup enhancements (weight classification, charts) — those are v2. No thread or collection changes beyond navigation restructure.

## Implementation Decisions

Setup Item Selection

• Checklist picker in a SlideOutPanel showing all collection items
• Items grouped by category with emoji headers (same grouping as collection view)
• Toggle items on/off via checkboxes — "Done" button to confirm
• Items can belong to multiple setups (shared, not exclusive)

Setup Creation

• Inline name input + create button at top of setups list
• Same pattern as thread creation in Phase 2 (text input + button)
• No description field or extra metadata — just a name

Setup Display

• Card grid layout grouped by category, reusing ItemCard component
• Same visual pattern as collection view for consistency
• Each item card gets a small × remove icon to remove from setup (not from collection)
• No confirmation dialog for removal — non-destructive action
• Per-category subtotals in CategoryHeader (weight/cost within this setup)

Setup Totals

• Sticky bar at top of setup detail page showing setup name, item count, total weight, total cost
• Reuses TotalsBar pattern — contextual stats for the current setup
• Totals computed live from current item data

Dashboard Card Design

• Three equal-width cards side by side on desktop, stacking vertically on mobile
• Collection card: item count, total weight, total cost
• Planning card: active thread count
• Setups card: setup count
• Summary stats on each card — at-a-glance overview before clicking in
• Empty state: same cards with zeros, Collection card says "Get started"

Dashboard Page Header

• "GearBox" title only on dashboard (stats already on cards, no redundancy)
• No welcome message or greeting — clean and minimal

Navigation & URL Structure

• / = Dashboard (three summary cards)
• /collection = Gear | Planning tabs (moved from current /)
• /collection?tab=planning = Planning tab
• /threads/:id = Thread detail (unchanged)
• /setups = Setups list
• /setups/:id = Setup detail
• "GearBox" title in TotalsBar is always a clickable link back to dashboard
• No breadcrumbs or back arrows — GearBox title link is the only back navigation
• Sub-pages show contextual stats in TotalsBar; dashboard shows title only

Claude's Discretion

• Setup list card design (what stats/info to show per setup card beyond name and totals)
• Exact Tailwind styling, spacing, and transitions for dashboard cards
• Setup detail page layout specifics beyond the card grid + sticky totals
• How the checklist picker handles a large number of items (scroll behavior)
• Error states and loading skeletons

## Specific Ideas

• Dashboard should feel like a clean entry point — "GearBox" title, three cards, lots of whitespace
• Setup detail should visually mirror the collection view (same card grid, category headers, tag chips) so it feels like a filtered subset of your gear
• Removal × on cards should be subtle — don't clutter the visual consistency with collection
• Thread creation pattern (inline input + button) is the reference for setup creation

<code_context>

Existing Code Insights

Reusable Assets

• SlideOutPanel.tsx: Right-side slide panel — reuse for checklist item picker
• ItemCard.tsx: Card with tag chips — reuse directly in setup detail view (add × icon variant)
• CategoryHeader.tsx: Category section with emoji + subtotals — reuse in setup detail
• TotalsBar.tsx: Sticky bar with stats — adapt for contextual stats per page
• ThreadCard.tsx: Card with pill tags — pattern reference for setup list cards
• ConfirmDialog.tsx: Confirmation modal — reuse for setup deletion
• ThreadTabs.tsx: Tab component — reuse for gear/planning tabs on /collection

Established Patterns

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

Integration Points

• Database: New setups and setup_items tables in src/db/schema.ts
• Shared schemas: Setup Zod schemas in src/shared/schemas.ts
• Server: New setup routes in src/server/routes/, mounted in src/server/index.ts
• Client: New /collection and /setups routes, refactor current / to dashboard
• TotalsBar: Needs to become route-aware (different stats per page)
• Totals service: New setup totals endpoint or compute client-side from items

</code_context>

## Deferred Ideas

None — discussion stayed within phase scope

---

Phase: 03-setups-and-dashboard Context gathered: 2026-03-15