Jean-Luc Makiola
2853477a75
Phases 28-31 archived to milestones/v2.2-phases/ Requirements and roadmap snapshots archived to milestones/ Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
126 lines
6.2 KiB
Markdown
126 lines
6.2 KiB
Markdown
# Phase 30: Onboarding Redesign - Context
|
|
|
|
**Gathered:** 2026-04-12
|
|
**Status:** Ready for planning
|
|
|
|
<domain>
|
|
## Phase Boundary
|
|
|
|
Replace the current manual-entry onboarding wizard with a catalog-driven, hobby-personalized full-screen experience. New users pick their hobby, see popular items from that hobby's catalog, and batch-add items they own to their collection. Categories auto-created from selections.
|
|
|
|
</domain>
|
|
|
|
<decisions>
|
|
## Implementation Decisions
|
|
|
|
### Flow Structure
|
|
- **D-01:** Onboarding flow: **Welcome → Pick Hobby → Browse Popular Items → Review & Confirm → Done**
|
|
- **D-02:** Display name captured during signup (Logto field or first-login prompt) — NOT during onboarding wizard.
|
|
- **D-03:** Profile pic is not part of onboarding — users add it later from the profile page.
|
|
- **D-04:** Hobby selection is the key personalization step — it determines what catalog items are shown.
|
|
- **D-05:** Categories auto-created from the user's selections (based on the tags/categories of items they add). No manual "create a category" step.
|
|
|
|
### Hobby Selection
|
|
- **D-06:** Card-based hobby picker with icons — visual cards for each hobby area (Bikepacking, Hiking, Climbing, Cycling, etc.). Not a plain tag list.
|
|
- **D-07:** Hobbies map to catalog tags for filtering. Starting with outdoor categories, but the system is extensible to any hobby.
|
|
- **D-08:** User can pick one or more hobbies. Multiple selections show combined results.
|
|
|
|
### Catalog Integration
|
|
- **D-09:** After hobby selection, show popular items from the most popular tags within that hobby. Not a full search — a curated, browsable grid.
|
|
- **D-10:** "Popular" initially measured by **owner count** (how many users have linked the item). Real view analytics are a future enhancement.
|
|
- **D-11:** User taps/checks items they own — selections collected as a batch. No immediate adds.
|
|
- **D-12:** Summary/review screen before final commit — user confirms their selections, then all items batch-added to their collection at once.
|
|
|
|
### Visual Style
|
|
- **D-13:** Full-screen experience — each step takes the full viewport. Big visuals, generous spacing, immersive. Modern app intro feel (Notion/Linear style).
|
|
- **D-14:** Replace the current centered modal card approach entirely.
|
|
- **D-15:** Smooth transitions between steps. Step indicator still present but full-width, not dots.
|
|
|
|
### Trigger & Skip Behavior
|
|
- **D-16:** Triggers on first login (any auth method — email, Google, GitHub).
|
|
- **D-17:** Hobby selection step is **required** (not skippable) — essential for personalization.
|
|
- **D-18:** Other steps (browse items, add to collection) are skippable. Skipping marks onboarding complete.
|
|
|
|
### Claude's Discretion
|
|
- Hobby card design and icon choices
|
|
- How many items/tags to show per hobby
|
|
- Transition animations between steps
|
|
- Whether to use TanStack Router routes or a single component with internal step state
|
|
- How to handle users who sign up for a hobby with no catalog items yet (empty state)
|
|
- Exact categories auto-created logic (group by tag, by catalog category, etc.)
|
|
|
|
</decisions>
|
|
|
|
<canonical_refs>
|
|
## Canonical References
|
|
|
|
**Downstream agents MUST read these before planning or implementing.**
|
|
|
|
### Existing Onboarding Code (to be replaced)
|
|
- `src/client/components/OnboardingWizard.tsx` — Current 4-step modal wizard
|
|
- `src/client/routes/__root.tsx` — Onboarding trigger logic (lines ~98-105, ~193)
|
|
|
|
### Catalog Components (reusable patterns)
|
|
- `src/client/components/CatalogSearchOverlay.tsx` — Catalog search with tag filtering
|
|
- `src/client/components/GlobalItemCard.tsx` — Card display for catalog items
|
|
- `src/client/hooks/useGlobalItems.ts` — Catalog data fetching hooks
|
|
|
|
### Add-from-Catalog Flow
|
|
- `src/client/components/LinkToGlobalItem.tsx` — Linking user items to global items
|
|
|
|
### Settings/Onboarding State
|
|
- `src/server/routes/settings.ts` — Settings CRUD (onboardingComplete flag)
|
|
- `src/server/services/settings.service.ts` — Settings service
|
|
|
|
### Discovery (popular items data)
|
|
- `src/server/services/discovery.service.ts` — getRecentCatalogItems, getPopularSetups — similar patterns for popular items by tag
|
|
|
|
</canonical_refs>
|
|
|
|
<code_context>
|
|
## Existing Code Insights
|
|
|
|
### Reusable Assets
|
|
- `GlobalItemCard` component — card display for catalog items. Can be reused in the onboarding item grid.
|
|
- `CatalogSearchOverlay` — tag-filtered search. Patterns reusable for hobby-filtered browsing.
|
|
- `useGlobalItems` hook — fetches catalog items with search/filter. Can be extended for tag-based popularity queries.
|
|
- `LucideIcon` — icon rendering for hobby cards.
|
|
- Discovery service — `getRecentCatalogItems` pattern can be adapted for "popular items by tag".
|
|
|
|
### Established Patterns
|
|
- Onboarding state tracked via `settings` table (`onboardingComplete: "true"`)
|
|
- Full-screen modals exist in auth flow — pattern can be adapted
|
|
- Tag system already supports filtering catalog items by tags
|
|
|
|
### Integration Points
|
|
- `src/client/routes/__root.tsx` — Replace onboarding trigger with new full-screen experience
|
|
- `src/server/services/discovery.service.ts` — Add "popular items by hobby/tag" query
|
|
- `src/server/routes/discovery.ts` — Add endpoint for hobby-filtered popular items
|
|
- `src/db/schema.ts` — May need a user_preferences or hobby_selections table
|
|
|
|
</code_context>
|
|
|
|
<specifics>
|
|
## Specific Ideas
|
|
|
|
- The hobby selection personalizes the experience from the very start — it should feel like the app is being tailored for them.
|
|
- Starting with outdoor categories (bikepacking, hiking, climbing, cycling) but the system must easily accommodate future hobbies (sim racing, photography, etc.).
|
|
- Owner count as the initial "popularity" metric is good enough for launch. Real analytics/view tracking comes later (backlog 999.8).
|
|
- The current OnboardingWizard.tsx is a complete rewrite — nothing is reused from it except the onboardingComplete settings flag.
|
|
|
|
</specifics>
|
|
|
|
<deferred>
|
|
## Deferred Ideas
|
|
|
|
- View/click analytics for better popularity ranking — belongs in 999.8 Analytics Integration
|
|
- Category editing UI — separate improvement, not onboarding-specific
|
|
- Profile pic during onboarding — deferred, handled via profile page
|
|
|
|
</deferred>
|
|
|
|
---
|
|
|
|
*Phase: 30-onboarding-redesign*
|
|
*Context gathered: 2026-04-12*
|