104 lines
5.0 KiB
Markdown
104 lines
5.0 KiB
Markdown
# Phase 7: Setup Wizard - Context
|
|
|
|
**Gathered:** 2026-04-20
|
|
**Status:** Ready for planning
|
|
|
|
<domain>
|
|
## Phase Boundary
|
|
|
|
A new user can set up their budget template in under 3 minutes by following a guided 3-step wizard with pre-filled common items and a live running balance. The wizard auto-redirects first-run users (detected by useFirstRunState), creates categories and template items on completion, persists state across refreshes, and supports skip at any point. Bilingual (EN/DE) via existing i18n system.
|
|
|
|
</domain>
|
|
|
|
<decisions>
|
|
## Implementation Decisions
|
|
|
|
### Wizard Layout & Navigation
|
|
- Numbered horizontal stepper (1-2-3 bar at top) — minimal, clear progress indicator
|
|
- Centered card layout (max-w-2xl) on clean background — consistent with auth pages
|
|
- Next/Back buttons at bottom + step indicator is clickable for going back
|
|
- Same centered card on mobile, full-width breakpoint — project is desktop-first
|
|
|
|
### Income Step (Step 1)
|
|
- Single "monthly net income" number input — simplest mental model
|
|
- Pre-filled with 3000 (PRESETS salary default), user can clear and type their own
|
|
- Show user's profile currency (EUR) from useAuth/profile next to input
|
|
- Required field, must be > 0, numeric only — can't proceed without income entered
|
|
|
|
### Recurring Items Step (Step 2)
|
|
- Full checklist: all 19 PRESETS shown, grouped by category type, with item name + category badge + editable amount per row
|
|
- Bills (4) + variable_expense (5) pre-checked by default — focuses on spending categories the wizard is about
|
|
- Income/debt/saving/investment items unchecked by default
|
|
- Sticky bar at top: "Remaining to allocate: Income - sum(checked) = X" — turns red when negative
|
|
- Inline number input per item, only editable when item is checked
|
|
|
|
### Review Step & Completion (Step 3)
|
|
- Read-only summary card: income at top, grouped checked items with amounts below, total and remaining at bottom
|
|
- "Complete" creates categories (from checked item types that don't already exist) + template items (from checked items with amounts)
|
|
- Does NOT create first month's budget (Phase 8 handles auto-budget creation)
|
|
- After completion: redirect to `/` (dashboard) with success toast "Template created! Your first budget will appear automatically."
|
|
|
|
### Skip & State Persistence
|
|
- "Skip" button on each step + global "Skip setup" to exit wizard entirely without creating data
|
|
- Wizard state persisted in localStorage keyed by user_id — survives page refresh
|
|
- On complete or skip: clear localStorage, mark profiles.setup_completed = true
|
|
- Refreshing mid-wizard restores the wizard at the correct step
|
|
|
|
### Claude's Discretion
|
|
- Exact component decomposition (how many sub-components for the wizard)
|
|
- Animation/transition between steps (if any)
|
|
- Exact styling of category badges and grouping headers
|
|
- Toast message wording variations
|
|
- Error handling UX for failed API calls during completion
|
|
|
|
</decisions>
|
|
|
|
<code_context>
|
|
## Existing Code Insights
|
|
|
|
### Reusable Assets
|
|
- `src/hooks/useFirstRunState.ts` — detects first-run users (isFirstRun + loading)
|
|
- `src/hooks/useCategories.ts` — CRUD for categories (create method available)
|
|
- `src/hooks/useTemplate.ts` — CRUD for template items (createItem method available)
|
|
- `src/hooks/useAuth.ts` — profile access (currency, locale)
|
|
- `src/data/presets.ts` — 19 PresetItem entries with slug, type, defaultAmount, item_tier
|
|
- `src/components/ui/card.tsx` — Card component
|
|
- `src/components/ui/button.tsx` — Button component
|
|
- `src/components/ui/input.tsx` — Input component
|
|
- `src/components/ui/badge.tsx` — Badge component (for category type indicators)
|
|
- `src/components/ui/sonner.tsx` — Toast notifications
|
|
- `src/i18n/en.json` + `de.json` — presets.* keys already translated
|
|
|
|
### Established Patterns
|
|
- Pages are in `src/pages/*.tsx`, routed via React Router
|
|
- Hooks use React Query with Supabase client
|
|
- Category types: income, bill, variable_expense, debt, saving, investment
|
|
- UI uses Tailwind + shadcn/ui components with OKLCH pastel design tokens
|
|
- Auth-protected routes via layout wrapper
|
|
|
|
### Integration Points
|
|
- Router: Add `/setup` route, redirect logic in dashboard or layout
|
|
- `useFirstRunState()` — gate for redirect (check !loading && isFirstRun)
|
|
- `useCategories().create` — create categories on wizard completion
|
|
- `useTemplate().createItem` — create template items on wizard completion
|
|
- `profiles.setup_completed` — mark true on completion/skip via Supabase update
|
|
|
|
</code_context>
|
|
|
|
<specifics>
|
|
## Specific Ideas
|
|
|
|
- Pre-filled common items come from the existing PRESETS array (19 items, already i18n'd)
|
|
- The "remaining to allocate" balance = income entered in step 1 minus sum of checked item amounts in step 2
|
|
- Wizard must not create duplicate categories if user already has some (edge case: user skipped wizard, manually created categories, then somehow re-enters wizard)
|
|
- Phase 6 decisions: round EUR amounts, backfill existing users to setup_completed=true (they never see wizard)
|
|
|
|
</specifics>
|
|
|
|
<deferred>
|
|
## Deferred Ideas
|
|
|
|
None — discussion stayed within phase scope.
|
|
|
|
</deferred>
|