# 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:

```bash
# 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.