How sofardogood/f1-calendar works
Project Type and Purpose
• This is a full-stack F1 Calendar web application with a statically rendered React front end and a Node-based back end (tRPC/Express/Drizzle) deployed via Vercel. It provides F1 race schedules, standings, and statistics, supports automated data updates via GitHub Actions, and archives historical data in CSV.
File Structure Analysis
• Top-level directories:
• client/ – React + TypeScript + Vite + Tailwind front end
• server/ – Node/Express/tRPC server code, data-update scripts, environment config
• drizzle/ – Database schema, migrations (Drizzle ORM + MySQL)
• shared/ – Shared TypeScript types and constants
• .github/workflows – CI jobs (data update)
• Configuration/build files: pnpm-lock.yaml, tsconfig.json, vite.config.ts, vercel.json
• Data files: F1-YYYY-*.csv archives, f1_data.json in client/src, server scripts to parse/update data
• CI job “update-f1-data.yml” scrapes external sources, commits updated f1_data.json, triggers Vercel redeploy.
Architecture from README
• Static site prebuilt and served by Vercel
• GitHub Actions cron job for data scraping and JSON regeneration
• Optionally a live back end (serverless functions) for tRPC API endpoints, Drizzle-managed MySQL database, and external F1 data providers (Ergast, OpenF1, Wikipedia).
Main Components and Interactions
a. Frontend (client/):
• React SPA rendered by Vite, deployed as static assets
• UI components (Calendar, Standings, Statistics) fetch data via:
– client/src/f1_data.json (pre-baked season data)
– tRPC endpoints (optional live updates)
b. Backend / Serverless (server/ + drizzle/):
• TRPC router exposing race info services
• Drizzle ORM connecting to MySQL2 (DATABASE_URL) for persistent stats or caching
• Services: Ergast API, OpenF1, Wikipedia scraper, cacheService
• Utility scripts (updateF1Data.ts, parseYearlyCSV.ts, exportYearToCSV.ts) for data generation
c. CI/CD Pipeline (GitHub Actions + Vercel):
• Cron workflow (update-f1-data.yml) runs scraping script
• Commits updated f1_data.json to main branch
• Vercel picks up changes → rebuild/dist → static hosting + serverless endpoints
d. Data Archives:
• CSV files at repo root for each season (races, sessions, results)
• Scripts parse/import these into f1_data.json for historical lookup
Architectural Patterns and Principles
• Jamstack: pre-render static content + serverless endpoints for dynamic features
• Separation of concerns:
• client/ for UI, hooks, components
• server/ for business logic, data ingestion, and API surface
• drizzle/ for database schema & migrations
• shared/ for cross-cutting types & constants
• Code generation & type safety: tRPC end-to-end types, TypeScript shared types
• Automated data pipeline: GitHub Actions → scripts → JSON → redeploy