# 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, smart task delete (soft/hard), intuitive frequency picker with shortcuts, anytime task completion regardless of schedule, and recurring task pre-population across interval windows with muted styling. 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.

## Current State

Shipped v1.2 (2026-04-03). All milestone goals achieved across 4 phases, 6 plans, 14 requirements.

**v1.2 delivered:** Smart task delete, intuitive frequency picker, dead code cleanup, anytime task completion, and recurring task pre-population with muted visual styling.

## 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
- Task delete with smart soft/hard behavior — v1.2 (Phase 8)
- Task creation frequency picker UX rework — v1.2 (Phase 9)
- Dead code cleanup (v1.0 daily plan files) — v1.2 (Phase 10)
- Anytime task completion with today-based nextDueDate recalculation — v1.2 (Phase 11)
- Recurring task pre-population on all interval days with muted styling — v1.2 (Phase 11)

### Active

- [ ] Data export/import (JSON) — deferred
- [ ] English localization — deferred

### 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
- Room cover photos from camera or gallery — dropped, clean design preferred
- Statistics & insights dashboard — v2.0
- Onboarding wizard — v2.0
- Custom accent color picker — v2.0

## Context

- Shipped v1.2 with 13,232 LOC Dart (lib + test), Drift schema v3
- 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.2
- Gitea (self-hosted on Hetzner) for version control; no CI/CD pipeline yet
- v1.0 dead code cleaned up in Phase 10 (DailyPlanDao preserved for 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 |
| isActive soft-delete over row deletion | Preserve completion history for future statistics | Good — BoolColumn.withDefault(true) auto-migrates existing rows |
| Shortcut chips + freeform picker | Replace 10-chip grid with intuitive "Every N unit" | Good — fewer taps, picker is single source of truth |
| Query-time virtual instances for pre-population | No schema migration, provider-layer only | Good — interval-window logic in providers, zero DB changes |
| Today-based nextDueDate on non-due completion | User expects next occurrence relative to today, not original schedule | Good — simple baseDate swap in tasks_dao |
| 0.55 Opacity for pre-populated tasks | Muted distinction without custom painting | Good — clear visual hierarchy between due/overdue/upcoming |

---
*Last updated: 2026-04-03 after v1.2 milestone*
