How the backend works

Information Flow

What Each Service Does

Google Sheets stores the planned marathon build, Strava actual writeback fields, supplement checkbox history, and nutrition history. You can adjust daily estimated mileage, session notes, weekly summaries, phase details, supplement checkboxes, and meal-level nutrition rows there.

Strava API provides actual runs: distance, time, pace, elevation, heart rate and cadence when Strava includes them, activity names, dates, and Strava links.

Cloudflare Worker is the live Strava sync worker. It receives Strava webhook events, refreshes Strava tokens privately, fetches changed activities, and stores sanitized actual-run JSON in Workers KV.

GitHub Actions is the private Sheet and deployment worker. It reads the Google service account secret, optionally calls OpenAI for nutrition estimates, fetches the Sheet, and prepares the static deployment output.

OpenAI API is used only by the private workflow script when an OPENAI_API_KEY secret is configured. The public site never calls OpenAI directly.

GitHub Pages and Cloudflare Pages are public static hosts. They have no API secrets in frontend JavaScript.

Repository Map

sckl-marathon-dashboard/
|-- index.html                    # Main static dashboard
|-- nutrition.html                # Standalone nutrition tracker
|-- backend.html                  # Technical architecture page
|-- race.html                     # Race execution page
|-- styles.css                    # Shared visual system
|-- app.js                        # Browser rendering, charts, status, and comparisons
|-- nutrition.js                  # Nutrition page rendering and empty states
|-- race.js                       # Pace calculator and race page interactions
|-- data/
|   |-- training-plan.json        # Generated Google Sheets plan
|   |-- strava-activities.json    # Generated Strava run data
|   |-- supplements.json          # Generated Google Sheets supplement history
|   |-- nutrition.json            # Generated Google Sheets nutrition history
|   |-- mock-training-plan.json   # Local fallback plan
|   |-- mock-strava-activities.json
|   |-- mock-supplements.json
|   `-- mock-nutrition.json
|-- scripts/
|   |-- fetch_google_sheet.py     # Reads and normalises Google Sheet rows
|   |-- process_nutrition_ai.py   # Private raw food log -> nutrition estimate writer
|   |-- fetch_strava.py           # Refreshes Strava token and fetches runs
|   |-- sync_strava_actuals_to_sheet.py # Writes run actuals back to the plan
|   |-- sync_training_calendar.py # Syncs planned runs into Google Calendar
|   `-- exchange_strava_code.py   # One-time OAuth helper
|-- .github/workflows/
|   |-- deploy-pages.yml          # Scheduled/manual sync and Pages deploy
|   `-- sync-calendar.yml         # Manual training calendar sync
|-- requirements.txt
|-- .env.example
`-- README.md

Workflow Responsibilities

Pace Range Derivation

The pace table is a practical coaching estimate, not a lab result. It starts from recent performance anchors, converts those into equivalent training intensities, then widens the final ranges for Singapore heat, humidity, hills, and day-to-day fatigue.

Secrets And Runtime Config

Data Contract

data/training-plan.json contains the plan from Google Sheets: week number, week start date, phase, weekly mileage, daily sessions, daily actual writeback fields, long run target, weekly summary, and notes.

data/strava-activities.json contains the generated actual training data used by the dashboard: athlete profile, sync timestamp, run distance, moving time, elapsed time, elevation, heart rate, cadence, activity names, dates, and Strava links.

data/supplements.json contains read-only supplement checkbox history from the Supplements tab: date, week, training phase, supplement names, and whether each supplement was taken.

data/nutrition.json contains read-only meal-level nutrition rows from the Nutrition tab, plus daily totals and rolling seven-day calorie and protein averages. The sync reads columns A:T by header name, but only public nutrition fields are written into the generated JSON; raw food logs, guidelines, AI status, timestamps, and errors remain Sheet workflow columns.

{
  "metadata": { "generated_at": "2026-05-11T12:00:00+08:00" },
  "weeks": [
    {
      "week_number": 1,
      "week_start_date": "2026-05-11",
      "phase": "Base",
      "target_weekly_mileage_km": 61,
      "week_summary": "Base week with 61 km across 5 planned runs..."
    }
  ]
}

Privacy And Limits

The website is public, so anything written into generated JSON can be viewed by anyone with the site link. API secrets are private, but published activity metrics are public.

Nutrition rows are public once synced into data/nutrition.json, so only track food items, assumptions, and notes you are comfortable showing on the public dashboard.

The frontend does not call OpenAI or any other estimation API directly. AI-assisted nutrition estimates are generated in GitHub Actions or locally, written into Google Sheets, then synced as static JSON.

If a Strava token or Google service account key is ever shared outside the secret stores, rotate it and update GitHub Actions secrets.

The dashboard is a training visibility tool, not a coaching or medical system. Risk flags and progress views should guide decisions, not replace judgement around injury, sleep, heat, or recovery.

Technical Reference

Source code and setup notes live in the GitHub repository.

The manual sync workflow is available at deploy-pages.yml.

The manual calendar sync workflow is available at sync-calendar.yml.