TaskManagerMobile/CLAUDE.md

KittieMobile — CLAUDE.md

Project Overview

KittieMobile is an ADHD-friendly task manager with a virtual pet companion. Users manage tasks while caring for a pet (dog, cat, or capybara) that reacts to task completion and daily energy levels. The app is offline-first with optional sync to a remote backend.

Tech Stack

• Frontend: Flutter 3.x (Dart 3.x), targeting iOS and Android
• State Management: Riverpod 3.x (flutter_riverpod + riverpod_annotation + riverpod_generator)
• Local Database: Drift 2.x (SQLite, offline-first; mirrors the PostgreSQL schema)
• Animations: Rive 0.14.x (pet animations via .riv files in assets/animations/)
• Navigation: go_router 17.x
• Fonts: Google Fonts (Lexend, Atkinson Hyperlegible)
• Notifications: flutter_local_notifications 21.x
• Remote Sync: http package to backend REST API at localhost:8090

Architecture

Feature-first structure with clean separation of concerns:

lib/
  core/
    constants/    # App-wide constants (colors, sizes, durations, energy levels)
    theme/        # ThemeData, color scheme, text styles
    router/       # go_router configuration and route name constants
  data/
    models/       # Drift table definitions and generated data classes
    repositories/ # Data access layer (abstracts Drift + HTTP)
    db/           # Drift database class and migration strategy
  domain/
    entities/     # Pure Dart domain entities (decoupled from DB schema)
    use_cases/    # Business logic (complete task, reset day, sync, etc.)
  pet/            # Pet engine: mood state machine, Rive controller, reward logic
  features/
    tasks/        # Task CRUD, list view, detail/edit screens
      screens/
      widgets/
      providers/
    onboarding/   # First-run flow: name input, pet selection (dog/cat/capybara)
      screens/
      widgets/
      providers/
    zen_mode/     # Distraction-free single-task view
      screens/
      widgets/
      providers/
    daily_reset/  # Morning check-in: energy level selection (1-3)
      screens/
      widgets/
      providers/
  shared/
    widgets/      # Reusable UI components (EnergyBadge, TaskCard, PetDisplay)
    utils/        # Date helpers, formatters, extensions
assets/
  animations/     # .riv pet animation files (per pet type and mood)
  fonts/          # Custom font files (if self-hosted; otherwise use google_fonts)

Ports & Infrastructure

Service	Port	Notes
Backend REST API	localhost:8090	Remote sync target
PostgreSQL	5432 (Docker internal), 5439 (host-mapped)	via docker-compose

API base URL: http://localhost:8090/api/v1/

Widget API Patterns

• Dual-param widgets: shared/widgets/ accept both entity param (e.g. task: TaskEntity?) AND individual raw params — private getters resolve which to use. Keep backward compat when extending.
• PetType canonical location: domain/entities/pet_type.dart — never redeclare locally.
• todayTasksProvider is a top-level alias for tasksProvider (no date filter in MVP).
• Pet identity vs. pet state: petType/petName belong to userProvider; petStateProvider tracks energy/streak/rewards only.

Naming Conventions

• Files: snake_case.dart
• Classes: PascalCase
• Riverpod providers: camelCaseProvider / camelCaseNotifier
• Drift tables: class PascalCase, column names camelCase (maps to snake_case in DB)
• Feature structure: each features/X/ dir contains screens/, widgets/, providers/
• Route names: string constants in core/router/routes.dart
• Use cases: VerbNounUseCase e.g. CompleteTaskUseCase, ResetDayUseCase

Build Commands

# Install dependencies
flutter pub get

# Generate code (Drift tables + Riverpod providers)
dart run build_runner build --delete-conflicting-outputs

# Watch mode (during development)
dart run build_runner watch --delete-conflicting-outputs

# Run on connected device/emulator
flutter run

# Static analysis
flutter analyze

# Run tests
flutter test

# Check environment
flutter doctor

Database Schema (Drift mirrors PostgreSQL)

Tables:

• users — device identity, pet selection (dog/cat/capybara), pet name
• tasks — title, description, energy_level (1-3), status (pending/done/snoozed/someday/archived), deadline, photo_path, sort_order, synced_at, local_id
• pet_state — energy_today (1-3), streak_days, total_tasks_done, unlocked_items
• task_completions — completion log for rewards and analytics

Energy levels: 1 = low, 2 = medium, 3 = high

Sync Strategy

• Drift local SQLite is the source of truth on device
• synced_at and local_id columns on tasks track sync state
• data/repositories/sync_repository.dart pushes unsynced tasks to localhost:8090
• Conflict resolution: last-write-wins on updated_at

Package Versions (as of project init)

• flutter_riverpod: ^3.0.0 (3.3.1)
• riverpod_annotation: ^4.0.0 (4.0.2)
• riverpod_generator: ^4.0.0 (4.0.3)
• drift: ^2.22.0 (2.32.0)
• drift_flutter: ^0.2.0 (0.3.0)
• drift_dev: ^2.22.0 (2.32.0)
• go_router: ^17.0.0 (17.1.0)
• rive: ^0.14.0 (0.14.4)
• google_fonts: ^8.0.0 (8.0.2)
• flutter_local_notifications: ^21.0.0 (21.0.0)