# 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
```bash
# 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)