# Phase 26: Discovery Landing Page - Context

**Gathered:** 2026-04-10
**Status:** Ready for planning

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

</domain>

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

</decisions>

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

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

</specifics>

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

</deferred>

---

*Phase: 26-discovery-landing-page*
*Context gathered: 2026-04-10*