# zhanyulong/running architecture

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

- Interactive diagram: https://gitdiagram.com/zhanyulong/running
- Repository: https://github.com/zhanyulong/running

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Services
    subgraph "External Services" 
        direction TB
        Strava["Strava"]:::external
        Garmin["Garmin"]:::external
        Nike["Nike"]:::external
        GPXFile["GPX Files"]:::external
        TCXFile["TCX Files"]:::external
        FITFile["FIT Files"]:::external
        Keep["Keep"]:::external
        Coros["Coros"]:::external
        Endomondo["Endomondo"]:::external
        Joyrun["Joyrun"]:::external
        Oppo["Oppo"]:::external
        TulipSport["TulipSport"]:::external
    end

    %% CI/CD Runner
    subgraph "CI/CD Pipeline" 
        direction TB
        Actions["GitHub Actions Workflows"]:::hosting
    end

    %% Python Sync Layer
    subgraph "Python Data Sync Layer" 
        direction TB
        subgraph "Adapters" 
            direction TB
            StravaSync["strava_sync.py"]:::python
            GarminSync["garmin_sync.py"]:::python
            NikeSync["nike_sync.py"]:::python
            GPXSync["gpx_sync.py"]:::python
            TCXSync["tcx_sync.py"]:::python
            FITSync["fit_sync.py"]:::python
            KeepSync["keep_sync.py"]:::python
            CorosSync["coros_sync.py"]:::python
            EndomondoSync["endomondo_sync.py"]:::python
            JoyrunSync["joyrun_sync.py"]:::python
            OppoSync["oppo_sync.py"]:::python
            TulipSync["tulipsport_sync.py"]:::python
        end
        DataToCSV["data_to_csv.py"]:::python
        SaveParqent["save_to_parqent.py"]:::python
        LogSync["synced_data_file_logger.py"]:::python
        GenSVG["gen_svg.py"]:::python
        TrackPoster["gpxtrackposter/"]:::python
    end

    %% Data Storage
    subgraph "Data Storage" 
        direction TB
        SQLite["run_page/data.db"]:::storage
        RawFIT["FIT_OUT/"]:::storage
        RawGPX["GPX_OUT/"]:::storage
        RawTCX["TCX_OUT/"]:::storage
        ImportedJSON["imported.json"]:::storage
        ActivitiesJSON["src/static/activities.json"]:::storage
    end

    %% Build Layer
    subgraph "Static-Site Build Layer" 
        direction TB
        FrontendSrc["src/"]:::build
        PackageJSON["package.json"]:::build
        LockFile["pnpm-lock.yaml"]:::build
        ViteConfig["vite.config.ts"]:::build
        MainEntry["src/main.tsx"]:::build
        HTMLTemplate["index.html"]:::build
    end

    %% Hosting
    subgraph "Hosting" 
        direction TB
        ConfigVercel["vercel.json"]:::hosting
        Ignore{" .vercelignore"}:::hosting
    end

    %% Client
    Client["Client Browser"]:::external

    %% Connections
    Strava -->|HTTP API| StravaSync
    Garmin -->|HTTP API| GarminSync
    Nike -->|HTTP API| NikeSync
    GPXFile -->|Local Files| GPXSync
    TCXFile -->|Local Files| TCXSync
    FITFile -->|Local Files| FITSync
    Keep -->|HTTP API| KeepSync
    Coros -->|HTTP API| CorosSync
    Endomondo -->|HTTP API| EndomondoSync
    Joyrun -->|HTTP API| JoyrunSync
    Oppo -->|HTTP API| OppoSync
    TulipSport -->|HTTP API| TulipSync

    Actions -->|runs CLI scripts| StravaSync
    Actions -->|runs CLI scripts| GarminSync
    Actions -->|runs CLI scripts| DataToCSV
    Actions -->|runs CLI scripts| GenSVG
    Actions -->|runs CLI scripts| TrackPoster
    StravaSync -->|normalized data| SQLite
    GarminSync -->|normalized data| SQLite
    NikeSync -->|normalized data| SQLite
    GPXSync -->|copies raw| RawGPX
    TCXSync -->|copies raw| RawTCX
    FITSync -->|copies raw| RawFIT
    DataToCSV -->|exports JSON| ImportedJSON
    SaveParqent -->|persists| SQLite
    LogSync -->|logs| ImportedJSON
    GenSVG -->|generates SVGs| ActivitiesJSON
    TrackPoster -->|generates posters| ActivitiesJSON

    Actions -->|triggers build| PackageJSON
    PackageJSON -->|configures| FrontendSrc
    LockFile -->|locks deps| FrontendSrc
    ViteConfig -->|build config| FrontendSrc
    FrontendSrc -->|build| MainEntry
    MainEntry -->|renders| HTMLTemplate

    HTMLTemplate -->|deploy| Client
    Actions -->|deploys| ConfigVercel
    Actions -->|deploys| Ignore
    Client -->|fetches static assets| ActivitiesJSON

    %% Click Events
    click StravaSync "https://github.com/zhanyulong/running/blob/main/run_page/strava_sync.py"
    click GarminSync "https://github.com/zhanyulong/running/blob/main/run_page/garmin_sync.py"
    click NikeSync "https://github.com/zhanyulong/running/blob/main/run_page/nike_sync.py"
    click GPXSync "https://github.com/zhanyulong/running/blob/main/run_page/gpx_sync.py"
    click TCXSync "https://github.com/zhanyulong/running/blob/main/run_page/tcx_sync.py"
    click FITSync "https://github.com/zhanyulong/running/blob/main/run_page/fit_sync.py"
    click KeepSync "https://github.com/zhanyulong/running/blob/main/run_page/keep_sync.py"
    click CorosSync "https://github.com/zhanyulong/running/blob/main/run_page/coros_sync.py"
    click EndomondoSync "https://github.com/zhanyulong/running/blob/main/run_page/endomondo_sync.py"
    click JoyrunSync "https://github.com/zhanyulong/running/blob/main/run_page/joyrun_sync.py"
    click OppoSync "https://github.com/zhanyulong/running/blob/main/run_page/oppo_sync.py"
    click TulipSync "https://github.com/zhanyulong/running/blob/main/run_page/tulipsport_sync.py"
    click DataToCSV "https://github.com/zhanyulong/running/blob/main/run_page/data_to_csv.py"
    click SaveParqent "https://github.com/zhanyulong/running/blob/main/run_page/save_to_parqent.py"
    click LogSync "https://github.com/zhanyulong/running/blob/main/run_page/synced_data_file_logger.py"
    click GenSVG "https://github.com/zhanyulong/running/blob/main/run_page/gen_svg.py"
    click TrackPoster "https://github.com/zhanyulong/running/tree/main/run_page/gpxtrackposter/"
    click SQLite "https://github.com/zhanyulong/running/blob/main/run_page/data.db"
    click RawFIT "https://github.com/zhanyulong/running/tree/main/FIT_OUT/"
    click RawGPX "https://github.com/zhanyulong/running/tree/main/GPX_OUT/"
    click RawTCX "https://github.com/zhanyulong/running/tree/main/TCX_OUT/"
    click ImportedJSON "https://github.com/zhanyulong/running/blob/main/imported.json"
    click ActivitiesJSON "https://github.com/zhanyulong/running/blob/main/src/static/activities.json"
    click FrontendSrc "https://github.com/zhanyulong/running/tree/main/src/"
    click PackageJSON "https://github.com/zhanyulong/running/blob/main/package.json"
    click LockFile "https://github.com/zhanyulong/running/blob/main/pnpm-lock.yaml"
    click ViteConfig "https://github.com/zhanyulong/running/blob/main/vite.config.ts"
    click MainEntry "https://github.com/zhanyulong/running/blob/main/src/main.tsx"
    click HTMLTemplate "https://github.com/zhanyulong/running/blob/main/index.html"
    click Actions "https://github.com/zhanyulong/running/blob/main/.github/workflows/run_data_sync.yml"
    click ConfigVercel "https://github.com/zhanyulong/running/blob/main/vercel.json"
    click Ignore "https://github.com/zhanyulong/running/blob/main/.vercelignore"

    %% Styles
    classDef external fill:#ddd,stroke:#333,stroke-width:1px
    classDef python fill:#aee,stroke:#333,stroke-width:1px
    classDef storage fill:#fea,stroke:#333,stroke-width:1px
    classDef build fill:#afa,stroke:#333,stroke-width:1px
    classDef hosting fill:#cfc,stroke:#333,stroke-width:1px
```
