diff --git a/.planning/phases/26-discovery-landing-page/26-CONTEXT.md b/.planning/phases/26-discovery-landing-page/26-CONTEXT.md new file mode 100644 index 0000000..f94efea --- /dev/null +++ b/.planning/phases/26-discovery-landing-page/26-CONTEXT.md @@ -0,0 +1,135 @@ +# Phase 26: Discovery Landing Page - Context + +**Gathered:** 2026-04-10 +**Status:** Ready for planning + + +## Phase Boundary + +Replace the current personal dashboard at `/` with a public-first discovery landing page. The page features a prominent catalog search bar at the top, a feed of popular public setups, recently added catalog items, and trending categories. Authenticated users see a "Go to Collection" entry point. This is the first page any visitor sees — no login required. + + + + +## Implementation Decisions + +### Page Layout & Structure +- **D-01:** Full-width hero area with catalog search bar prominently centered. Below the hero, a vertical stack of content sections. +- **D-02:** Section order: (1) Hero with search bar, (2) Popular Setups, (3) Recently Added Items, (4) Trending Categories. Each section has a heading and optional "View all" link. +- **D-03:** The current `DashboardPage` component and its `DashboardCard` usage at `/` will be replaced entirely. The dashboard is now the landing page. + +### Search Bar Behavior +- **D-04:** The hero search bar triggers the existing `CatalogSearchOverlay` on focus or typing. This reuses the full-featured search (tag filtering, grid/list toggle, manual entry fallback) without duplicating search UI. The search bar on the landing page is a visual entry point, not a standalone search results container. + +### Feed Data Sources & Ranking +- **D-05:** "Popular setups" ranked by item count descending (proxy for effort/completeness). Only public setups are shown. No engagement tracking exists yet — item count is available via `setupItems` join table. +- **D-06:** "Recently added items" shows the most recently created `globalItems`, ordered by `createdAt` descending. +- **D-07:** "Trending categories" ranked by global item count per distinct `globalItems.category` value. Categories with the most catalog items appear first. +- **D-08:** Cursor-based pagination for feed sections per INFR-02. Use `createdAt` cursor for recently added items; item count + ID cursor for popular setups. + +### Authenticated vs Anonymous Experience +- **D-09:** Same page content for both authenticated and anonymous users — no personalized feed in v2.1. The difference is purely navigational. +- **D-10:** Authenticated users see a "Go to Collection" CTA in the hero area, next to the search bar. Visible without scrolling. +- **D-11:** Anonymous users see the search bar and content sections immediately (fire-and-forget auth from Phase 24, D-09). Sign-in button in top-right per Phase 24, D-10. + +### Claude's Discretion +- Exact layout sizing, spacing, and responsive breakpoints +- Number of items shown per section before "View all" (suggest 6-8 for items/setups, 8-12 for categories) +- Empty states for sections with no data +- Loading skeletons for each section +- Whether "View all" links for setups/items route to existing pages or new dedicated feed pages + +### Folded Todos +- **Add cursor pointer to all clickable links** — Ensure all clickable elements on the landing page have `cursor-pointer`. Apply broadly while building the new page. +- **Fix item image not showing on collection overview** — Investigate and fix image display issue; relevant since landing page will show `GlobalItemCard` components with images. +- **Investigate slow image loading** — Profile image loading performance; landing page is image-heavy with item cards and setup previews. + + + + +## Canonical References + +**Downstream agents MUST read these before planning or implementing.** + +### Current Landing Page (to replace) +- `src/client/routes/index.tsx` — Current dashboard page component (will be rewritten) +- `src/client/components/DashboardCard.tsx` — Current dashboard card (will be unused after this phase) + +### Reusable Components +- `src/client/components/GlobalItemCard.tsx` — Catalog item card with image, brand/model, weight/price pills +- `src/client/components/PublicSetupCard.tsx` — Basic public setup card (name + date; may need enhancement for item count) +- `src/client/components/CatalogSearchOverlay.tsx` — Full-screen search overlay with debounce, tag filtering, grid/list modes + +### Hooks & Data +- `src/client/hooks/useGlobalItems.ts` — Search global items by query and tags +- `src/client/hooks/useTags.ts` — Fetch tag list +- `src/client/hooks/useAuth.ts` — Auth state (`user`, `authenticated`) +- `src/client/stores/uiStore.ts` — UI state store including `catalogSearchOpen` / `openCatalogSearch` + +### Server Services +- `src/server/services/global-item.service.ts` — `searchGlobalItems` (needs new queries: recent items, category counts) +- `src/server/services/profile.service.ts` — `getPublicProfile`, `getPublicSetupWithItems` (setup data patterns) + +### Routes & API +- `src/server/routes/global-items.ts` — Current GET endpoints (needs discovery feed endpoints) +- `src/server/routes/setups.ts` — Public setup view endpoint (`GET /:id/public`) +- `src/server/index.ts` — Route registration and public route allowlist + +### Auth & Layout +- `src/client/routes/__root.tsx` — Root layout, auth check, `isPublicRoute` logic (root `/` already public per Phase 24) + +### Requirements +- `.planning/REQUIREMENTS.md` — DISC-01 through DISC-05, INFR-02 + + + + +## Existing Code Insights + +### Reusable Assets +- `GlobalItemCard` — Ready-to-use catalog item card with image placeholder, brand/model, weight/price/category pills. Can be used directly in "Recently Added" section. +- `PublicSetupCard` — Minimal card (name + date). Needs enhancement: add item count, possibly creator name and total weight to be useful in a "Popular Setups" feed. +- `CatalogSearchOverlay` — Full search implementation with debounce, tag chip filtering, grid/list toggle, manual entry. Landing page search bar should open this overlay rather than duplicating search logic. +- `useFormatters` hook — Weight and price formatting, reusable across all card components. +- `LucideIcon` component — For category icons in the "Trending Categories" section. + +### Established Patterns +- TanStack Router file-based routes — new route stays at `routes/index.tsx` (same file, new content) +- TanStack React Query for data fetching — landing page sections each get their own query hook +- Tailwind CSS v4 with light/airy/minimalist design language — white backgrounds, gray borders, rounded-xl cards, subtle shadows on hover +- Card pattern: `bg-white rounded-xl border border-gray-100 hover:border-gray-200 hover:shadow-md transition-all` + +### Integration Points +- `routes/index.tsx` — Rewrite to render landing page instead of dashboard +- New server endpoints needed: `GET /api/discovery/setups` (popular), `GET /api/discovery/items` (recent), `GET /api/discovery/categories` (trending) +- `uiStore.openCatalogSearch()` — Trigger from the hero search bar + + + + +## Specific Ideas + +- Design should feel like a welcoming storefront, not a login gate — consistent with Phase 24's "new user experience matters more" principle +- Tags are the public taxonomy for discovery; categories are private organizational tools — the landing page uses tags for any filtering/categorization display, not user categories +- Hero area should be visually distinctive but not heavy — the app's DNA is "light, airy, minimalist" + + + + +## Deferred Ideas + +- Personalized feed based on user's collection categories (PERS-01, PERS-02) — tracked in future requirements +- SSR/static prerendering for SEO (SEO-01, SEO-02) — out of scope for v2.1 +- Engagement metrics (views, likes) for better ranking — no tracking infrastructure yet +- Setup preview images/thumbnails — no setup image feature exists + +### Reviewed Todos (not folded) +- **Add manufacturer entity with brand details** — Database schema enhancement unrelated to landing page UI; belongs in a future catalog data model phase +- **Fix storage service tests** — Testing infrastructure concern; not related to landing page feature work + + + +--- + +*Phase: 26-discovery-landing-page* +*Context gathered: 2026-04-10* diff --git a/.planning/phases/26-discovery-landing-page/26-DISCUSSION-LOG.md b/.planning/phases/26-discovery-landing-page/26-DISCUSSION-LOG.md new file mode 100644 index 0000000..52d544f --- /dev/null +++ b/.planning/phases/26-discovery-landing-page/26-DISCUSSION-LOG.md @@ -0,0 +1,103 @@ +# Phase 26: Discovery Landing Page - Discussion Log + +> **Audit trail only.** Do not use as input to planning, research, or execution agents. +> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered. + +**Date:** 2026-04-10 +**Phase:** 26-discovery-landing-page +**Areas discussed:** Page Structure & Section Order, Search Bar Behavior, Feed Data & Ranking, Auth-Variant Experience +**Mode:** --batch --auto (all decisions auto-selected) + +--- + +## Page Structure & Section Order + +| Option | Description | Selected | +|--------|-------------|----------| +| Hero search + vertical sections | Full-width hero with search bar, vertical stack of content sections below | ✓ | +| Grid dashboard | Multi-column grid of section cards (like current dashboard) | | +| Single infinite feed | One merged feed of all content types | | + +**User's choice:** [auto] Hero search + vertical sections (recommended default) +**Notes:** Reuses existing visual patterns (cards, rounded-xl, light borders). Section order: Search → Setups → Items → Categories, prioritizing social content first. + +--- + +## Search Bar Behavior + +| Option | Description | Selected | +|--------|-------------|----------| +| Open CatalogSearchOverlay | Hero search bar triggers existing overlay on focus/type | ✓ | +| Inline search results | Show results directly below the search bar on the landing page | | +| Dedicated search route | Navigate to /search with query params | | + +**User's choice:** [auto] Open CatalogSearchOverlay (recommended default) +**Notes:** Avoids duplicating the full-featured search UI (tag filtering, grid/list toggle, manual entry fallback). CatalogSearchOverlay is already built and tested. + +--- + +## Feed Data & Ranking + +| Option | Description | Selected | +|--------|-------------|----------| +| Item count proxy (setups) | Rank popular setups by number of items — more items = more effort/completeness | ✓ | +| Creation date (setups) | Show most recently created setups | | +| Random rotation | Rotate featured setups randomly | | + +**User's choice:** [auto] Item count proxy (recommended default) +**Notes:** No engagement metrics exist. Item count is the best available proxy and is trivially queryable via setupItems join. + +| Option | Description | Selected | +|--------|-------------|----------| +| Global item count per category | Trending = categories with most catalog items | ✓ | +| Recent growth rate | Categories with most new items in last 7 days | | + +**User's choice:** [auto] Global item count per category (recommended default) +**Notes:** Simpler query, no time-windowed aggregation needed. Growth-based trending can be added later when catalog is larger. + +| Option | Description | Selected | +|--------|-------------|----------| +| Cursor-based pagination | Use cursor pagination per INFR-02 requirement | ✓ | +| Offset pagination | Traditional LIMIT/OFFSET | | + +**User's choice:** [auto] Cursor-based pagination (recommended default — required by INFR-02) + +--- + +## Auth-Variant Experience + +| Option | Description | Selected | +|--------|-------------|----------| +| Same page + Collection CTA | Identical content, authenticated users get "Go to Collection" button in hero | ✓ | +| Dual-mode page | Show personal stats/shortcuts for authenticated users | | +| Redirect authenticated to dashboard | Authenticated users skip landing page entirely | | + +**User's choice:** [auto] Same page + Collection CTA (recommended default) +**Notes:** Per DISC-05, the difference is a single navigational CTA. No personalized feed in v2.1 (PERS-01/PERS-02 deferred). + +| Option | Description | Selected | +|--------|-------------|----------| +| In hero area next to search | CTA visible without scrolling, adjacent to primary action | ✓ | +| Floating sidebar | Persistent side panel for authenticated users | | +| Below hero | Separate banner below search area | | + +**User's choice:** [auto] In hero area next to search (recommended default) + +--- + +## Claude's Discretion + +- Exact layout sizing, spacing, and responsive breakpoints +- Number of items shown per section before "View all" +- Empty states for sections with no data +- Loading skeletons for each section +- Whether "View all" links route to existing pages or new feed pages + +## Deferred Ideas + +- Personalized feed (PERS-01, PERS-02) +- SSR/static prerendering for SEO (SEO-01, SEO-02) +- Engagement metrics for ranking +- Setup preview images +- Manufacturer entity (todo — different domain) +- Storage service tests (todo — testing concern)