# msstoci/running_page architecture

> Architecture diagram of the GitHub repository msstoci/running_page, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/msstoci/running_page
- Repository: https://github.com/msstoci/running_page

## Overview

Running Page collects and synchronizes workout records from fitness services and files, then presents the resulting activity data as a personal running website. The browser loads the published activity JSON and renders it through a selectable dashboard or classic theme, with activity summaries and route-oriented views. The repository also includes a terminal activity browser and route-poster generation. The README documents the sync and data-update workflow; sampled code supports the frontend loading and rendering relationships, but does not establish all backend adapter wiring.

Main entry points: [`run_page/generator/db.py`](https://github.com/msstoci/running_page/blob/master/run_page/generator/db.py) (Activity database), [`src/themes/dashboard/index.tsx`](https://github.com/msstoci/running_page/blob/master/src/themes/dashboard/index.tsx) (Dashboard theme), [`src/App.tsx`](https://github.com/msstoci/running_page/blob/master/src/App.tsx) (App and themes), [`src/components/TracksPage.tsx`](https://github.com/msstoci/running_page/blob/master/src/components/TracksPage.tsx) (Track views)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sync["Activity synchronization"]
  node_sync_adapters["Service sync adapters"]
  node_file_sync["GPX/TCX/FIT sync<br/>[gpx_sync.py]"]
  node_transfer["Service transfers"]
end

subgraph group_data["Data and visualization"]
  node_db_update["Database updater<br/>[db_updater.py]"]
  node_activity_db[("Activity database<br/>[db.py]")]
  node_csv_export["CSV export<br/>[data_to_csv.py]"]
  node_poster["Track posters<br/>[poster.py]"]
end

subgraph group_web["Personal website"]
  node_activity_json["Published activities"]
  node_web_entry["React entry<br/>[main.tsx]"]
  node_app["App and themes<br/>[App.tsx]"]
  node_dashboard["Dashboard theme<br/>[index.tsx]"]
  node_classic["Classic theme<br/>[index.tsx]"]
  node_activity_loader["Activity loading<br/>[useActivities.ts]"]
  node_classic_loader["Classic activity data<br/>[useActivities.ts]"]
  node_summary["Activity summaries<br/>[SummaryPage.tsx]"]
  node_tracks["Track views<br/>[TracksPage.tsx]"]
  node_route_map["Route maps<br/>[RouteMap.tsx]"]
  node_cluster_worker["Track clustering"]
end

subgraph group_terminal["Terminal browser"]
  node_tui["Terminal activity browser<br/>[app.py]"]
  node_tui_data["Terminal data model<br/>[data.py]"]
end

node_runner(("Page owner"))
node_fitness{{"Fitness services"}}
node_activityfiles["Activity files"]
node_visitor(("Website visitor"))

node_runner -->|"starts sync"| node_sync_adapters
node_fitness -.->|"provides records"| node_sync_adapters
node_activityfiles -->|"provides tracks"| node_file_sync
node_runner -->|"starts import"| node_file_sync
node_runner -->|"starts transfer"| node_transfer
node_sync_adapters -->|"writes activities"| node_activity_db
node_file_sync -->|"writes activities"| node_activity_db
node_transfer -.->|"transfers activities"| node_fitness
node_db_update -->|"updates schema"| node_activity_db
node_activity_db -->|"reads activities"| node_csv_export
node_activity_db -->|"supplies tracks"| node_poster
node_activity_db -->|"exports data"| node_activity_json
node_visitor -->|"opens page"| node_web_entry
node_web_entry -->|"renders"| node_app
node_app -->|"selects theme"| node_dashboard
node_app -->|"selects theme"| node_classic
node_dashboard -->|"loads activities"| node_activity_loader
node_classic -->|"loads activities"| node_classic_loader
node_activity_loader -->|"fetches JSON"| node_activity_json
node_classic_loader -->|"fetches JSON"| node_activity_json
node_dashboard -->|"renders summaries"| node_summary
node_dashboard -->|"renders tracks"| node_tracks
node_tracks -->|"renders routes"| node_route_map
node_tracks -->|"clusters tracks"| node_cluster_worker
node_tui -->|"loads activity data"| node_tui_data

click node_sync_adapters "https://github.com/msstoci/running_page/tree/master/run_page"
click node_file_sync "https://github.com/msstoci/running_page/blob/master/run_page/gpx_sync.py"
click node_transfer "https://github.com/msstoci/running_page/blob/master/run_page/garmin_to_strava_sync.py"
click node_db_update "https://github.com/msstoci/running_page/blob/master/run_page/db_updater.py"
click node_activity_db "https://github.com/msstoci/running_page/blob/master/run_page/generator/db.py"
click node_csv_export "https://github.com/msstoci/running_page/blob/master/run_page/data_to_csv.py"
click node_poster "https://github.com/msstoci/running_page/blob/master/run_page/gpxtrackposter/poster.py"
click node_web_entry "https://github.com/msstoci/running_page/blob/master/src/main.tsx"
click node_app "https://github.com/msstoci/running_page/blob/master/src/App.tsx"
click node_dashboard "https://github.com/msstoci/running_page/blob/master/src/themes/dashboard/index.tsx"
click node_classic "https://github.com/msstoci/running_page/blob/master/src/themes/classic/index.tsx"
click node_activity_loader "https://github.com/msstoci/running_page/blob/master/src/core/hooks/useActivities.ts"
click node_classic_loader "https://github.com/msstoci/running_page/blob/master/src/themes/classic/hooks/useActivities.ts"
click node_summary "https://github.com/msstoci/running_page/blob/master/src/components/SummaryPage.tsx"
click node_tracks "https://github.com/msstoci/running_page/blob/master/src/components/TracksPage.tsx"
click node_route_map "https://github.com/msstoci/running_page/blob/master/src/components/RouteMap.tsx"
click node_cluster_worker "https://github.com/msstoci/running_page/blob/master/src/workers/clusterTracks.worker.ts"
click node_tui "https://github.com/msstoci/running_page/blob/master/run_page/tui/app.py"
click node_tui_data "https://github.com/msstoci/running_page/blob/master/run_page/tui/data.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_sync_adapters,node_file_sync,node_transfer toneBlue
class node_db_update,node_activity_db,node_csv_export,node_poster toneAmber
class node_activity_json,node_web_entry,node_app,node_dashboard,node_classic,node_activity_loader,node_classic_loader,node_summary,node_tracks,node_route_map,node_cluster_worker toneMint
class node_tui,node_tui_data toneRose
class node_runner,node_fitness,node_activityfiles,node_visitor toneIndigo
```

## Components

### Activity synchronization

- [Service sync adapters](https://github.com/msstoci/running_page/tree/master/run_page): `run_page`
- [GPX/TCX/FIT sync](https://github.com/msstoci/running_page/blob/master/run_page/gpx_sync.py): `run_page/gpx_sync.py`
- [Service transfers](https://github.com/msstoci/running_page/blob/master/run_page/garmin_to_strava_sync.py): `run_page/garmin_to_strava_sync.py`

### Data and visualization

- [Database updater](https://github.com/msstoci/running_page/blob/master/run_page/db_updater.py): `run_page/db_updater.py`
- [Activity database](https://github.com/msstoci/running_page/blob/master/run_page/generator/db.py): `run_page/generator/db.py`
- [CSV export](https://github.com/msstoci/running_page/blob/master/run_page/data_to_csv.py): `run_page/data_to_csv.py`
- [Track posters](https://github.com/msstoci/running_page/blob/master/run_page/gpxtrackposter/poster.py): `run_page/gpxtrackposter/poster.py`

### Personal website

- **Published activities**
- [React entry](https://github.com/msstoci/running_page/blob/master/src/main.tsx): `src/main.tsx`
- [App and themes](https://github.com/msstoci/running_page/blob/master/src/App.tsx): `src/App.tsx`
- [Dashboard theme](https://github.com/msstoci/running_page/blob/master/src/themes/dashboard/index.tsx): `src/themes/dashboard/index.tsx`
- [Classic theme](https://github.com/msstoci/running_page/blob/master/src/themes/classic/index.tsx): `src/themes/classic/index.tsx`
- [Activity loading](https://github.com/msstoci/running_page/blob/master/src/core/hooks/useActivities.ts): `src/core/hooks/useActivities.ts`
- [Classic activity data](https://github.com/msstoci/running_page/blob/master/src/themes/classic/hooks/useActivities.ts): `src/themes/classic/hooks/useActivities.ts`
- [Activity summaries](https://github.com/msstoci/running_page/blob/master/src/components/SummaryPage.tsx): `src/components/SummaryPage.tsx`
- [Track views](https://github.com/msstoci/running_page/blob/master/src/components/TracksPage.tsx): `src/components/TracksPage.tsx`
- [Route maps](https://github.com/msstoci/running_page/blob/master/src/components/RouteMap.tsx): `src/components/RouteMap.tsx`
- [Track clustering](https://github.com/msstoci/running_page/blob/master/src/workers/clusterTracks.worker.ts): `src/workers/clusterTracks.worker.ts`

### Terminal browser

- [Terminal activity browser](https://github.com/msstoci/running_page/blob/master/run_page/tui/app.py): `run_page/tui/app.py`
- [Terminal data model](https://github.com/msstoci/running_page/blob/master/run_page/tui/data.py): `run_page/tui/data.py`

### Other components

- **Page owner**
- **Fitness services**
- **Activity files**
- **Website visitor**

## Connections

- Page owner → Service sync adapters: starts sync
- Fitness services → Service sync adapters: provides records
- Activity files → GPX/TCX/FIT sync: provides tracks
- Page owner → GPX/TCX/FIT sync: starts import
- Page owner → Service transfers: starts transfer
- Service sync adapters → Activity database: writes activities
- GPX/TCX/FIT sync → Activity database: writes activities
- Service transfers → Fitness services: transfers activities
- Database updater → Activity database: updates schema
- Activity database → CSV export: reads activities
- Activity database → Track posters: supplies tracks
- Activity database → Published activities: exports data
- Website visitor → React entry: opens page
- React entry → App and themes: renders
- App and themes → Dashboard theme: selects theme
- App and themes → Classic theme: selects theme
- Dashboard theme → Activity loading: loads activities
- Classic theme → Classic activity data: loads activities
- Activity loading → Published activities: fetches JSON
- Classic activity data → Published activities: fetches JSON
- Dashboard theme → Activity summaries: renders summaries
- Dashboard theme → Track views: renders tracks
- Track views → Route maps: renders routes
- Track views → Track clustering: clusters tracks
- Terminal activity browser → Terminal data model: loads activity data