How zhanyulong/running works
Project type and purpose
• This is a full-stack, static “running page” website that uses Python scripts to ingest/sync workout data from many external services and a React/Vite front-end to render a static site.
• GitHub Actions (or Vercel/Cloudflare) orchestrate the data sync, build, and deploy steps.
File structure
Top-level directories and files reveal two major subsystems:
a. run_page/… (Python) – data-sync adapters and generators
b. src/… (TypeScript + React) – front-end SPA code, hooks, components, static data
Plus:
• OUT folders (FIT_OUT, GPX_OUT, TCX_OUT) for raw downloaded files
• config-example.yaml, requirements.txt, package.json, Dockerfile, CI workflows (.github/workflows)
• Data artifacts: run_page/data.db, imported.json, src/static/*.json
README for additional insights
• Adapters for Garmin, Strava, Nike, GPX, TCX, FIT, Keep, Coros, etc.
• A SQLite store + JSON exports + SVG generators
• React SPA using Mapbox and React Hooks
• Automated CI/CD via GitHub Actions → build → deploy to Vercel/GH-Pages/Cloudflare
Main components & interactions
a. External Services (Strava, Garmin, Nike, GPX files, TCX files, Keep, Coros, etc.)
b. CI/CD Runner (GitHub Actions / Vercel / Cloudflare)
c. Python Data Sync Layer (run_page/*.py)
– Adapters invoke each external API or process files → save raw files in OUT/ → persist normalized data in data.db → export JSON + backup GPX/TCX/FIT
– SVG generators (gen_svg.py, gpxtrackposter) produce visual assets
d. Static-Site Build Layer (Node + pnpm + Vite)
– Reads JSON and assets under src/static + activities → bundles React SPA → outputs dist/
e. Hosting (Vercel / GitHub Pages / Cloudflare Pages)
f. Client Browser (end-user visits the static site)
Data flow:
External Services → (1) Python Adapters → Data Storage & File Outputs → (2) Static-Site Build → (3) Hosting → Client
Architectural patterns and design principles
• Adapter pattern (one Python module per external service)
• Separation of concerns: data ingestion vs presentation
• Static-site generation: build-time injection of JSON + SVG into a SPA
• CI/CD pipeline integration: automated, repeatable data sync + build + deploy
Final checklist
• Clear component labels (e.g. “run_page/garmin_sync.py”, “Node/Vite Build”)
• Logical grouping (e.g. “CI/CD Pipeline”, “Data Layer”, “Presentation Layer”)
• Call out external dependencies (Mapbox token, GitHub Secrets, Python & Node runtimes)