136 lines
7.9 KiB
Markdown
136 lines
7.9 KiB
Markdown
# 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*
|