flutter-ai-starter / rules

---
description: Architecture, folder layout, layering, and dependency rules
globs: ["lib/**/*.dart", "test/**/*.dart", "supabase/**/*.{sql,ts}"]
alwaysApply: false
---

# Architecture

## Stack (company default — pin versions in each app's `pubspec.yaml`)

| Layer | Choice |
|---|---|
| Mobile | Flutter stable, Dart 3.x |
| State & DI | **`package:provider`** + **`ChangeNotifier`** ViewModels |
| Routing | **go_router** (declarative; `context.go` / `context.push`) |
| Models | **freezed** + **json_serializable** (sealed unions for errors/states) |
| HTTP | dio + supabase_flutter (when backend enabled) |
| Local | hive_ce, flutter_secure_storage |

Use `build_runner` for **codegen only** — freezed, json_serializable, and Mockito mocks (`generate-mocks` skill). Not for state management (no Riverpod/codegen DI).

Do not introduce other state managers (Riverpod, Bloc, GetX, GetIt) or ORMs without user approval and an entry in `docs/DECISIONS.md`.

## Pattern: feature-first MVVM (Flutter official)

Organize by **feature**, not by file type. Matches [Flutter app architecture](https://docs.flutter.dev/app-architecture):

| Layer | Folder | Role |
|---|---|---|
| View | `presentation/screens`, `widgets` | UI only — observes ViewModel |
| ViewModel | `presentation/view_models` | `ChangeNotifier` — screen state & commands |
| Model | `data/` + optional `domain/` | Repositories, services, DTOs, entities |

**Domain layer (`domain/`)** — optional; see `docs/ARCHITECTURE.md` for when to skip vs add.

## Folder layout

```
lib/
  main.dart                  # entrypoint — calls bootstrap(), then runApp
  bootstrap.dart             # binding init, zone/error handling, flavor setup
  app/                       app.dart, router.dart, theme.dart, dependencies.dart
  core/                      config/ errors/ logging/ network/ storage/ utils/
  design_system/             tokens/ theme/ components/
  features/<feature>/
    data/                    repositories/, services/, models/
    domain/                  entities/, use_cases/          # optional
    presentation/            view_models/, screens/, widgets/
  services/                  analytics/ crash/ push/
  l10n/
```

## Dependency injection

- Wire dependencies in `app/dependencies.dart` with `MultiProvider` at the root (`runApp`).
- Expose **services** and **repositories** as `Provider<T>`.
- Expose **ViewModels** as `ChangeNotifierProvider<T>` (or `.value` in tests).
- Inject into ViewModels via constructor — use `context.read()` in `create:` callbacks, not globals.
- ViewModels receive repositories as **private** constructor params — views must not call repositories directly.

## Layering

- **Direction:** `presentation → domain (optional) → data`. Never the reverse.
- **Services** wrap one data source each. No state.
- **Repositories** orchestrate services. **Must not depend on each other.**
- Widgets never import `data/` directly.
- Cross-cutting services in `lib/services/` registered in `dependencies.dart`.
- Feature A never imports `features/feature_b/`.

## go_router + provider

- Create `GoRouter` in `app/router.dart`.
- Inject repositories/ViewModels in route `builder`s via `context.read()`.
- Auth redirect: pass a `ChangeNotifier` (or `Listenable`) as `refreshListenable` on `GoRouter` — call `notifyListeners()` when auth state changes.
- Do not rebuild the entire router reactively on every frame.

## Rules

- One screen / ViewModel / repository per file.
- `freezed` for DTOs, entities, sealed `Failure` / UI state unions.
- Repositories return `Future<Result<T, Failure>>`.
- No `Supabase.instance.client` from widgets — inject via `Provider`.
- No AI vendor SDK on client — backend Edge Functions when AI is enabled.
- No singletons via `static`.
- No business logic in `build()`.
- `setState` only for local ephemeral UI (focus, animation controllers).

## Before implementing

- Check for duplicate functionality and reuse opportunities.
- Files: `snake_case.dart`; classes: `PascalCase`; ViewModels: `<Feature>ViewModel`.

See `docs/ARCHITECTURE.md` and `docs/DECISIONS.md`.