winded/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Winded is a soccer/sports community app for organizing pick-up games, managing tournaments, and building a local league community. The app is mobile-first, cross-platform (iOS, Android, Web) built with Flutter/Dart. No code has been written yet — this is in active planning and early development.

Tech Stack

• Frontend: Flutter (Dart), targeting iOS, Android, and Web
• Backend: Firebase (Auth, Firestore, Storage, Cloud Functions)
• State Management: Riverpod (preferred) or BLoC for complex logic
• Navigation: GoRouter (declarative, URL-friendly, works on mobile + web)
• Charts: fl_chart package for stats/leaderboards
• Ads (future): Google AdMob

Planned Folder Structure

lib/
 ├── core/              # App-wide config, themes, constants, routing
 ├── features/
 │     ├── auth/        # Firebase Auth, login, registration
 │     ├── events/      # Event listing, detail, countdown, registration
 │     ├── brackets/    # Tournament bracket generation and viewing
 │     ├── teams/       # Team profiles, rosters
 │     ├── stats/       # Player/team leaderboards and stats
 │     ├── media/       # Social media links, YouTube embeds, highlights
 │     ├── suggestions/ # Suggestion box, admin review
 │     └── ads/         # Ad integration (future phase)
 ├── shared/            # Reusable widgets, utilities
 └── main.dart

Each feature follows a layered structure: presentation (widgets/screens) → application (controllers/notifiers) → domain (models/entities) → infrastructure (repositories/services).

User Roles

• Guest: View events, brackets, stats, teams
• Registered User: Register for events, submit suggestions, vote in polls
• Admin: Create/edit events, manage brackets, approve teams, post ads

Core Features

1. Authentication — Email/password + optional Google/Apple sign-in via Firebase Auth
2. Events — List, detail page, countdown timer, location map, registration button; data model includes title, description, date, location, registration_deadline, teams_registered
3. Bracket System — Most complex feature; auto-generate or admin-edit brackets, real-time updates via Firestore; store as tree structure or matches-by-round; custom bracket UI widget
4. Teams Page — Team profiles (name, logo, wins, losses, players), roster view
5. Stats — Player and team leaderboards, filters by event, optional charts
6. Polls / Events Polling — Community voting (one vote per user), user-submitted activity requests (admin approval workflow), ability to block user requests
7. Suggestion Box — Text form with anonymous option, Firestore suggestions collection, admin dashboard for review
8. Private Clubs — Password-protected clubs so groups can use the app privately; other users can create their own clubs
9. Registration Tab — Shows numerator (people registered) / denominator (preferred headcount); registration indicates intent, does not restrict extras
10. Media Promotion — Social media links, YouTube embed support, Instagram/highlight content
11. Advertisements (future) — AdMob banners/interstitials; add only after core UX is polished, never on bracket screen

Flutter Conventions

• All Dart code must use sound null safety
• Follow dart format conventions; widget names PascalCase, variables/functions camelCase
• Use const constructors wherever possible to minimize rebuilds
• Responsive layouts via LayoutBuilder, MediaQuery, Flexible, Expanded; breakpoints: mobile <640px, tablet 640–1024px, desktop >1024px
• Use kIsWeb and Platform checks for platform-specific behavior
• Define ThemeData with full color scheme, typography, and component themes from the start

Common Commands

Once the Flutter project is initialized:

# Run on a connected device/emulator
flutter run

# Run on Chrome (web)
flutter run -d chrome

# Build for web (production)
flutter build web --release

# Run tests
flutter test

# Run a single test file
flutter test test/path/to/test_file.dart

# Format code
dart format lib/

# Analyze code
dart analyze

# Get/update packages
flutter pub get

Custom Agents

Two specialized sub-agents are configured in .claude/agents/:

• flutter-webapp-dev — Use for building features, writing Flutter/Dart code, architecture decisions, and any cross-platform implementation work. Prefers Riverpod, GoRouter, and feature-layered architecture.
• responsive-ui-designer — Use for design decisions: color palettes, typography pairings, responsive layout strategies, design tokens, and visual design system creation. Follows WCAG 2.1 AA accessibility standards.

MVP Scope

Build in this order: Auth → Events → Registration → Bracket viewing → Teams page → Stats → Suggestion box → Ads (last).

Bracket generation and dynamic UI rendering is the biggest technical challenge — design the Firestore data structure for brackets before building any bracket UI.