From 843261d321e7f8744a606efb109ddfae66dc3644 Mon Sep 17 00:00:00 2001
From: Jean-Luc Makiola <business@jeanlucmakiola.de>
Date: Mon, 20 Apr 2026 17:38:01 +0200
Subject: [PATCH] docs(06): smart discuss context

---
 .../06-CONTEXT.md                             | 81 +++++++++++++++++++
 1 file changed, 81 insertions(+)
 create mode 100644 .planning/phases/06-preset-data-first-run-detection-and-db-safety/06-CONTEXT.md

diff --git a/.planning/phases/06-preset-data-first-run-detection-and-db-safety/06-CONTEXT.md b/.planning/phases/06-preset-data-first-run-detection-and-db-safety/06-CONTEXT.md
new file mode 100644
index 0000000..1cf8200
--- /dev/null
+++ b/.planning/phases/06-preset-data-first-run-detection-and-db-safety/06-CONTEXT.md
@@ -0,0 +1,81 @@
+# Phase 6: Preset Data, First-Run Detection, and DB Safety - Context
+
+**Gathered:** 2026-04-20
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+The data layer is safe and ready — duplicate budget/category writes are impossible at the DB level, and the app correctly identifies first-run users. This phase delivers: DB uniqueness constraints, a setup_completed column with backfill migration, a useFirstRunState hook, and a preset budget item library (~15-20 items with i18n).
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Preset Library Content
+- Default amounts in EUR (matches existing profiles.currency default)
+- 4 income, 4 bill, 5 variable_expense, 2 debt, 2 saving, 2 investment items (~19 total)
+- i18n key format: `presets.{category_type}.{slug}` (e.g., `presets.bill.rent`)
+- Round number amounts (e.g., rent=1000, groceries=400) — easier to adjust, less presumptuous
+
+### First-Run Detection Logic
+- First-run triggers when user has zero categories OR zero template items (either missing = not set up)
+- New dedicated hook: `src/hooks/useFirstRunState.ts` (follows useCategories/useTemplate pattern)
+- Backfill via Supabase migration SQL: `UPDATE profiles SET setup_completed = true WHERE id IN (SELECT DISTINCT user_id FROM categories)`
+- Hook derives state from existing hooks (useCategories count + useTemplate items count) — no extra network call
+
+### DB Migration & Constraint Strategy
+- Cleanup step before adding unique constraints (deduplicate existing data safely)
+- Separate migration files: `006_uniqueness_constraints.sql` and `007_setup_completed.sql`
+- `setup_completed` column defaults to `false` — new signups start as not-setup; existing users backfilled to `true`
+- Unique constraint on budgets: `(user_id, start_date)` only — end_date always derived
+
+### Claude's Discretion
+- Exact preset item names and amounts (within the balanced category distribution)
+- German translation text for preset i18n keys
+- Order of migration operations within each file
+- Error handling approach for constraint violations in application code
+
+</decisions>
+
+<code_context>
+## Existing Code Insights
+
+### Reusable Assets
+- `src/hooks/useCategories.ts` — existing hook pattern to follow for useFirstRunState
+- `src/hooks/useTemplate.ts` — template data access, can derive "has template items" from this
+- `src/lib/types.ts` — type definitions for categories, templates, budgets
+- `supabase/migrations/001-005` — existing migration chain to extend
+
+### Established Patterns
+- Hooks use React Query with Supabase client
+- Category types enum: income, bill, variable_expense, debt, saving, investment
+- Template items reference categories via category_id
+- Profiles table auto-created via trigger on auth.users insert
+
+### Integration Points
+- `profiles` table needs new `setup_completed` boolean column
+- `budgets` table needs unique constraint on (user_id, start_date)
+- `categories` table needs unique constraint on (user_id, name)
+- New `src/data/presets.ts` file for preset library
+- New `src/hooks/useFirstRunState.ts` for first-run detection
+- i18n files need preset translation keys (en + de)
+
+</code_context>
+
+<specifics>
+## Specific Ideas
+
+- Currency column in profiles is already `currency text not null default 'EUR'` — confirmed in 001_profiles.sql
+- The `handle_new_user()` trigger creates profiles on signup — setup_completed will be false by default for new users
+- Templates table already has `unique(user_id)` — one template per user is enforced
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+None — discussion stayed within phase scope.
+
+</deferred>