diff --git a/.planning/phases/01-foundation-and-collection/01-CONTEXT.md b/.planning/phases/01-foundation-and-collection/01-CONTEXT.md new file mode 100644 index 0000000..125ecfe --- /dev/null +++ b/.planning/phases/01-foundation-and-collection/01-CONTEXT.md @@ -0,0 +1,91 @@ +# 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 + + + + +## 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 + + + + +## 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*