Sideline

Imported from WolfeLeo2/Sideline (AGENTS.md). Install upstream with npx skills add WolfeLeo2/Sideline. Copyright stays with the author.

AGENTS.md — Sideline

This file is the operational reference for all AI coding agents working on this codebase. Read this before writing any code. For full details, see docs/PRD.md.

Project Overview

Sideline is a personalized real-time sports companion app built with Flutter. It aggregates live scores, news, stats, and fantasy data — filtered through the user's personal following list.

Core value prop: One app replacing ESPN + Twitter/X + a fantasy app, showing only what the user cares about.

Tech Stack

Client (Flutter)

Backend

Infrastructure

Project Structure

lib/
├── main.dart
├── app.dart
├── core/
│   ├── constants/      # colors.dart, typography.dart, spacing.dart
│   ├── theme/           # app_theme.dart
│   ├── router/          # app_router.dart
│   └── services/        # supabase_service.dart, notification_service.dart
├── features/
│   ├── auth/
│   ├── following/
│   ├── feed/
│   ├── live_game/
│   ├── scores/
│   ├── fantasy/
│   └── profile/
└── shared/
    ├── utils/           # time_utils, sport_icons, sport_utils
    └── widgets/         # live_badge, section_header, app_error_state, app_empty_state, team_logo, app_bar_brand_icon, selectable_chip

Each feature folder structure:

features/<name>/
├── data/            # Repository implementations, API calls, ObjectBox queries
├── domain/          # Models, abstract repository interfaces
└── presentation/    # Screens, widgets, Riverpod providers

Architecture Rules

1. Flutter NEVER calls third-party APIs directly. All sports data, news, and fantasy requests go through the Sideline backend.
2. No API keys in Flutter code. All third-party keys live in backend environment variables only.
3. Supabase RLS must be enabled on all user-scoped tables.
4. Fantasy OAuth tokens stored encrypted via pgcrypto. Never plaintext.
5. Rate limiting on all backend routes: 100 req/min per user via Redis.
6. HTTPS and WSS only in production.
7. DRY: Use shared widgets/utils. Before writing a new widget, check lib/shared/widgets/ and lib/shared/utils/. Never duplicate LIVE badges, section headers, error/empty states, team logos, or utility functions.
8. Public backend routes (no auth): /health, /api/games, /api/stats, /api/trending, /api/teams/colors, /api/search, /api/h2h, /api/players, /api/teams/:sport. All other routes require Supabase JWT.
9. Reference is fair game. Code examples, patterns, design references, and assets found online are free to use, adapt, and integrate. If it's publicly available, treat it as a resource.

Design Paradigms

Apply the right principle for the situation — don't default to one:

Decision flow: KISS first → wait for repetition → AHA (wait for 3rd case) → DRY extract → keep SOLID at boundaries → YAGNI everything else.

Design System

Font

Google Sans Flex — bundled variable font for Material 3 Expressive look. Loaded as a bundled asset (not via google_fonts package). Available on both Android and iOS.

Colors (Dark-first)

Styling

Reference my app styling from /constants/ folder before making inline changes to a specific file. Only make inline specific styles (ie there is AppSpacing.xs which is 4 pixels from my spacing.dart. By inline styling i mean not using the AppSpacing.(value) and using your own spacing ie Radius.circle(2))

Avoid hardcoded fontSizes and prefer usting textTheme ie Theme.of(context).textTheme.display/heading/label....?.copyWith().

Navigation

5-tab bottom nav bar: Home | Live | Scores | Fantasy | Profile No hamburger menu or side drawer.

Coding Conventions

Dart / Flutter

• freezed for all model classes (immutable, copyWith, equality)
• json_serializable for JSON parsing — no manual fromJson
• All async operations use AsyncValue from Riverpod — handle loading, data, and error in UI
• Feature folders are self-contained with data/, domain/, presentation/
• Shared widgets in lib/shared/widgets/ — never duplicate across features
• File naming: snake_case.dart
• Class naming: PascalCase
• Never use BuildContext across async gaps
• ListView.builder only — never ListView with children array
• Loading states: shimmer skeleton loaders only — never CircularProgressIndicator
• Never show empty screens — always shimmer, error state, or empty state illustration
• Remote images: cached_network_image with team color gradient placeholder
• Complex list items: wrap in RepaintBoundary
• Cards: BorderRadius.circular(10), background AppColors.surface
• Primary buttons: BorderRadius.circular(12), background AppColors.accentRed
• All touch targets: minimum 48×48 logical pixels

TypeScript / Backend

• Fastify routes typed with zod schema validation on request and response
• DB queries use Supabase TypeScript client with generated types
• BullMQ jobs must be idempotent
• Validate all environment variables on startup using zod — crash fast if missing
• All errors logged with context — no silent failures

Git

• Branch naming: feature/, fix/, chore/
• One feature per PR

MVP Scope (v1.0) — Build Only This

• Auth (email/password + Google via Supabase Auth)
• Onboarding (6 screens)
• Following system (teams, players, leagues — optimistic UI)
• Personalized news feed (20/page, infinite scroll, breaking news banner)
• Live game screen (play-by-play, box score, stats, win probability chart)
• Player & team profiles
• Scores tab (today's games, filterable by sport)
• Push notifications (Tier 1 breaking + Tier 2 live game)
• Offline caching via ObjectBox
• Backend: Fastify + Supabase + Redis + BullMQ

NOT in MVP

• Fantasy integration (v1.5)
• Unified sports calendar (v1.5)
• Fan Pulse / Rivalry Mode (v2.0)
• AI summaries (v3.0)

Key References

Shared Widget & Utility Inventory

Before creating a new widget, check these shared components:

Utilities (lib/shared/utils/)

Widgets (lib/shared/widgets/)