Sports Calendar Sync - Architecture

This app uses a robust entity identification system to handle athletes with the same name across different sports.

Each entity has a unique ID that encodes:

• Type: sport, team, or athlete
• Sport code: f1, nfl, nba, etc.
• Unique identifier: API-provided ID or generated UUID

Examples:

• sport_f1 - Formula 1 as a sport
• team_f1_redbull - Red Bull Racing team
• athlete_f1_verstappen_33 - Max Verstappen (F1, car #33)
• athlete_nfl_smith_67890 - John Smith (NFL player)
• athlete_f1_smith_12345 - John Smith (F1 driver)

1. User searches for "John Smith"
2. API returns ALL matching entities with unique IDs:

   [
     {
       "id": "athlete_f1_smith_12345",
       "name": "John Smith",
       "sport": "Formula 1",
       "team": "Example Racing",
       "metadata": { "carNumber": "88" }
     },
     {
       "id": "athlete_nfl_smith_67890", 
       "name": "John Smith",
       "sport": "NFL",
       "team": "Example FC",
       "metadata": { "position": "WR" }
     }
   ]

3. User selects the correct John Smith
4. App stores the unique entity ID
5. Schedule fetched using that specific ID

Athletes like Max Verstappen who compete in multiple series have:

• Single athlete ID: athlete_f1_verstappen_33
• Multiple categories: ["Formula 1", "IGTC"]
• Aggregated events from all series they compete in

• F1: Ergast API (https://ergast.com/api/f1/)
  • Free, reliable, real-time
  • Provides race schedules, circuit info, results
  • Automatically updates when races are rescheduled

Planned API integrations:

• NFL: ESPN API or NFL official API
• NBA: NBA Stats API
• NHL: NHL Stats API
• MLB: MLB Stats API
• Soccer: Football-Data.org or API-Football

All schedules automatically filter to show only upcoming events:

• Compares event datetime against current time
• Past events are excluded
• Updates in real-time (no stale data)

When a race gets rescheduled:

1. Ergast API updates immediately
2. Next fetch gets new time
3. Option 1: Manual refresh button
4. Option 2: Webhook to update Google Calendar events (future feature)

User adds events → Store entity ID in calendar metadata
Daily cron job → Check for schedule changes
If changed → Update calendar event via Google Calendar API

/
├── main.tsx              # Main UI component
├── api/
│   ├── search.ts         # Entity search with disambiguation
│   ├── schedule.ts       # Fetch events for specific entity
│   ├── add-to-calendar.ts  # Google Calendar integration
│   └── auth/
│       └── google.ts     # OAuth flow

1. Google Calendar OAuth - Set up credentials
2. More sports APIs - NFL, NBA, NHL, MLB
3. Auto-sync - Detect schedule changes and update calendar
4. Webhook system - Real-time updates when events change
5. User preferences - Save followed entities
6. Notification system - Alert when schedules change