philip
b239ae3e5f
Replaces Firebase with a self-hosted PHP/MySQL API served from winded.prymsolutions.com. Includes full backend (schema, auth, events, teams, brackets, suggestions, stats, media, file upload) and updated Flutter repositories and domain models. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
109 lines
5.1 KiB
Markdown
109 lines
5.1 KiB
Markdown
# 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.
|