GearBox/.planning/milestones/v1.0-phases/01-foundation-and-collection/01-CONTEXT.md

Phase 1: Foundation and Collection - Context

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

## Phase Boundary

Project scaffolding (Bun + Hono + React + Vite + SQLite via Drizzle), database schema for items and categories, and complete gear collection CRUD with category management and aggregate totals. No threads, no setups, no dashboard — those are later phases.

## Implementation Decisions

Collection Layout

• Card grid layout, grouped by category headers
• Each card shows: item name (prominent), then tag-style chips for weight, price, and category
• Item image displayed on the card for visual identification
• Items grouped under category headers with per-category weight/cost subtotals
• Global sticky totals bar at the top showing total items, weight, and cost
• Empty categories are hidden from the collection view (not shown)

Item Editing Flow

• Slide-out panel from the right side for both adding and editing items
• Same panel component for add (empty) and edit (pre-filled)
• Collection remains visible behind the panel for context
• Confirmation dialog before deleting items ("Are you sure?")

Category Management

• Single-level categories only (no subcategories)
• Searchable category picker in the item form — type to find existing or create new
• Categories editable from the collection overview (rename, delete, change icon)
• Each category gets an emoji/icon for visual distinction
• Deleting a category moves its items to "Uncategorized" default category

First-Run Experience

• Step-by-step onboarding wizard for first-time users
• Guides through: create first category, add first item
• After onboarding, normal collection view takes over

Claude's Discretion

• Form layout for item add/edit panel (all fields visible vs grouped sections)
• Loading states and skeleton design
• Exact spacing, typography, and Tailwind styling choices
• Error state handling and validation feedback
• Weight unit storage (grams internally, display in user's preferred unit can be deferred to v2)

## Specific Ideas

• Cards should feel clean and minimal — "light and airy" aesthetic with white/light backgrounds, lots of whitespace
• Item info displayed as tag-style chips (not labels with values) — compact, scannable
• Category picker should work like a combobox: type to search, select existing, or create new inline
• Photos on cards are important for visual identification even in v1

<code_context>

Existing Code Insights

Reusable Assets

• None — greenfield project, no existing code

Established Patterns

• None yet — Phase 1 establishes all patterns

Integration Points

• Bun runtime with bun:sqlite for database
• Hono for API server
• React 19 + Vite 8 for frontend
• Drizzle ORM for type-safe database access
• Tailwind v4 for styling
• TanStack Router for client-side routing

</code_context>

## Deferred Ideas

• Subcategories (e.g. "Bags" → "Handlebar Bag") — revisit if single-level feels limiting
• Photos are noted as important for cards; image upload implementation is technically in scope (COLL-01 mentions item details) but full photo management is v2

---

Phase: 01-foundation-and-collection Context gathered: 2026-03-14