SportSync 🏆

A beautifully simple sports dashboard following the CALM principle - instantly scannable, elegantly informative, and completely automated.

✨ What is SportSync?

SportSync is a static sports dashboard that answers one question perfectly: "What sports are happening when?"

• 🕒 Crystal clear time display with Norwegian timezone (24-hour format)
• 🎯 CALM design - readable by grandparents, loved by tech users
• 🔄 Fully automated - fresh data every 6 hours via GitHub Actions
• 📱 Mobile-first responsive design
• 🚀 Zero maintenance once deployed

🚀 Quick Start

1. Deploy to GitHub Pages (1-click setup)

1. Fork this repository
2. Enable GitHub Pages: Settings → Pages → Deploy from /docs folder
3. Visit your dashboard: https://yourusername.github.io/SportSync/
4. Done! Data updates automatically every 6 hours

2. Local Development

git clone https://github.com/chaerem/SportSync.git
cd SportSync
npm run dev
# Open http://localhost:8000

🏃‍♂️ Live Demo

See it in action: chaerem.github.io/SportSync

📊 Sports Coverage

Sport	Data Source	Coverage
⚽ Football	ESPN API	Premier League, La Liga, Eliteserien
🎾 Tennis	ESPN API	ATP, WTA, Grand Slams
🏌️ Golf	ESPN API	PGA Tour, DP World Tour, Majors
🏎️ Formula 1	ESPN Racing API	Full race calendar + practice/qualifying
♟️ Chess	Curated Data	Major tournaments, Norwegian focus
🎮 Esports	HLTV API	CS2 competitions (FaZe/rain focus)

🎨 Design Philosophy

The CALM Principle

SportSync is designed to be instantly scannable without overwhelming users:

┌─────────────────────────────────────┐
│ TODAY              🟢 FOOTBALL      │  ← Day + Sport Badge
├─────────────────────────────────────┤
│ 19:45                               │  ← Large, clear time
│                                     │
│ Arsenal vs Manchester City          │  ← Event title
│ Premier League • Emirates Stadium   │  ← Competition & venue
└─────────────────────────────────────┘

Perfect for everyone:

• Grandparents: Large text, obvious controls, zero confusion
• Tech users: Efficient scanning, comprehensive data
• Mobile users: Touch-friendly, readable on any screen
• Quick checks: Essential info visible at a glance

Time Display Strategy

All events show in Norwegian time (Europe/Oslo) using 24-hour format:

• Today: "TODAY 19:45"
• Tomorrow: "TOMORROW 14:30"
• This week: "FRIDAY 16:00"
• Future: "SUN, DEC 15 12:30"

🏗️ Architecture

GitHub Actions (every 6 hours)
    ↓
Fetch fresh sports data from APIs
    ↓
Generate unified events.json + individual sport files
    ↓
Commit to repository → GitHub Pages deploys
    ↓
Users see updated dashboard instantly

File Structure

docs/                           # GitHub Pages root
├── index.html                  # Main dashboard (all-in-one file)
├── js/
│   ├── simple-dashboard.js     # CALM dashboard controller  
│   └── sports-api.js           # API integration layer
├── data/                       # Auto-generated by GitHub Actions
│   ├── events.json             # ⭐ Unified events feed (main data source)
│   ├── events.ics              # Calendar export
│   ├── football.json           # Per-sport source files
│   ├── tennis.json
│   ├── golf.json
│   ├── f1.json
│   ├── chess.json
│   ├── esports.json
│   └── meta.json               # Update timestamps
└── sw.js                       # Service worker for offline support

scripts/                        # Data fetching & processing
├── fetch/                      # Modular API fetchers
│   ├── football.js
│   ├── tennis.js
│   ├── golf.js
│   ├── f1.js
│   ├── chess.js
│   └── esports.js
├── config/                     # Curated configs
│   ├── chess-tournaments.json
│   └── norwegian-chess-players.json
├── build-events.js             # Creates unified events.json
├── build-ics.js                # Generates calendar export
└── validate-events.js          # Data integrity checks

.github/workflows/
└── update-sports-data.yml      # Automation pipeline

⚙️ How It Works

🤖 Automated Data Pipeline

The entire system runs serverlessly using only GitHub infrastructure:

1. GitHub Actions trigger every 6 hours (00:00, 06:00, 12:00, 18:00 UTC)
2. Node.js scripts fetch fresh data from ESPN, HLTV, and curated sources
3. Unified events.json gets generated with all upcoming events sorted chronologically
4. Calendar export (.ics) created for external calendar apps
5. Auto-commit pushes updated data to repository
6. GitHub Pages instantly deploys the updated dashboard

📱 Client-Side Strategy

The dashboard loads only one file (events.json) for maximum performance:

• Cached data first - instant loading from GitHub CDN
• Graceful fallback - handles API outages seamlessly
• Offline support - service worker caches everything
• Minimal JavaScript - <10KB total, works on any device

🛠️ Development

Available Scripts

npm run dev        # Start local development server
npm run build      # Fetch data + build events + calendar
npm run test       # Validate data integrity
npm run clean      # Remove all generated data files
npm run refresh    # Clean + full rebuild

Data Pipeline Commands

npm run update:data     # Fetch fresh API data
npm run build:events    # Generate unified events.json  
npm run build:calendar  # Create calendar export (.ics)
npm run validate:data   # Check data integrity

Adding New Sports

1. Create fetcher: Add scripts/fetch/newsport.js
2. Update pipeline: Import in scripts/fetch/index.js
3. Add to dashboard: Update sport badges in docs/index.html
4. Test locally: npm run refresh

Customizing Focus

Edit sport priorities and Norwegian focus:

• Chess tournaments: scripts/config/chess-tournaments.json
• Norwegian players: scripts/config/norwegian-chess-players.json
• API endpoints: Individual fetcher files in scripts/fetch/

🔧 Deployment Options

GitHub Pages (Recommended)

• ✅ Free hosting
• ✅ Automatic updates
• ✅ Custom domain support
• ✅ Global CDN

Alternative Platforms

• Netlify: Connect your GitHub repo for auto-deploys
• Vercel: Import project, deploy from /docs folder
• Cloudflare Pages: GitHub integration with edge performance

📅 Calendar Integration

SportSync generates a standard .ics calendar file at /docs/data/events.ics:

• Subscribe in any calendar app (Google Calendar, Apple Calendar, Outlook)
• Auto-updates every 6 hours with fresh sports events
• Includes participants for chess tournaments and team sports
• Norwegian timezone for accurate local times

🎯 Why SportSync?

In a world of cluttered sports apps and overwhelming dashboards, SportSync returns to simplicity:

• No notifications - just information when you need it
• No accounts - works instantly for everyone
• No premium features - everything is free and open source
• No bloat - pure HTML/CSS/JS, works on any device
• No maintenance - set it and forget it

Perfect for checking your daily sports schedule over morning coffee or planning your weekend viewing. ☕️🏆

🤝 Contributing

We welcome contributions that maintain the CALM principle:

1. Fork the repository
2. Keep changes simple and user-focused
3. Test on both mobile and desktop
4. Ensure accessibility and readability
5. Create a Pull Request with clear description

📄 License

MIT License - feel free to create your own sports dashboard!

---

Built with ❤️ for sports fans who value simplicity over complexity.