GearBox/.planning/phases/26-discovery-landing-page/26-CONTEXT.md

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_refs>

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

</canonical_refs>

<code_context>

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

</code_context>

## 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