# Footy Access - Comprehensive Platform Documentation

## Platform Overview

**Footy Access** is a premier multimedia platform dedicated to youth soccer (U15-U19) in the United States. Founded by David Rodriguez and former USMNT player Jeremiah White, Footy Access combines real-time match tracking, player scouting, team rankings, and rich editorial content to showcase the next generation of football stars.

**Mission**: Amplifying the voices and journeys of the next generation of football stars through compelling storytelling, insightful coverage, and engaging original content.

**Coverage Scope**:
- Age Groups: U15, U16, U17, U19
- Competitions: MLS NEXT, MLS NEXT Pro, FIFA World Cup U17/U20, NCAA Division 1 (Men's & Women's)
- Geographic Focus: Nationwide United States coverage, International Youth Tournaments
- Content Types: Live scores, player/team rankings, editorial stories, breaking news, video content

**Social Media Reach**:
- Instagram: 82K followers (@footyaccess) - 12M+ monthly views, 153K+ avg views/post
- TikTok: 210K followers (@footyaccess) - 13.4M total likes, 378K+ avg views/post
- YouTube: 7.6K+ subscribers - 991.5K+ total views, 27K+ hours watch time
- Additional: X/Twitter (@footy_access), LinkedIn, Threads (@footyaccess), Snapchat (footyaccess)

**Key Partnerships**:
- MLS Academies: Philadelphia Union, Orlando City SC, New York City FC, San Jose Earthquakes, FC Cincinnati
- Leagues: USL Academy, NCAA
- Tournaments: Generation adidas Cup, MLS NEXT Fest, USL Academy Finals

---

## Complete Site Architecture

### Core Navigation Pages

**Homepage** (`https://footyaccess.com/`)
- Live scores carousel with date navigation (yesterday/today/tomorrow)
- Smart date selection automatically finds nearest match date
- Age group filtering (U15, U16, U17, U19)
- Competition filtering (MLS NEXT, FIFA tournaments, college leagues)
- Featured stories section with hero story + grid
- Top players ranking preview by birth year ('07, '08, '09, '10)
- YouTube shorts and videos integration
- Email newsletter signup
- Social media links and footer navigation

**About Page** (`https://footyaccess.com/about`)
- Platform mission and vision
- Founder information (David Rodriguez, Jeremiah White)
- Social media metrics dashboard with real-time stats
- Latest news and partnership announcements
- Community impact section
- Background video showcase

**Contact Page** (`https://footyaccess.com/contact`)
- Contact form with reCAPTCHA v2 protection
- Email: info@footyaccess.com
- Response time: Typically within 24 hours
- Story tips submission
- Technical support
- Partnership inquiry guidance

**Partnership Page** (`https://footyaccess.com/partner`)
- Partnership opportunities for brands, clubs, and organizations
- Collaboration frameworks
- Media partnership details
- Sponsorship opportunities

---

### League Coverage Pages

**MLS NEXT** (`https://footyaccess.com/leagues/mls-next`)
- **Description**: Premier youth development league in North America featuring MLS club academies and elite non-MLS programs
- **Age Groups**: U15, U16, U17, U19 with interactive age group selector
- **Navigation Tabs**:
  - Overview: League summary, key stats, featured matches
  - Matches: Full fixture list with live scores and results
  - Stats: Player statistics, team performance metrics
  - Teams: Complete team directory with logos and divisions
- **Features**:
  - Live match ticker with real-time score updates
  - Match detail modals with lineups, events (goals, cards, substitutions), and timestamps
  - Data sourced from Kitman Labs platform via web scraping
  - Team profiles with division placement and conference information
  - Player statistics tracking (goals, assists, appearances)
  - Season tracking (2026 season)
  - Age group filtering for focused viewing
  - Team search functionality
- **Team Pages**: Individual team detail pages at `/leagues/mls-next/teams/[teamName]`
- **Data Structure**: Match dates, times, venues, lineups, match events, team logos

**MLS NEXT Pro** (`https://footyaccess.com/leagues/mls-next-pro`)
- **Description**: Professional development league serving as bridge between MLS academies and first teams
- **Competition Level**: Professional/Semi-professional (MLS pathway)
- **Navigation Tabs**:
  - Overview: League highlights and current standings preview
  - Table: Full league standings with points, wins, draws, losses, goal difference
  - Matches/Playoffs: Fixture list (switches to "Playoffs" during postseason)
  - Stats: Top scorers, assists, team statistics
  - Teams: All MLS reserve team profiles
- **Features**:
  - Live match ticker with elapsed time display for in-progress matches
  - Playoff bracket visualization during postseason with automatic switching
  - League table with comprehensive statistics
  - Match results and upcoming fixtures
  - Team statistics and performance tracking
  - Season tracking (2025 season)
  - Integration with API-Football.com for professional league data
- **Team Pages**: Individual team pages at `/leagues/mls-next-pro/teams/[teamId]`
- **Playoff System**: Knockout bracket visualization when playoffs are active

**FIFA World Cup U20** (`https://footyaccess.com/leagues/fifa-world-cup-u20`)
- **Description**: FIFA U-20 World Cup international youth tournament
- **Competition Type**: International tournament with group stage and knockout rounds
- **Navigation Tabs**:
  - Overview: Tournament summary, featured matches, key moments
  - Groups: Group stage standings organized by groups (A, B, C, D, E, F)
  - Knockout: Bracket visualization for Round of 16, Quarter-Finals, Semi-Finals, Final
  - Matches: Complete fixture list across all tournament stages
  - Stats: Top scorers, assists, team statistics
  - Teams: All participating national teams with profiles
- **Features**:
  - Group stage standings with points, wins, draws, losses, goals for/against
  - Interactive knockout bracket showing tournament progression
  - Live match tracking during tournament dates
  - Top scorers and assists leaderboards
  - Team statistics for all participating nations
  - Player performance tracking during tournament
  - Integration with API-Football.com for FIFA tournament data
- **Team Pages**: National team pages at `/leagues/fifa-world-cup-u20/teams/[teamId]`
- **Tournament Format**: Group stage (6 groups of 4) → Knockout rounds (Round of 16 → Quarter-Finals → Semi-Finals → Final)

**FIFA World Cup U17** (`https://footyaccess.com/leagues/fifa-world-cup-u17`)
- **Description**: FIFA U-17 World Cup tournament for youth international soccer
- **Competition Type**: International tournament (group stage + knockout)
- **Navigation Tabs**:
  - Overview: Tournament overview and highlights
  - Groups: Group stage standings by group
  - Knockout: Tournament bracket for elimination rounds
  - Matches: All tournament fixtures
  - Teams: International team profiles
- **Features**:
  - Group stage standings organized by tournament groups
  - Knockout bracket system visualizing playoff progression
  - Match schedules and results across all stages
  - Team profiles for youth international squads
  - Tournament statistics and player tracking
  - Season tracking (2025 tournament)
  - API-Football.com integration for FIFA youth data
- **Team Pages**: Youth national team pages at `/leagues/fifa-world-cup-u17/teams/[teamId]`
- **Age Category**: U17 (Under-17 years old)

**College Soccer - Men's Division 1** (`https://footyaccess.com/leagues/college/men`)
- **Description**: NCAA Division 1 men's soccer championship coverage
- **Competition Level**: Collegiate (NCAA Division 1)
- **Navigation Tabs**:
  - Overview: Season overview, top teams, featured matches
  - Standings: Conference standings and rankings
  - Matches: Full schedule of D1 men's matches
  - Stats: Player statistics (goals, assists, clean sheets)
  - News: NCAA-specific news feed and updates
- **Features**:
  - Conference standings organized by NCAA conferences
  - Match schedules and results for D1 programs
  - Player statistics tracking (goals, assists, appearances)
  - NCAA men's soccer news feed with college-specific updates
  - Team profiles for Division 1 programs
  - Championship tournament tracking
  - Season tracking (Fall 2026 season)
  - ESPN/NCAA data integration
  - College player performance metrics
- **Season Structure**: Fall season (August-November) + NCAA Tournament (November-December)
- **Coverage**: All Division 1 conferences and independents

**College Soccer - Women's Division 1** (`https://footyaccess.com/leagues/college/women`)
- **Description**: NCAA Division 1 women's soccer championship coverage
- **Competition Level**: Collegiate (NCAA Division 1)
- **Navigation Tabs**:
  - Overview: Season highlights and top performers
  - Standings: Conference standings for women's D1
  - Matches: Complete fixture list for women's college soccer
  - Stats: Player statistics and performance metrics
  - News: NCAA women's soccer news and updates
- **Features**:
  - Conference standings for women's D1 programs
  - Match fixtures and results across all conferences
  - Player performance metrics (goals, assists, saves)
  - NCAA women's soccer news feed
  - Team profiles for D1 women's programs
  - National championship tournament coverage
  - Season tracking (Fall 2026 season)
  - ESPN/NCAA women's soccer data feeds
  - Women's player rankings and scouting
- **Season Structure**: Fall season + NCAA Women's College Cup
- **Coverage**: Nationwide Division 1 women's programs

**Team Detail Pages**
- **MLS NEXT Teams**: `/leagues/mls-next/teams/[teamName]` - Team-specific pages with roster, match history, statistics
- **MLS NEXT Pro Teams**: `/leagues/mls-next-pro/teams/[teamId]` - Reserve team profiles with player development tracking
- **FIFA U20 Teams**: `/leagues/fifa-world-cup-u20/teams/[teamId]` - National team pages for U20 World Cup participants
- **FIFA U17 Teams**: `/leagues/fifa-world-cup-u17/teams/[teamId]` - Youth national team profiles for U17 tournament

---

### Rankings System

**Team Rankings** (`https://footyaccess.com/rankings`)

**Ranking Categories**:
1. **Composite Rankings**: All youth academies (MLS-affiliated and independent)
2. **Pro Academy Rankings**: MLS-affiliated academies only
3. **Non-Pro Academy Rankings**: Independent clubs and non-MLS programs

**Evaluation Criteria** (Grade-Based System):
- **Form**: Current team performance and recent results
- **Talent Pipeline Strength**: Quality and depth of player development
- **Development Pathways**: Coaching quality, training methodology, progression structure
- **Impact Players**: Number and quality of standout athletes

**Visual Presentation**:
- Podium display for top 3 teams (Gold, Silver, Bronze)
- Cards for positions 4-10
- Team logos, grades, and detailed metrics

**Free vs Premium Access**:
- Free Tier: View top 3 teams with full details
- Premium Required: Positions 4+ show placeholder cards with upgrade prompts
- Paywall messaging and conversion modals

**Player Rankings** (`https://footyaccess.com/rankings/players`)

**Top 50 Player System**:
- Elite player identification across U15-U19 age groups
- Birth year grouping ('07, '08, '09, '10)
- Detailed player profiles with comprehensive scouting data

**Player Profile Components**:
- Full name, nationality, date of birth
- Current club affiliation
- Primary and secondary positions
- Height, weight, physical attributes
- Contract information (contract until date)
- Market value estimation
- Profile photo

**Scouting Reports**:
- Evaluator name and credentials
- Overall grade (A+, A, A-, B+, etc.)
- Technical grade (ball control, passing, dribbling, finishing)
- Physical grade (speed, strength, stamina, agility)
- Mental grade (decision-making, positioning, leadership, work rate)
- Detailed written analysis and observations
- Player comparison ("Reminds us of...")
- Projected ceiling (Elite Professional, High-Level Professional, Professional, Semi-Professional)

**Career Accolades**:
- National team callups (youth national teams, senior caps)
- Championships won (league titles, tournament victories)
- Individual awards (Golden Boot, Best Player, All-Tournament Team)
- Performance milestones

**Player Statistics**:
- Goals scored
- Assists
- Appearances
- Average rating
- Season/career stats breakdown

**Social Media Links**:
- Instagram profiles
- TikTok accounts
- Twitter/X handles
- YouTube channels

**College Player Rankings** (`https://footyaccess.com/rankings/college/players`)
- NCAA player rankings and performance metrics
- College athlete tracking and scouting
- Transfer portal monitoring
- Draft prospect evaluation

---

### Content Pages

**Stories** (`https://footyaccess.com/stories`)

**Story Structure**:
- Title and headline
- Summary/excerpt
- Full content (rich HTML with embedded media)
- URL slug for SEO
- Categories (player features, tournament coverage, academy spotlights, interviews)
- Author information (name, bio, photo, social links)
- Thumbnail image
- Publish date and last updated
- View count tracking
- Like/engagement metrics

**Content Features**:
- Featured story spotlight on homepage
- Pagination for browsing archives
- Category filtering
- Search functionality
- Premium/exclusive story tiers
- Related content recommendations

**Story Types**:
- Player profiles and interviews
- Tournament reports and recaps
- Academy spotlights
- Behind-the-scenes access
- Coaching insights
- Parent and player perspectives
- College recruitment stories
- International youth soccer features

---

### User System & Authentication

**User Account Pages**:
- `/login` - Email/password authentication, Google OAuth
- `/register` - New user registration with email verification
- `/forgot-password` - Password reset request
- `/reset-password` - Complete password reset with token
- `/verify-email` - Email address verification
- `/profile` - User profile management, subscription status, preferences

**Authentication Methods**:
- Email/password with JWT tokens
- Google OAuth integration
- Email verification via OTP (one-time password)
- Session monitoring and management
- Password reset via secure tokens

**User Features**:
- Profile customization
- Subscription management
- Payment history
- Notification preferences
- Score reminders for favorite teams/matches
- Saved articles and favorites

**Subscription Tiers**:
- **Free Tier**: Basic scores, top 3 team rankings, limited player data, select stories
- **Premium Tier**: Full team rankings, complete player statistics, all stories, advanced analytics
- **Exclusive Tier**: Highest-level content access, early access to features

**Billing Integration**:
- Stripe payment processing
- Subscription plans with recurring billing
- Checkout sessions
- Customer portal for management
- Next billing date tracking
- Subscription status (active, cancelled, past_due)

---

### Admin Portal

**Admin Access** (`/admin-portal-x7k9m2w8`)
- Hidden URL for security
- Role-based access control (master, editor, viewer)
- Admin authentication separate from user accounts

**Admin Dashboard** (`/admin`)
- Platform analytics summary
- User subscription breakdown
- Content metrics (stories, news, rankings published)
- Match data statistics
- Traffic and engagement overview

**Content Management Sections**:

1. **Stories Management**
   - Create/edit/delete stories
   - Rich text editor with HTML support
   - Image upload and management
   - SEO metadata (title, description, keywords)
   - Category assignment
   - Author selection
   - Premium/exclusive tier assignment
   - Publish/draft/archive status

2. **Scores Management**
   - Create/update/delete matches
   - Manual score entry
   - Match status updates
   - Lineup management
   - Match events (goals, cards, subs)
   - Venue and time editing
   - Data source tracking

3. **Rankings Management**
   - Create/update/delete team rankings
   - Grade assignment (form, talent pipeline, development pathways)
   - Age group and ranking type selection
   - Impact player documentation
   - Coach information

4. **News Management**
   - Create/edit/delete news items
   - Category and priority assignment
   - Thumbnail upload
   - External link integration
   - Publication status control

5. **User Management**
   - View all users
   - Create admin accounts
   - Update user roles
   - Delete/suspend users
   - Monitor subscriptions
   - Session tracking

6. **Analytics Dashboard**
   - User growth metrics
   - Subscription conversion rates
   - Content performance
   - Traffic sources
   - Engagement metrics

---

## Data Models & Structure

### Core Entities

**Score/Match Model**:
```
{
  matchId: String (unique),
  competition: String (league/tournament name),
  ageGroup: String (U15, U16, U17, U19),
  homeTeam: String,
  awayTeam: String,
  homeScore: Number,
  awayScore: Number,
  matchDate: Date,
  status: String (Live, HT, FT, Scheduled, Postponed, Cancelled),
  venue: String,
  dataSource: String (KITMAN_LABS, API_FOOTBALL, MANUAL, MLS_NEXT),
  homeLogo: String (URL),
  awayLogo: String (URL),
  createdAt: Date,
  updatedAt: Date
}
```

**Enhanced Score Model** (with details):
```
{
  matchId: Reference to Score,
  homeLineup: [{
    playerName: String,
    position: String,
    jerseyNumber: Number
  }],
  awayLineup: [{
    playerName: String,
    position: String,
    jerseyNumber: Number
  }],
  events: [{
    type: String (goal, yellow_card, red_card, substitution),
    time: Number (minutes),
    player: String,
    team: String (home/away),
    assistedBy: String (for goals)
  }],
  statistics: {
    possession: {home: Number, away: Number},
    shots: {home: Number, away: Number},
    shotsOnTarget: {home: Number, away: Number},
    corners: {home: Number, away: Number},
    fouls: {home: Number, away: Number}
  }
}
```

**Ranking Model**:
```
{
  ageGroup: String (U15, U16, U17, U19),
  type: String (Composite, Pro, Non-pro),
  rank: Number,
  team: String,
  logo: String (URL),
  form: String (Grade: A+, A, A-, B+, B, B-, C+, C, C-, D, F),
  talentPipelineStrength: String (Grade),
  developmentPathways: String (Grade),
  impactPlayers: String (comma-separated names),
  coach: String,
  conference: String,
  division: String,
  cityState: String
}
```

**Player Model**:
```
{
  fullName: String,
  dateOfBirth: Date,
  birthYear: String ('07, '08, '09, '10),
  nationality: String,
  currentClub: String,
  primaryPosition: String,
  secondaryPosition: String,
  height: String,
  weight: String,
  contractUntil: Date,
  marketValue: Number,
  profilePhoto: String (URL),

  scoutingReport: {
    evaluator: String,
    overallGrade: String,
    technicalGrade: String,
    physicalGrade: String,
    mentalGrade: String,
    analysis: String (detailed text),
    comparison: String ("Reminds us of..."),
    projectedCeiling: String
  },

  accolades: [{
    type: String (national_team_callup, championship, individual_award),
    title: String,
    year: Number,
    description: String
  }],

  statistics: {
    goals: Number,
    assists: Number,
    appearances: Number,
    averageRating: Number,
    seasonStats: [{
      season: String,
      competition: String,
      goals: Number,
      assists: Number,
      appearances: Number
    }]
  },

  socialLinks: {
    instagram: String (URL),
    tiktok: String (URL),
    twitter: String (URL),
    youtube: String (URL)
  }
}
```

**Story Model**:
```
{
  title: String,
  summary: String,
  content: String (rich HTML),
  slug: String (URL-friendly),
  categories: [String],
  author: {
    name: String,
    bio: String,
    photo: String (URL),
    socialLinks: {instagram: String, twitter: String}
  },
  thumbnail: String (URL),
  publishDate: Date,
  lastUpdated: Date,
  isPremium: Boolean,
  isExclusive: Boolean,
  status: String (draft, published, archived),
  views: Number,
  likes: Number,
  metaDescription: String,
  metaKeywords: [String]
}
```

**News Model**:
```
{
  title: String,
  summary: String,
  thumbnail: String (URL),
  category: String (partnership, update, community, event),
  priority: String (high, medium, low),
  status: String (published, archived),
  externalLink: String (URL),
  publishDate: Date
}
```

**Team Model**:
```
{
  name: String,
  logo: String (URL),
  conference: String,
  division: String,
  cityState: String,
  ageGroups: [String]
}
```

**User Model**:
```
{
  email: String (unique),
  passwordHash: String,
  googleId: String (for OAuth),
  profile: {
    firstName: String,
    lastName: String,
    phoneNumber: String,
    preferences: Object
  },
  emailVerified: Boolean,
  subscriptionStatus: String (free, premium, exclusive),
  createdAt: Date,
  lastLogin: Date
}
```

**Subscription Model**:
```
{
  userId: Reference to User,
  plan: String (premium, exclusive),
  status: String (active, cancelled, past_due),
  nextBillingDate: Date,
  stripeCustomerId: String,
  stripeSubscriptionId: String,
  createdAt: Date,
  updatedAt: Date
}
```

**AdminUser Model**:
```
{
  email: String (unique),
  passwordHash: String,
  name: String,
  role: String (master, editor, viewer),
  createdAt: Date,
  lastLogin: Date
}
```

---

## API Endpoints & Data Access

### Authentication Endpoints (`/api/auth`)

- `POST /api/auth/register` - User registration with email and password
- `POST /api/auth/login` - User login, returns JWT token
- `POST /api/auth/logout` - User logout and session termination
- `GET /api/auth/me` - Get current authenticated user profile
- `POST /api/auth/verify-email` - Email verification via OTP code
- `POST /api/auth/resend-verification` - Resend verification email
- `POST /api/auth/forgot-password` - Request password reset email
- `POST /api/auth/reset-password` - Complete password reset with token
- `PUT /api/auth/profile` - Update user profile information
- `POST /api/auth/change-password` - Change user password
- `GET /api/auth/google` - Initiate Google OAuth flow
- `GET /api/auth/google/callback` - Handle Google OAuth callback

### Scores Endpoints (`/api/scores`)

- `GET /api/scores` - Get scores with filters
  - Query params: `date`, `ageGroup`, `competition`, `team`
  - Returns: Array of match objects
- `GET /api/scores/:matchId` - Get detailed match information
  - Returns: Match with lineups and events
- `POST /api/scores` - Create new match (admin only)
- `PUT /api/scores/:matchId` - Update match details (admin only)
- `DELETE /api/scores/:matchId` - Delete match (admin only)
- `GET /api/scores/nearest-date` - Find nearest date with matches
  - Returns: Closest date with scheduled/completed matches

### Admin Scores Endpoints (`/api/admin/scores`)

- `GET /api/admin/scores` - Get filtered scores for admin panel
- `GET /api/admin/scores/:matchId` - Get match details for editing
- `POST /api/admin/scores/:matchId/events` - Update match events
- `PUT /api/admin/scores/:matchId/lineup` - Update team lineups
- `PUT /api/admin/scores/:matchId/complete` - Mark match as complete

### Rankings Endpoints (`/api/rankings`)

- `GET /api/rankings` - Get team rankings
  - Query params: `ageGroup`, `type` (Composite/Pro/Non-pro)
  - Returns: Ordered array of team rankings
- `POST /api/rankings` - Create new ranking (admin only)
- `PUT /api/rankings/:id` - Update ranking (admin only)
- `DELETE /api/rankings/:id` - Delete ranking (admin only)

### Stories Endpoints (`/api/stories`)

- `GET /api/stories` - List stories with pagination
  - Query params: `page`, `limit`, `category`, `search`
  - Returns: Stories array with pagination metadata
- `GET /api/stories/featured` - Get featured story for homepage
- `GET /api/stories/:slug` - Get story by URL slug
  - Increments view count
  - Returns: Full story content with author details
- `POST /api/stories` - Create story (admin only)
- `PUT /api/stories/:id` - Update story (admin only)
- `DELETE /api/stories/:id` - Delete story (admin only)

### News Endpoints (`/api/news`)

- `GET /api/news` - List news items
  - Query params: `category`, `priority`, `status`
  - Returns: News articles sorted by priority and date
- `POST /api/news` - Create news item (admin only)
- `PUT /api/news/:id` - Update news item (admin only)
- `DELETE /api/news/:id` - Delete news item (admin only)

### Players Endpoints (`/api/players`)

- `GET /api/players` - List all players
  - Query params: `birthYear`, `position`, `club`
- `GET /api/players/top50` - Get top 50 ranked players
  - Returns: Elite players with full scouting reports
- `GET /api/players/:id` - Get player profile by ID
  - Returns: Complete player data including accolades and stats
- `POST /api/players` - Create player profile (admin only)
- `PUT /api/players/:id` - Update player profile (admin only)
- `DELETE /api/players/:id` - Delete player (admin only)

### Teams Endpoints (`/api/teams`)

- `GET /api/teams` - List all teams
- `GET /api/teams/:id` - Get team details
- `POST /api/teams` - Create team (admin only)
- `PUT /api/teams/:id` - Update team (admin only)

### Subscription Endpoints (`/api/subscription`)

- `POST /api/subscription/create-checkout-session` - Create Stripe checkout
  - Body: `{plan: 'premium' | 'exclusive'}`
  - Returns: Stripe checkout URL
- `GET /api/subscription/plans` - Get available subscription plans
- `GET /api/subscription/current` - Get current user's subscription

### Admin Endpoints (`/api/admin`)

- `POST /api/admin/login` - Admin authentication
- `GET /api/admin/users` - List all users (admin only)
- `POST /api/admin/users` - Create admin user (master role only)
- `PUT /api/admin/users/:id` - Update user (admin only)
- `DELETE /api/admin/users/:id` - Delete user (admin only)
- `GET /api/admin/dashboard-stats` - Get analytics dashboard data

### Analytics Endpoints (`/api/analytics`)

- `GET /api/analytics/summary` - Platform usage summary
- `GET /api/analytics/subscriptions` - Subscription breakdown

### Other Endpoints

- `POST /api/contact` - Submit contact form (with reCAPTCHA verification)
- `POST /api/upload` - Upload files/images (admin only)
- `GET /api/youtube` - Fetch YouTube videos/shorts
- `POST /api/partnership` - Submit partnership inquiry

---

## Technology Stack

### Frontend Technology
- **Framework**: Next.js 15 (App Router architecture)
- **React**: Version 19
- **Language**: TypeScript (strict mode enabled)
- **Styling**: Tailwind CSS with custom configuration
- **Animations**: Framer Motion
- **Icons**: Heroicons
- **Fonts**: Druk Text (display), Effra (body text)
- **Data Fetching**: SWR for client-side data fetching
- **State Management**: React Context API and hooks
- **Forms**: React Hook Form
- **Image Optimization**: Next.js Image component

### Backend Technology
- **Runtime**: Node.js
- **Framework**: Express.js
- **Database**: MongoDB with Mongoose ODM
- **Authentication**: Passport.js (Google OAuth), JWT tokens
- **File Upload**: Multer middleware
- **Email**: Nodemailer with Gmail API integration
- **Payment Processing**: Stripe API
- **Security**: Helmet.js, CORS, bcrypt for password hashing
- **Environment**: dotenv for configuration

### External Integrations
- **Kitman Labs**: Web scraping with Puppeteer for MLS NEXT scores
- **API-Football.com**: General soccer data and statistics
- **ESPN/NCAA**: College soccer scores and RSS feeds
- **YouTube API**: Video integration and content embedding
- **Google APIs**: OAuth authentication, Gmail sending
- **Stripe**: Subscription billing and payment processing
- **reCAPTCHA v2**: Form protection against spam

### Development Tools
- **Linting**: ESLint for code quality
- **Package Manager**: npm
- **Version Control**: Git
- **Build Tool**: Turbopack (Next.js 15 default)

---

## Data Sources & Scraping Services

### Web Scraping Services

**Kitman Labs Scraper** (MLS NEXT Scores):
- Target: Kitman Labs platform (official MLS NEXT data provider)
- Method: Puppeteer headless browser automation
- Frequency: Periodic scraping for live match updates
- Data Extracted: Match scores, team names, age groups, match status, dates
- Script Variations:
  - `workingKitmanScraper.js` - Production scraper based on MuiDataGrid
  - `enhancedKitmanScraper.js` - Handles lazy-loaded tables
  - `alternativeKitmanScraper.js` - Compatibility fallback
  - `debugKitmanScraper.js` - Debug mode with extraction details
  - `testKitmanLabsScores.js` - Test scraper (no database writes)

**NCAA Scraper**:
- Service: `ncaaScraperService.js`
- Data: College soccer scores and schedules
- Integration: ESPN NCAA feeds and official NCAA data

**ESPN NCAA Service**:
- Service: `espnNcaaService.js`
- Data: College soccer statistics and game results
- Format: JSON API responses

**NCAA RSS Service**:
- Service: `ncaaRssService.js`
- Data: News feeds and updates from NCAA soccer

### API Integrations

**API-Football.com**:
- Service: `apiFootballService.js`
- Data: General soccer statistics, fixtures, standings
- Use Case: Backup data source for scores and team information

**YouTube Data API**:
- Integration: Embedded videos and shorts on homepage
- Content: Player highlights, tournament coverage, original Footy Access content
- Channels: Footy Access official YouTube channel

**Gmail API**:
- Service: `emailService.js`
- Use Case: Transactional emails (verification, password reset, notifications)
- Integration: Nodemailer with Gmail SMTP

---

## Interactive Features & User Experience

### Navigation & Discovery

**Date Navigation System**:
- Carousel interface (yesterday/today/tomorrow)
- Calendar modal for jump-to-date selection
- Smart date finding (automatically selects nearest date with matches)
- Persistent date selection across sessions

**Search & Filtering**:
- Team search (live search across all teams)
- Age group filtering (U15, U16, U17, U19)
- Competition filtering (MLS NEXT, FIFA tournaments, college leagues)
- Story category filtering
- News category and priority filtering
- Multi-level filtering combinations

**Content Discovery**:
- Featured content on homepage (stories, matches, players)
- Related content recommendations
- Category browsing
- Pagination for archives
- RSS feed for automated updates

### Premium Content System

**Free Tier Access**:
- Live scores for all competitions
- Top 3 team rankings with full details
- Limited player data preview
- Select free stories
- Basic match information

**Premium Tier Access**:
- Full team rankings (positions 4+)
- Complete player statistics and scouting reports
- All premium stories
- Advanced match analytics
- Detailed player accolades

**Paywall Implementation**:
- Placeholder cards for locked rankings
- "Upgrade to Premium" conversion modals
- Subscription benefit messaging
- Seamless Stripe checkout integration
- Immediate access upon subscription

### User Engagement

**Personalization**:
- User profiles with preferences
- Favorite teams tracking
- Score reminders for selected matches
- Saved articles and bookmarks
- Customized content recommendations

**Notifications**:
- Email notifications for score reminders
- Verification emails
- Password reset emails
- Newsletter subscriptions
- Partnership and update announcements

**Social Sharing**:
- Share stories on social media
- Embed match results
- Player profile sharing
- Team ranking screenshots

---

## Content Management Workflow

### Story Creation Process

1. **Admin Login** - Access admin portal with credentials
2. **Navigate to Stories** - Select "Create Story" in admin dashboard
3. **Content Entry**:
   - Title and summary
   - Rich text editor for full content (HTML support)
   - Image upload for thumbnail
   - Category selection
   - Author assignment
4. **SEO Optimization**:
   - Meta description
   - Meta keywords
   - URL slug generation
5. **Tier Assignment**:
   - Free (accessible to all)
   - Premium (subscription required)
   - Exclusive (highest tier)
6. **Publication**:
   - Save as draft
   - Publish immediately
   - Schedule for future publication
7. **Post-Publication**:
   - Track views and likes
   - Update content as needed
   - Feature on homepage
   - Archive when outdated

### Match Data Management

1. **Automatic Scraping**:
   - Kitman Labs scraper runs periodically
   - Extracts MLS NEXT scores automatically
   - Updates existing matches
   - Creates new match records

2. **Manual Entry** (Admin Portal):
   - Create match record
   - Enter teams, date, venue
   - Input scores
   - Update match status (Live, HT, FT)
   - Add lineups
   - Record match events (goals, cards, subs)

3. **Data Quality**:
   - Data source tracking (KITMAN_LABS, MANUAL, API_FOOTBALL)
   - Timestamp tracking (created, updated)
   - Validation rules for score entry
   - Logo URL verification

### Player Profile Management

1. **Profile Creation**:
   - Basic information (name, DOB, nationality)
   - Current club affiliation
   - Position and physical attributes
   - Photo upload

2. **Scouting Report Entry**:
   - Evaluator credentials
   - Grade assignments (overall, technical, physical, mental)
   - Detailed written analysis
   - Player comparison
   - Ceiling projection

3. **Accolades Tracking**:
   - National team callups
   - Championship wins
   - Individual awards
   - Performance milestones

4. **Statistics Integration**:
   - Goals, assists, appearances
   - Season-by-season breakdown
   - Average ratings
   - Competition-specific stats

5. **Social Media Linking**:
   - Instagram, TikTok, Twitter, YouTube profiles
   - Verified account badges
   - Follower count tracking

---

## SEO & Discoverability

### On-Page SEO

**Meta Tags**:
- Dynamic page titles based on content
- Meta descriptions for all pages
- Open Graph tags for social sharing
- Twitter Card markup
- Canonical URLs

**Structured Data**:
- Organization schema (Footy Access business entity)
- Article schema (stories and news)
- SportsEvent schema (matches and tournaments)
- Person schema (player profiles)

**URL Structure**:
- Clean, semantic URLs
- Story slugs for readability
- League and competition permalinks
- Player and team profile URLs

**Content Optimization**:
- Keyword-rich content
- Header hierarchy (H1, H2, H3)
- Alt text for images
- Internal linking strategy

### RSS Feed

**Feed URL**: `https://footyaccess.com/feed.xml`

**Feed Content**:
- Latest stories
- News updates
- Match results
- Player rankings updates
- Automated generation
- XML format for reader compatibility

### Social Media Integration

**Social Sharing**:
- One-click sharing to Instagram, TikTok, Twitter, LinkedIn
- Pre-populated share text with hashtags
- Image optimization for social platforms
- Click tracking for shares

**Embedded Content**:
- YouTube videos and shorts on homepage
- Instagram feed widgets (potential)
- Twitter timeline embeds (potential)
- Social proof badges (follower counts)

---

## Legal & Compliance

**Terms of Use** (`https://footyaccess.com/terms`)
- User agreement and terms of service
- Acceptable use policy
- Content licensing
- Disclaimer of warranties
- Limitation of liability

**Privacy Policy** (`https://footyaccess.com/privacy`)
- Data collection practices
- Cookie usage
- Third-party services (Stripe, Google)
- User rights and data access
- Contact information for privacy inquiries

**Children's Privacy Policy** (`https://footyaccess.com/childrens-privacy`)
- COPPA compliance (Children's Online Privacy Protection Act)
- Parental consent mechanisms
- Data collection limitations for minors
- Age verification procedures
- Youth-focused platform considerations

**Community Guidelines** (`https://footyaccess.com/community-guidelines`)
- Content standards
- Prohibited behavior
- Reporting mechanisms
- Moderation policies
- Enforcement and appeals

**COPPA Compliance**:
- Age-appropriate content
- Parental consent for users under 13
- Limited data collection for minors
- Secure handling of youth information
- Educational and developmental focus

**GDPR Considerations**:
- Cookie consent (future implementation)
- Right to access data
- Right to deletion
- Data portability
- Privacy by design

---

## Contact & Support

**Primary Contact**:
- Email: info@footyaccess.com
- Response Time: Typically within 24 hours

**Inquiry Types**:
- Story tips and submissions
- Technical support and bug reports
- Partnership and collaboration proposals
- Advertising and sponsorship
- General feedback and questions
- Media inquiries

**Coverage Area**:
- Geographic Focus: Nationwide United States
- Age Groups: U15, U16, U17, U19
- Leagues: MLS NEXT, MLS NEXT Pro, NCAA Division 1, FIFA Youth World Cups

**Social Media Support**:
- Instagram DMs: @footyaccess
- Twitter/X mentions: @footy_access
- TikTok comments: @footyaccess

---

## Platform Statistics & Metrics

**Social Media Reach** (Current as of 2025):

**Instagram** (@footyaccess):
- Followers: 82,000
- Monthly Views: 12,000,000+
- Average Views per Post: 153,000+

**TikTok** (@footyaccess):
- Followers: 210,000
- Total Likes: 13,400,000
- Average Views per Post: 378,000+

**YouTube**:
- Subscribers: 7,600+
- Total Views: 991,500+
- Watch Time: 27,000+ hours

**Additional Platforms**:
- Twitter/X: @footy_access
- LinkedIn: Footy Access company page
- Threads: @footyaccess
- Snapchat: footyaccess

**Content Impact**:
- Total Followers Across Platforms: 300,000+
- All-Time Views: 25,000,000+
- Monthly Reach: Millions of impressions

---

## Future Development & Roadmap

**Potential Features** (based on platform architecture):
- Live match commentary
- Player comparison tools
- Advanced statistics dashboards
- Interactive team pages
- College recruitment tracking
- Transfer news and rumors
- Mobile app development
- Push notification system
- Video highlights integration
- Fan engagement features (polls, predictions)
- Fantasy youth soccer leagues
- Coaching resources and training content

**Data Expansion**:
- Additional leagues (USL Academy, ECNL)
- International youth leagues
- Women's youth soccer expansion
- Grassroots tournament coverage
- Regional showcase events

**Monetization Opportunities**:
- Tiered subscription plans
- Sponsored content
- Team and player profile upgrades
- Tournament partnerships
- Merchandise and apparel
- Premium video content
- Recruiting services

---

## Technical Performance

**Frontend Optimization**:
- Next.js 15 with Turbopack for fast builds
- Image optimization with Next.js Image component
- Code splitting and lazy loading
- Server-side rendering for SEO
- Static generation for fast page loads
- API route caching

**Backend Performance**:
- MongoDB indexing for fast queries
- API response caching
- Efficient Mongoose queries
- Connection pooling
- Rate limiting for API protection

**Security Measures**:
- JWT authentication with secure tokens
- Password hashing with bcrypt
- CORS configuration for cross-origin security
- Helmet.js for HTTP header security
- Input validation and sanitization
- reCAPTCHA for form protection
- HTTPS encryption (production)
- SQL injection prevention (NoSQL)
- XSS protection

---

## Contact Information

**Footy Access, Inc.**
- Website: https://footyaccess.com
- Email: info@footyaccess.com
- Founded by: David Rodriguez, Jeremiah White (former USMNT player)

**Social Media**:
- Instagram: https://instagram.com/footyaccess
- TikTok: https://tiktok.com/@footyaccess
- YouTube: https://youtube.com/channel/UCiEALhoquNxAVI3Immh6FqQ
- Twitter/X: https://x.com/footy_access
- LinkedIn: https://linkedin.com/company/footy-access
- Threads: https://threads.net/@footyaccess
- Snapchat: https://snapchat.com/add/footyaccess

**Copyright**: Copyright © 2025 Footy Access, Inc. All Rights Reserved.

---

*This comprehensive documentation provides LLMs with complete context about the Footy Access platform, enabling accurate responses to queries about youth soccer coverage, player rankings, team evaluations, match tracking, and content discovery.*