# sofardogood/f1-calendar architecture

> Architecture diagram of the GitHub repository sofardogood/f1-calendar, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sofardogood/f1-calendar
- Repository: https://github.com/sofardogood/f1-calendar

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "CI/CD Pipeline" 
    GH[("GitHub Actions Runner\n(update-f1-data.yml cron: 0 3 * * *)")]:::cicd
    UpdateScripts[/"Data-Update Scripts\n(updateF1Data.ts, parseYearlyCSV.ts,\nexportYearToCSV.ts, ...)"/]:::data
    CSVArchive[("CSV Archives\n(F1-2020-...csv)")]:::data
    JSON[("f1_data.json")]:::frontend
    RepoCommit[("Main Branch Commit")]:::cicd
    VercelBuild[("Vercel Build & Deploy")]:::cicd

    GH -->|"runs"| UpdateScripts
    UpdateScripts -->|"reads"| CSVArchive
    UpdateScripts -->|"writes"| JSON
    JSON -->|"git commit"| RepoCommit
    RepoCommit -->|"triggers"| VercelBuild
  end

  subgraph "Vercel Deployment"
    CDN[("Vercel CDN\nStatic Hosting")]:::frontend
    Serverless[("Vercel Serverless Functions\nExpress/tRPC API")]:::backend

    CDN -->|"serves static assets"| Browser[("Browser\n(User Interface)")]:::frontend
    Browser -->|"loads SPA"| Main
    Browser -->|"GET JSON"| JSON
    Browser -->|"tRPC call"| Serverless

    Main["main.tsx"]:::frontend
    App["App.tsx"]:::frontend
    Calendar["Calendar.tsx"]:::frontend
    Standings["Standings.tsx"]:::frontend
    Statistics["Statistics.tsx"]:::frontend
    History["History.tsx"]:::frontend
    UIComponents["UI Components\n(client/src/components/ui/)"]:::frontend
    Hooks["useAuth.ts"]:::frontend
    ThemeCtx["ThemeContext.tsx"]:::frontend

    Main --> App
    App --> Calendar
    App --> Standings
    App --> Statistics
    App --> History
    App --> UIComponents
    App --> Hooks
    App --> ThemeCtx

    Serverless --> TRPCRouter["trpc.ts & routers.ts"]:::backend
    TRPCRouter --> Context["context.ts"]:::backend
    TRPCRouter --> Env["env.ts"]:::backend
    TRPCRouter --> Services["API & Cache Services"]:::backend

    subgraph "Services"
      ErgastApi["ergastApi.ts"]:::external
      ErgastSvc["ergastService.ts"]:::external
      OpenF1["openF1Service.ts"]:::external
      Wiki["wikipediaScraper.ts"]:::external
      Cache["cacheService.ts"]:::backend

      Services --> ErgastApi
      Services --> ErgastSvc
      Services --> OpenF1
      Services --> Wiki
      Services --> Cache
    end

    Serverless -->|"SQL Query"| DB[("MySQL Database\n(Drizzle ORM)")]:::db
    DB --> Schema["schema.ts\nrelations.ts\nmigrations/"]:::db
  end

  subgraph "Shared Layer"
    SharedTypes["types.ts\nconst.ts"]:::frontend
    SharedTypes --> App
    SharedTypes --> TRPCRouter
  end

  classDef frontend fill:#D0E8FF,stroke:#333,stroke-width:1px
  classDef backend fill:#D0FFD8,stroke:#333,stroke-width:1px
  classDef cicd fill:#FFE8C0,stroke:#333,stroke-width:1px
  classDef data fill:#FFE0E0,stroke:#333,stroke-width:1px
  classDef external fill:#E0E0E0,stroke:#333,stroke-width:1px
  classDef db fill:#FFF0D0,stroke:#333,stroke-width:1px

  click Main "https://github.com/sofardogood/f1-calendar/blob/main/client/src/main.tsx"
  click App "https://github.com/sofardogood/f1-calendar/blob/main/client/src/App.tsx"
  click Calendar "https://github.com/sofardogood/f1-calendar/blob/main/client/src/pages/Calendar.tsx"
  click Standings "https://github.com/sofardogood/f1-calendar/blob/main/client/src/pages/Standings.tsx"
  click Statistics "https://github.com/sofardogood/f1-calendar/blob/main/client/src/pages/Statistics.tsx"
  click History "https://github.com/sofardogood/f1-calendar/blob/main/client/src/pages/History.tsx"
  click UIComponents "https://github.com/sofardogood/f1-calendar/tree/main/client/src/components/ui/"
  click Hooks "https://github.com/sofardogood/f1-calendar/blob/main/client/src/_core/hooks/useAuth.ts"
  click ThemeCtx "https://github.com/sofardogood/f1-calendar/blob/main/client/src/contexts/ThemeContext.tsx"
  click JSON "https://github.com/sofardogood/f1-calendar/blob/main/client/src/f1_data.json"
  click UpdateScripts "https://github.com/sofardogood/f1-calendar/blob/main/server/scripts/updateF1Data.ts"
  click CSVArchive "https://github.com/sofardogood/f1-calendar/blob/main/F1-2020-races.csv"
  click Serverless "https://github.com/sofardogood/f1-calendar/blob/main/server/index.ts"
  click TRPCRouter "https://github.com/sofardogood/f1-calendar/blob/main/server/routers.ts"
  click Context "https://github.com/sofardogood/f1-calendar/blob/main/server/_core/context.ts"
  click Env "https://github.com/sofardogood/f1-calendar/blob/main/server/_core/env.ts"
  click ErgastApi "https://github.com/sofardogood/f1-calendar/blob/main/server/services/ergastApi.ts"
  click ErgastSvc "https://github.com/sofardogood/f1-calendar/blob/main/server/services/ergastService.ts"
  click OpenF1 "https://github.com/sofardogood/f1-calendar/blob/main/server/services/openF1Service.ts"
  click Wiki "https://github.com/sofardogood/f1-calendar/blob/main/server/services/wikipediaScraper.ts"
  click Cache "https://github.com/sofardogood/f1-calendar/blob/main/server/services/cacheService.ts"
  click Schema "https://github.com/sofardogood/f1-calendar/blob/main/drizzle/schema.ts"
  click SharedTypes "https://github.com/sofardogood/f1-calendar/blob/main/shared/types.ts"
```
