makiolaj/HouseHoldKeaper
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

docs(01-01): complete project scaffold plan

Browse Source 
- SUMMARY.md with execution results, deviations, and self-check
- STATE.md updated with position and decisions
- ROADMAP.md updated with Phase 1 progress (1/2)
- REQUIREMENTS.md: FOUND-01, FOUND-02, FOUND-03, THEME-01, THEME-02 marked complete

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Jean-Luc Makiola
2026-03-15 20:02:08 +01:00
parent 51738f78bc
commit cd1ce21f3f
3 changed files with 195 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
.planning/REQUIREMENTS.md
View File

@@ -51,14 +51,14 @@ Requirements for initial release. Each maps to roadmap phases.
### Theme & UI ### Theme & UI
- [ ] **THEME-01**: App supports light and dark themes, following the system setting by default - [x] **THEME-01**: App supports light and dark themes, following the system setting by default
- [ ] **THEME-02**: App uses a calm Material 3 palette with muted greens, warm grays, and gentle blues - [x] **THEME-02**: App uses a calm Material 3 palette with muted greens, warm grays, and gentle blues
### Foundation ### Foundation
- [ ] **FOUND-01**: App uses Drift for local SQLite storage with proper schema migration workflow - [x] **FOUND-01**: App uses Drift for local SQLite storage with proper schema migration workflow
- [ ] **FOUND-02**: App uses Riverpod 3 for state management with code generation - [x] **FOUND-02**: App uses Riverpod 3 for state management with code generation
- [ ] **FOUND-03**: App uses localization infrastructure (ARB files + AppLocalizations) with German locale, even though only one language ships in v1 - [x] **FOUND-03**: App uses localization infrastructure (ARB files + AppLocalizations) with German locale, even though only one language ships in v1
- [ ] **FOUND-04**: Bottom navigation with tabs: Home (Daily Plan), Rooms, Settings - [ ] **FOUND-04**: Bottom navigation with tabs: Home (Daily Plan), Rooms, Settings
## v2 Requirements ## v2 Requirements
@@ -119,12 +119,12 @@ Which phases cover which requirements. Updated during roadmap creation.
| Requirement | Phase | Status | | Requirement | Phase | Status |
|-------------|-------|--------| |-------------|-------|--------|
| FOUND-01 | Phase 1: Foundation | Pending | | FOUND-01 | Phase 1: Foundation | Complete |
| FOUND-02 | Phase 1: Foundation | Pending | | FOUND-02 | Phase 1: Foundation | Complete |
| FOUND-03 | Phase 1: Foundation | Pending | | FOUND-03 | Phase 1: Foundation | Complete |
| FOUND-04 | Phase 1: Foundation | Pending | | FOUND-04 | Phase 1: Foundation | Pending |
| THEME-01 | Phase 1: Foundation | Pending | | THEME-01 | Phase 1: Foundation | Complete |
| THEME-02 | Phase 1: Foundation | Pending | | THEME-02 | Phase 1: Foundation | Complete |
| ROOM-01 | Phase 2: Rooms and Tasks | Pending | | ROOM-01 | Phase 2: Rooms and Tasks | Pending |
| ROOM-02 | Phase 2: Rooms and Tasks | Pending | | ROOM-02 | Phase 2: Rooms and Tasks | Pending |
| ROOM-03 | Phase 2: Rooms and Tasks | Pending | | ROOM-03 | Phase 2: Rooms and Tasks | Pending |

24
.planning/STATE.md
View File

@@ -10,28 +10,28 @@ See: .planning/PROJECT.md (updated 2026-03-15)
## Current Position ## Current Position
Phase: 1 of 4 (Foundation) Phase: 1 of 4 (Foundation)
Plan: 0 of TBD in current phase Plan: 1 of 2 in current phase
Status: Ready to plan Status: Executing
Last activity: 2026-03-15 — Roadmap created, all 4 phases defined, 30 requirements mapped Last activity: 2026-03-15 — Completed 01-01-PLAN.md (project scaffold, core infrastructure, tests)
Progress: [░░░░░░░░░░] 0% Progress: [█░░░░░░░░░] 10%
## Performance Metrics ## Performance Metrics
**Velocity:** **Velocity:**
- Total plans completed: 0 - Total plans completed: 1
- Average duration: - - Average duration: 7 min
- Total execution time: 0 hours - Total execution time: 0.1 hours
**By Phase:** **By Phase:**
| Phase | Plans | Total | Avg/Plan | | Phase | Plans | Total | Avg/Plan |
|-------|-------|-------|----------| |-------|-------|-------|----------|
| - | - | - | - | | 1 - Foundation | 1 | 7 min | 7 min |
**Recent Trend:** **Recent Trend:**
- Last 5 plans: none yet - Last 5 plans: 01-01 (7 min)
- Trend: - - Trend: baseline
*Updated after each plan completion* *Updated after each plan completion*
@@ -47,6 +47,8 @@ Recent decisions affecting current work:
- [Pre-phase]: German-only UI for MVP; localization infrastructure (ARB + AppLocalizations) required from Phase 1 even with one locale - [Pre-phase]: German-only UI for MVP; localization infrastructure (ARB + AppLocalizations) required from Phase 1 even with one locale
- [Pre-phase]: riverpod_lint must be active before any feature code — catches ref.watch outside build() at analysis time - [Pre-phase]: riverpod_lint must be active before any feature code — catches ref.watch outside build() at analysis time
- [Pre-phase]: drift_dev make-migrations workflow must be established in Phase 1 — recovery cost is data loss - [Pre-phase]: drift_dev make-migrations workflow must be established in Phase 1 — recovery cost is data loss
- [01-01]: Pinned drift/drift_dev to 2.31.0 for analyzer ^9.0.0 compatibility with riverpod_generator 4.0.3
- [01-01]: Generated Riverpod 3 provider named themeProvider (not themeNotifierProvider) per new naming convention
### Pending Todos ### Pending Todos
@@ -61,5 +63,5 @@ None yet.
## Session Continuity ## Session Continuity
Last session: 2026-03-15 Last session: 2026-03-15
Stopped at: Roadmap created — ready to plan Phase 1 Stopped at: Completed 01-01-PLAN.md -- ready for 01-02-PLAN.md
Resume file: None Resume file: None

172
.planning/phases/01-foundation/01-01-SUMMARY.md Normal file
View File

@@ -0,0 +1,172 @@
---
phase: 01-foundation
plan: 01
subsystem: infra
tags: [flutter, drift, riverpod, material3, arb-localization, sqlite]
# Dependency graph
requires: []
provides:
- Flutter project scaffold with all Phase 1 dependencies resolved
- Drift AppDatabase with schemaVersion 1 and migration workflow established
- Riverpod providers with @riverpod code generation working
- Light and dark ThemeData with sage green seed and warm surface overrides
- ThemeNotifier with SharedPreferences persistence
- German ARB localization file with 15 keys for Phase 1 UI
- Wave 0 test suite (14 tests) covering database, theme, and localization
affects: [01-02, 02-rooms-and-tasks]
# Tech tracking
tech-stack:
added: [flutter_riverpod 3.3.1, riverpod_annotation 4.0.2, drift 2.31.0, drift_flutter 0.2.8, go_router 17.1.0, path_provider 2.1.5, shared_preferences 2.5.4, flutter_localizations, intl, riverpod_generator 4.0.3, drift_dev 2.31.0, build_runner 2.12.2]
patterns: [@riverpod code generation, Drift database with migration workflow, ColorScheme.fromSeed with surface overrides, ARB-based localization]
key-files:
created:
- pubspec.yaml
- analysis_options.yaml
- build.yaml
- l10n.yaml
- lib/core/database/database.dart
- lib/core/providers/database_provider.dart
- lib/core/theme/app_theme.dart
- lib/core/theme/theme_provider.dart
- lib/l10n/app_de.arb
- drift_schemas/household_keeper/drift_schema_v1.json
- test/core/database/database_test.dart
- test/core/theme/color_scheme_test.dart
- test/core/theme/theme_test.dart
- test/l10n/localization_test.dart
modified:
- lib/main.dart
key-decisions:
- "Pinned drift/drift_dev to 2.31.0 (not 2.32.0) for analyzer ^9.0.0 compatibility with riverpod_generator 4.0.3"
- "Generated provider named themeProvider (Riverpod 3 naming convention), not themeNotifierProvider"
patterns-established:
- "@riverpod annotation with build_runner code generation for all providers"
- "Drift database with optional QueryExecutor for test injection (NativeDatabase.memory())"
- "ColorScheme.fromSeed with .copyWith() for warm surface overrides"
- "SharedPreferences for lightweight settings persistence"
- "ARB-based localization with German as template language"
requirements-completed: [FOUND-01, FOUND-02, FOUND-03, THEME-01, THEME-02]
# Metrics
duration: 7min
completed: 2026-03-15
---
# Phase 1 Plan 01: Project Scaffold Summary
**Drift database (schema v1) with migration workflow, Riverpod 3 providers with code generation, sage & stone Material 3 theme, and German ARB localization -- 14 Wave 0 tests passing**
## Performance
- **Duration:** 7 min
- **Started:** 2026-03-15T18:52:57Z
- **Completed:** 2026-03-15T18:59:57Z
- **Tasks:** 2
- **Files modified:** 17
## Accomplishments
- Flutter project scaffolded with all runtime and dev dependencies resolved
- Drift AppDatabase with schemaVersion 1 and make-migrations workflow capturing drift_schema_v1.json
- Riverpod providers generated via @riverpod annotation (database_provider, theme_provider)
- Light and dark themes with sage green seed (0xFF7A9A6D) and warm stone/charcoal surface overrides
- ThemeNotifier defaults to ThemeMode.system with SharedPreferences persistence
- Full German ARB localization with 15 keys covering all Phase 1 screens (proper umlauts)
- 14 Wave 0 tests all passing: database (3), color scheme (6), theme switching (3), localization (2)
## Task Commits
Each task was committed atomically:
1. **Task 1: Create Flutter project and configure all dependencies and tooling** - `4b27aea` (chore)
2. **Task 2: Create core infrastructure, localization strings, and Wave 0 test scaffolding** - `51738f7` (feat)
## Files Created/Modified
- `pubspec.yaml` - All dependencies (flutter_riverpod, drift, go_router, etc.)
- `analysis_options.yaml` - riverpod_lint plugin configuration
- `build.yaml` - Drift code generation configuration
- `l10n.yaml` - ARB localization configuration (German template)
- `lib/core/database/database.dart` - AppDatabase class with schemaVersion 1
- `lib/core/database/database.g.dart` - Generated Drift database code
- `lib/core/providers/database_provider.dart` - Riverpod provider for AppDatabase
- `lib/core/providers/database_provider.g.dart` - Generated provider code
- `lib/core/theme/app_theme.dart` - Light and dark ThemeData with sage & stone palette
- `lib/core/theme/theme_provider.dart` - ThemeNotifier with SharedPreferences persistence
- `lib/core/theme/theme_provider.g.dart` - Generated theme provider code
- `lib/l10n/app_de.arb` - German localization strings (15 keys)
- `lib/l10n/app_localizations.dart` - Generated localization delegate
- `lib/l10n/app_localizations_de.dart` - Generated German localization implementation
- `lib/main.dart` - Minimal ProviderScope placeholder
- `drift_schemas/household_keeper/drift_schema_v1.json` - Schema v1 migration capture
- `test/core/database/database_test.dart` - Database unit tests (FOUND-01)
- `test/core/theme/color_scheme_test.dart` - ColorScheme unit tests (THEME-02)
- `test/core/theme/theme_test.dart` - Theme switching tests (THEME-01)
- `test/l10n/localization_test.dart` - Localization widget tests (FOUND-03)
## Decisions Made
- **drift/drift_dev pinned to 2.31.0:** drift_dev 2.32.0 requires analyzer ^10.0.0 which is incompatible with riverpod_generator 4.0.3's analyzer ^9.0.0. Downgrading to 2.31.0 (analyzer >=8.1.0 <11.0.0) resolves the conflict with no functional difference for Phase 1.
- **Riverpod 3 provider naming:** Generated provider is `themeProvider` (not `themeNotifierProvider`) per Riverpod 3 naming convention where the Notifier suffix is dropped.
## Deviations from Plan
### Auto-fixed Issues
**1. [Rule 3 - Blocking] Resolved analyzer version conflict between drift_dev and riverpod_generator**
- **Found during:** Task 1 (dependency installation)
- **Issue:** drift_dev 2.32.0 requires analyzer ^10.0.0, riverpod_generator 4.0.3 requires analyzer ^9.0.0 -- mutually exclusive
- **Fix:** Pinned drift to 2.31.0 and drift_dev to 2.31.0 (analyzer >=8.1.0 <11.0.0, compatible with ^9.0.0)
- **Files modified:** pubspec.yaml
- **Verification:** flutter pub get succeeds, all code generation works
- **Committed in:** 4b27aea (Task 1 commit)
**2. [Rule 3 - Blocking] Created l10n directory and minimal ARB file for flutter pub get**
- **Found during:** Task 1 (dependency verification)
- **Issue:** l10n.yaml references lib/l10n/app_de.arb which doesn't exist yet, causing flutter pub get to fail
- **Fix:** Created lib/l10n/ directory with minimal ARB file (expanded in Task 2)
- **Files modified:** lib/l10n/app_de.arb
- **Verification:** flutter pub get succeeds without localization errors
- **Committed in:** 4b27aea (Task 1 commit)
**3. [Rule 1 - Bug] Fixed provider name in theme tests**
- **Found during:** Task 2 (test creation)
- **Issue:** Test used `themeNotifierProvider` but Riverpod 3 generates `themeProvider`
- **Fix:** Updated all test references from `themeNotifierProvider` to `themeProvider`
- **Files modified:** test/core/theme/theme_test.dart
- **Verification:** dart analyze clean, flutter test passes
- **Committed in:** 51738f7 (Task 2 commit)
---
**Total deviations:** 3 auto-fixed (1 bug, 2 blocking)
**Impact on plan:** All auto-fixes necessary for dependency resolution and test correctness. No scope creep.
## Issues Encountered
- Default widget_test.dart referenced removed MyApp class -- deleted as part of Task 2
- Generated database.g.dart has unused field warning (_db) -- this is in auto-generated code and cannot be fixed
## User Setup Required
None - no external service configuration required.
## Next Phase Readiness
- All core infrastructure ready for Plan 02 (navigation shell, placeholder screens, settings, full app wiring)
- Drift database ready to receive tables in Phase 2
- Riverpod code generation pipeline established
- Theme and localization ready for UI consumption
- riverpod_lint active (warnings appear in dart analyze output)
## Self-Check: PASSED
- All 20 key files verified present on disk
- Both task commits verified in git log (4b27aea, 51738f7)
- 14/14 tests passing (flutter test)
- dart analyze: 0 errors (2 warnings in generated code only)
---
*Phase: 01-foundation*
*Completed: 2026-03-15*