MyClub/app/README.md

# MyClub Mobile - Unified Club Hub (React Native / Expo)

MyClub Mobile is a **single, unified mobile app for all football clubs** running the MyClub platform. Users can discover and access any MyClub-supported club from one app, with three distinct access modes: Guest browsing, Fan portal, or Admin tools.

## Vision
One app to rule all MyClub clubs. Users discover clubs through our directory API, pin their favorites to a personal homepage, and access club-specific features based on their access level.

## Access Modes

### **Guest Mode** (Default)
- Browse club information, news, matches, and announcements
- View public content without registration
- **Call-to-action**: "Register on our website for full access"

### **Fan Mode** (Authenticated)
- Full fan portal experience
- QR ticket passes for entry (offline-capable)
- Match ordering, notifications, and personalized content
- Syncs with web account for seamless experience

### **Admin Mode** (Staff Only)
- QR code scanner for ticket validation
- Mobile admin management tools
- Real-time verification and gate control
- Port of web admin functionality optimized for mobile

## How It Works

1. **Club Discovery**: On first launch, users browse all active MyClub clubs via our directory API
2. **Club Pinning**: Users pin clubs to their personal homepage for quick access
3. **Access Selection**: For each club, users choose:
   - **Guest** - Browse public content
   - **Fan Login** - Connect to web account for full features
   - **Admin Login** - Staff access to validation tools
4. **Unified Experience**: All navigation, theming, and API calls adapt to the selected club context

## Features (Implemented)

### Core Infrastructure
- **Unified Club Directory**: Search and discover all MyClub-supported clubs via API
- **Multi-club Homepage**: Pin and organize favorite clubs on one dashboard
- **Dynamic Theming**: Each club's branding (colors, logo, name) automatically applied
- **Smart API Routing**: Seamlessly switches between club APIs based on selection
- **Offline Support**: Cached content and sync queue for poor connectivity

### Fan Features
- **QR Ticket Passes**: Store and display entry tickets offline
- **Match Information**: Upcoming/recent matches with scores and details
- **News Feed**: Club announcements and articles
- **Push Notifications**: Match reminders, results, and club updates
- **Web Account Sync**: Connects with existing web platform accounts

### Admin Features
- **QR Scanner**: Camera-based ticket validation at gates
- **Real-time Verification**: Instant validation against club backend
- **Mobile Admin Tools**: Essential management functions on-the-go
- **Staff Authentication**: Secure admin login with role-based access

### Technical Features
- **React Native + Expo**: Cross-platform mobile development
- **TypeScript**: Type-safe development with comprehensive interfaces
- **Offline Sync**: Queue-based synchronization for poor connectivity
- **Push Notifications**: Expo-based notification system
- **Error Handling**: Robust error states with retry mechanisms
- **Responsive Design**: Optimized for mobile screens and touch interactions

## Features (In Progress)

### Enhanced Fan Experience
- **Match Ticket Ordering**: Direct ticket purchasing within the app
- **Advanced Notifications**: Customizable notification preferences
- **Social Features**: Fan interactions and community features

### Admin Tools Expansion
- **Advanced Analytics**: Mobile-friendly dashboards and reports
- **Content Management**: Create and edit club content on mobile
- **Team Management**: Player and staff management tools

## Getting Started

1. **Install Dependencies** (Node 18+ recommended):
```bash
cd app
npm install
```

2. **Start Development Server**:
```bash
npm run dev
```

3. **Configure Environment**:
   - The app automatically detects API URLs from the MyClub directory
   - Override with `setApiBaseUrl(url)` for development
   - Ensure backend endpoints are accessible for club data

## Project Structure

### Core App Files
- `src/App.tsx` – Entry point with ClubContext and navigation setup
- `src/contexts/ClubContext.tsx` – Global club management and switching
- `src/theme.ts` – Dynamic theming based on club settings
- `src/navigation/RootNavigator.tsx` – Navigation structure with auth flows

### Services Layer
- `src/services/api.ts` – Axios client with per-club base URL handling
- `src/services/dashboard.ts` – Dashboard data fetching with offline support
- `src/services/auth.ts` – Fan and admin authentication helpers
- `src/services/notifications.ts` – Push notification setup and management
- `src/services/offlineSync.ts` – Offline caching and synchronization
- `src/services/club.ts` – Club pinning and management utilities
- `src/services/directory.ts` – MyClub directory API integration

### Feature Screens
- `src/features/club/ClubSelectorScreen.tsx` – Club discovery and pinning
- `src/features/dashboard/DashboardScreen.tsx` – Rich club content display
- `src/features/auth/FanLoginScreen.tsx` – Fan authentication flow
- `src/features/admin/AdminQRValidatorScreen.tsx` – Admin QR scanner
- `src/features/tickets/TicketScreen.tsx` – Ticket display and management
- `src/features/more/MoreScreen.tsx` – Settings and club management

## User Flow

### First-Time Experience
1. **Launch App** → Browse MyClub directory
2. **Discover Clubs** → Search and explore available clubs
3. **Pin Clubs** → Add favorites to personal homepage
4. **Choose Access** → Select Guest, Fan, or Admin mode for each club

### Fan Journey
1. **Select Club** → Choose from pinned clubs
2. **Fan Login** → Connect with web account credentials
3. **Access Features** → Tickets, notifications, match info
4. **Offline Use** → QR passes work without internet

### Admin Workflow
1. **Select Club** → Choose admin-enabled club
2. **Admin Login** → Staff authentication
3. **Launch Scanner** → QR code validation tool
4. **Manage On-site** → Real-time ticket verification

## API Integration

### Required Backend Endpoints
- `GET /api/v1/directory/clubs` – List all active MyClub clubs
- `GET /api/v1/settings` – Club-specific settings and theming
- `POST /api/v1/auth/login` – Fan authentication
- `POST /api/v1/admin/login` – Admin authentication
- `GET /api/v1/tickets/my-tickets` – User ticket data
- `POST /api/v1/tickets/validate` – QR ticket validation
- Standard CRUD endpoints for matches, news, announcements

### Error Handling
- Graceful fallbacks to cached content when offline
- User-friendly error messages in Czech
- Retry mechanisms for failed network requests
- Comprehensive logging for debugging

## Technical Notes

- **Expo SDK 51** with React Native 0.76
- **Cross-platform**: iOS and Android support
- **Offline-first**: Core functionality works without internet
- **Type-safe**: Full TypeScript implementation
- **Scalable**: Service layer architecture for easy feature additions
- **Secure**: Proper authentication and data handling

## Development Guidelines

- Follow Czech language requirements for user-facing text
- Maintain offline-first approach for core features
- Ensure consistent error handling across all screens
- Test with multiple clubs to verify theme switching
- Validate QR scanner performance on various devices

## Future Enhancements

- **Deep Linking**: Handle club invites and ticket URLs
- **Advanced Analytics**: Mobile-friendly admin dashboards
- **Social Features**: Fan interactions and community tools
- **Live Streaming**: Match video integration
- **Payment Integration**: In-app ticket purchasing