## PlayMaker — guidance for AI coding assistants

This file gives focused, actionable knowledge to quickly make safe edits in the PlayMaker Flutter app.

Key facts (big picture)
- App: Flutter (mobile + desktop) using Supabase for backend and SharedPreferences for local persistence.
- Data ownership: teams are per-user (teams.user_id). Team records include fields like `id`, `name`, `image_url`, `wins`, `losses`, `draws`, `is_favorite`.
- Global selection: the app exposes a single global active team via `lib/controllers/active_team.dart` — a `ValueNotifier<ActiveTeam?>` named `globalActiveTeam`. Use `loadGlobalTeam()` and `saveGlobalTeam()` to read/update both local (SharedPreferences) and Supabase (`profiles.selected_team_id`).

Where to look (important files)
- `lib/controllers/active_team.dart` — central logic: load/save active team, prefers favorite team after our recent change.
- `lib/controllers/team_controller.dart` — creates teams, toggles favorites and exposes `teamsStream` for realtime listing.
- `lib/pages/home.dart` — main UI that shows the selected team, reads/writes last_team_* prefs and uses `TeamController` streams.
- `lib/pages/status_page.dart` — shows detailed stats and accepts initialTeam* props; will use the same persistence keys as `home.dart` as a fallback.
- `lib/widgets/*.dart` — UI building blocks (game, placar, team widgets) that assume team names/logos are strings and use `globalActiveTeam`/selectedTeam state.

Project-specific conventions & patterns
- Single active team: stored locally under prefs keys `last_team_id`, `last_team_name`, `last_team_logo`, `last_team_wins`, `last_team_losses`, `last_team_draws`.
- Realtime lists: controllers expose Streams from Supabase (e.g., `teamsStream`) and UI uses `StreamBuilder`/`snapshot.data` expecting List<Map<String,dynamic>>.
- Favoriting: `teams.is_favorite` is a boolean; code expects at most one favorite per user. When marking favorite, clear other favorites for that user and set the favorite as the global active team (we updated `team_controller.toggleFavorite` to do this).
- Global state: prefer using `globalActiveTeam` instead of ad-hoc SharedPreferences reads when changing the current team — it notifies Home and Status pages automatically.
- Naming: Portuguese UI strings are used throughout (e.g., "Selecionar Equipa"), so preserve that when editing visible text.

Examples of common edits
- Changing how the active team is chosen: edit `loadGlobalTeam()` in `lib/controllers/active_team.dart`. Example behaviour implemented: prefer `teams.is_favorite == true`, then fallback to `profiles.selected_team_id`, then local prefs.
- Adding a field to teams: update Supabase schema, then adapt `TeamController.getTeamsWithStats()` and UI widgets under `lib/widgets/` to read the new field.
- Making UI reactive to team changes: call `saveGlobalTeam(ActiveTeam(...))` to update memory, Supabase profile and notify UI.

Developer workflows (how to build/test/debug)
- Install dependencies: `flutter pub get`.
- Run on iOS simulator: `flutter run -d ios` (macOS only). Android: `flutter run -d android`.
- Quick analyzer: `flutter analyze` or rely on the project's editor diagnostics.
- Running tests: There is a `test/widget_test.dart` — run `flutter test` to execute.
- When debugging Supabase flows locally, ensure `google-services.json` (Android) and iOS config files are present under `android/app/` and `ios/` as appropriate.

Safe-edit checklist for AI agents
- Prefer small, focused patches. Keep existing structure and naming conventions (Portuguese strings, `prefs` keys and Supabase table names).
- When touching team selection: update both local prefs and Supabase `profiles.selected_team_id` (use `saveGlobalTeam`).
- When changing persistence keys, update both `home.dart` and `status_page.dart` and `active_team.dart`.
- Avoid altering app-wide themes or widget contracts unless necessary; many widgets rely on team names/logos being non-null strings.
- If adding Supabase queries, filter by `user_id` unless deliberately global.

If you can't find something
- Search for the pref keys `last_team_id` / `last_team_name` / `last_team_logo` to locate all usages.
- Look for `globalActiveTeam` to see places that react to the active team.

Contact / next steps
- After applying changes that affect team selection flow, run `flutter analyze` and (if possible) `flutter test`.
- Ask for confirmation before changing user-visible Portuguese copy or database schema.

— end of guidance —