PlayMaker/.github/copilot-instructions.md

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 —