HouseHoldKeaper/.planning/PROJECT.md

HouseHoldKeaper

What This Is

A local-first Flutter app for organizing household chores, built for personal/couple use on Android. Uses a room-based task scheduling model where users create rooms, add recurring tasks with frequency intervals, and the app auto-calculates the next due date after each completion. Features a horizontal calendar strip home screen with day-by-day task navigation, task completion history, configurable sorting (alphabetical, interval, effort), bundled German-language task templates, room cleanliness indicators, and daily summary notifications. Fully offline, free, privacy-respecting — all data stays on-device.

Core Value

Users can see what needs doing today, mark it done, and trust the app to schedule the next occurrence — without thinking about it.

Requirements

Validated

• Room CRUD with icons and drag-and-drop reorder — v1.0
• Task CRUD with frequency intervals and due date calculation — v1.0
• Daily plan view with overdue/today/upcoming sections — v1.0
• Task completion with auto-scheduling of next due date — v1.0
• Bundled task templates per room type (German only, 14 room types) — v1.0
• Daily summary notification with configurable time — v1.0
• Light/dark theme with calm Material 3 palette — v1.0
• Cleanliness indicator per room (based on overdue vs on-time) — v1.0
• Horizontal calendar strip home screen replacing stacked daily plan — v1.1
• Overdue task carry-over with red/orange visual accent — v1.1
• Task completion history with per-task reverse-chronological log — v1.1
• Alphabetical, interval, and effort task sorting with persistence — v1.1

Active

• Data export/import (JSON)
• English localization
• Room cover photos from camera or gallery

Out of Scope

• User accounts & cloud sync — local-only by design
• Leaderboards & points ranking — not a gamification app
• Subscription model / in-app purchases — free forever
• Family profile sharing across devices — single-device app
• Server-side infrastructure — zero backend
• AI-powered task suggestions — overkill for curated templates
• Per-task push notifications — daily summary is more effective
• Firebase or any Google cloud services — contradicts local-first design
• Real-time cross-device sync — potential future self-hosted feature
• Tablet-optimized layout — future enhancement
• Weekly/monthly calendar views — date strip is sufficient for task app
• Drag tasks between days — tasks auto-schedule based on frequency
• Calendar sync (Google/Apple) — contradicts local-first, offline-only design
• Statistics & insights dashboard — v2.0
• Onboarding wizard — v2.0
• Custom accent color picker — v2.0

Context

• Shipped v1.1 with 13,031 LOC Dart (9,051 lib + 3,980 test), 108 tests
• Tech stack: Flutter + Dart, Riverpod 3 + code generation, Drift 2.31 SQLite, GoRouter, flutter_local_notifications, SharedPreferences
• Inspired by BeTidy (iOS/Android household cleaning app) — room-based model, no cloud/social
• Built for personal use with partner on a shared Android device; may publish publicly later
• Code and comments in English; UI strings German-only through v1.1
• Gitea (self-hosted on Hetzner) for version control; no CI/CD pipeline yet
• Dead code from v1.0: daily_plan_providers.dart, daily_plan_task_row.dart, progress_card.dart (DailyPlanDao still used by notification service)

Constraints

• Tech stack: Flutter + Dart, Riverpod for state management, Drift for local SQLite
• Platform: Android-first (iOS later)
• Offline: 100% offline-capable, zero network dependencies
• Privacy: No data leaves the device, no analytics, no tracking
• Language: German-only UI through v1.1, English code/comments
• No CI: No automated build pipeline initially

Key Decisions

Decision	Rationale	Outcome
Riverpod 3 over Bloc	Modern, compile-safe, less boilerplate, Dart-native	Good — code generation works well, @riverpod annotation reduces boilerplate
Drift over raw sqflite	Type-safe queries, compile-time validation, migration support	Good — DAOs with stream queries provide reactive UI, migration workflow established
Android-first	Primary device is Android; iOS follows	Good — no iOS-specific issues encountered
German-only MVP	Primary user language; defer localization infrastructure	Good — ARB localization infrastructure in place from Phase 1, ready for English
No CI initially	Keep scope focused on the app itself	Good — manual dart analyze + flutter test sufficient for solo dev
Calm Material 3 palette	Muted greens, warm grays, gentle blues — calm productivity	Good — sage & stone theme (seed 0xFF7A9A6D) with warm charcoal dark mode
Clean Architecture	Feature-based folder structure with data/domain/presentation layers	Good — clear separation, easy to navigate
Calendar-anchored scheduling	Monthly/quarterly/yearly tasks anchor to original day-of-month with clamping	Good — handles Feb 28/31 edge cases correctly with anchor memory
flutter_local_notifications v21	Standard Flutter notification package, TZ-aware scheduling	Good — inexactAllowWhileIdle avoids SCHEDULE_EXACT_ALARM complexity
Manual StreamProvider for drift types	riverpod_generator throws InvalidTypeException with drift Task type	Revisit — may be fixed in future riverpod_generator versions
Calendar strip replaces daily plan	v1.1 goal — stacked overdue/today/upcoming sections replaced by horizontal 181-day strip	Good — cleaner navigation, day-by-day browsing
NotifierProvider over StateProvider	Riverpod 3.x removed StateProvider	Good — minimal Notifier subclass works cleanly
In-memory sort over SQL ORDER BY	Sort preference changes without re-querying DB	Good — stream.map applies sort after DB emit, reactive to preference changes
SharedPreferences for sort	Simple enum.name string persistence for sort preference	Good — lightweight, no DB migration needed, survives app restart
PopupMenuButton for sort UI	Material 3 AppBar action pattern, overlay menu	Good — clean integration in both HomeScreen and TaskListScreen AppBars

---

Last updated: 2026-03-16 after v1.1 milestone completed