# matevivan/running-coach architecture

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

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

## Overview

This repository equips coding agents to maintain a privacy-first running-coaching workflow: initialize an athlete workspace, collect recovery data, review runs, and adapt the athlete profile and plan. Separate skills also support FIT parsing and gear research. The README documents the workflow routing, private-data model, and major capabilities; source excerpts were unavailable, so links below reflect documented relationships rather than unverified implementation calls.

Main entry points: [`.agents/skills/initialize-running-project/SKILL.md`](https://github.com/matevivan/running-coach/blob/main/.agents/skills/initialize-running-project/SKILL.md) (Initialize workspace), [`AGENTS.md`](https://github.com/matevivan/running-coach/blob/main/AGENTS.md) (Project instructions), [`.agents/skills/analyze-running-activity/SKILL.md`](https://github.com/matevivan/running-coach/blob/main/.agents/skills/analyze-running-activity/SKILL.md) (Analyze activity), [`.agents/skills/collect-daily-metrics/SKILL.md`](https://github.com/matevivan/running-coach/blob/main/.agents/skills/collect-daily-metrics/SKILL.md) (Collect daily metrics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent["Agent routing"]
  node_constitution["Project instructions<br/>[AGENTS.md]"]
end

subgraph group_athlete["Athlete workflows"]
  node_initialize["Initialize workspace<br/>[SKILL.md]"]
  node_collect["Collect daily metrics<br/>[SKILL.md]"]
  node_analyze["Analyze activity<br/>[SKILL.md]"]
  node_coach["Coach runner<br/>[SKILL.md]"]
  node_parsefit["Parse FIT run<br/>[SKILL.md]"]
  node_gear["Research gear<br/>[SKILL.md]"]
  node_fitparser["FIT file parser<br/>[parse_fit_run.py]"]
end

subgraph group_data["Private data"]
  node_workspace["Private workspace setup"]
  node_privatehistory[("Private athlete history<br/>[001_initial.sql]")]
  node_profile["Runner profile"]
  node_plan["Running plan"]
  node_recovery["Recovery projection"]
end

subgraph group_integrations["External data"]
  node_garminsetup["GarminDB setup"]
  node_dailyread["Read daily metrics"]
  node_recoverysync["Sync recovery data"]
  node_runsync["Sync recent runs"]
  node_runlist["List recent runs"]
  node_weatherfetch["Fetch historical weather"]
  node_garmin[("GarminDB")]
  node_weather["Open-Meteo weather API"]
end

node_runner(("Runner / agent user"))

node_runner -->|"starts task"| node_constitution
node_constitution -->|"routes setup"| node_initialize
node_constitution -->|"routes collection"| node_collect
node_constitution -->|"routes review"| node_analyze
node_constitution -->|"routes coaching"| node_coach
node_constitution -->|"routes research"| node_gear
node_analyze -->|"uses parser"| node_parsefit
node_initialize -->|"creates workspace"| node_workspace
node_initialize -->|"sets up GarminDB"| node_garminsetup
node_garminsetup -->|"configures access"| node_garmin
node_collect -->|"reads metrics"| node_dailyread
node_collect -->|"syncs recovery"| node_recoverysync
node_dailyread -->|"reads"| node_garmin
node_recoverysync -->|"reads"| node_garmin
node_collect -->|"updates projection"| node_recovery
node_analyze -->|"syncs activities"| node_runsync
node_analyze -->|"lists activities"| node_runlist
node_runsync -->|"reads"| node_garmin
node_runlist -->|"reads"| node_garmin
node_analyze -.->|"requests weather"| node_weatherfetch
node_weatherfetch -.->|"queries history"| node_weather
node_analyze -->|"records reviewed run"| node_privatehistory
node_initialize -->|"projects evidence"| node_privatehistory
node_coach -->|"maintains history"| node_privatehistory
node_coach -->|"updates profile"| node_profile
node_coach -->|"updates plan"| node_plan
node_initialize -->|"creates projection"| node_profile
node_initialize -->|"creates projection"| node_plan
node_initialize -->|"creates projection"| node_recovery

click node_constitution "https://github.com/matevivan/running-coach/blob/main/AGENTS.md"
click node_initialize "https://github.com/matevivan/running-coach/blob/main/.agents/skills/initialize-running-project/SKILL.md"
click node_collect "https://github.com/matevivan/running-coach/blob/main/.agents/skills/collect-daily-metrics/SKILL.md"
click node_analyze "https://github.com/matevivan/running-coach/blob/main/.agents/skills/analyze-running-activity/SKILL.md"
click node_coach "https://github.com/matevivan/running-coach/blob/main/.agents/skills/coach-runner/SKILL.md"
click node_parsefit "https://github.com/matevivan/running-coach/blob/main/.agents/skills/parse-fit-run/SKILL.md"
click node_gear "https://github.com/matevivan/running-coach/blob/main/.agents/skills/research-running-gear/SKILL.md"
click node_workspace "https://github.com/matevivan/running-coach/blob/main/.agents/skills/initialize-running-project/scripts/initialize_private_workspace.py"
click node_garminsetup "https://github.com/matevivan/running-coach/blob/main/.agents/skills/initialize-running-project/scripts/setup_garmindb_config.py"
click node_dailyread "https://github.com/matevivan/running-coach/blob/main/.agents/skills/collect-daily-metrics/scripts/read_garmindb_daily.py"
click node_recoverysync "https://github.com/matevivan/running-coach/blob/main/.agents/skills/collect-daily-metrics/scripts/sync_latest_garmindb_recovery.py"
click node_runsync "https://github.com/matevivan/running-coach/blob/main/.agents/skills/analyze-running-activity/scripts/sync_latest_garmindb.py"
click node_runlist "https://github.com/matevivan/running-coach/blob/main/.agents/skills/analyze-running-activity/scripts/list_recent_garmindb_runs.py"
click node_weatherfetch "https://github.com/matevivan/running-coach/blob/main/.agents/skills/analyze-running-activity/scripts/fetch_historical_weather.py"
click node_fitparser "https://github.com/matevivan/running-coach/blob/main/.agents/skills/parse-fit-run/scripts/parse_fit_run.py"
click node_privatehistory "https://github.com/matevivan/running-coach/blob/main/.agents/running_data/migrations/001_initial.sql"

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_constitution,node_runner toneBlue
class node_initialize,node_collect,node_analyze,node_coach,node_parsefit,node_gear,node_fitparser toneAmber
class node_workspace,node_privatehistory,node_profile,node_plan,node_recovery toneMint
class node_garminsetup,node_dailyread,node_recoverysync,node_runsync,node_runlist,node_weatherfetch,node_garmin,node_weather toneRose
```

## Components

### Agent routing

- [Project instructions](https://github.com/matevivan/running-coach/blob/main/AGENTS.md): `AGENTS.md`

### Athlete workflows

- [Initialize workspace](https://github.com/matevivan/running-coach/blob/main/.agents/skills/initialize-running-project/SKILL.md): `.agents/skills/initialize-running-project/SKILL.md`
- [Collect daily metrics](https://github.com/matevivan/running-coach/blob/main/.agents/skills/collect-daily-metrics/SKILL.md): `.agents/skills/collect-daily-metrics/SKILL.md`
- [Analyze activity](https://github.com/matevivan/running-coach/blob/main/.agents/skills/analyze-running-activity/SKILL.md): `.agents/skills/analyze-running-activity/SKILL.md`
- [Coach runner](https://github.com/matevivan/running-coach/blob/main/.agents/skills/coach-runner/SKILL.md): `.agents/skills/coach-runner/SKILL.md`
- [Parse FIT run](https://github.com/matevivan/running-coach/blob/main/.agents/skills/parse-fit-run/SKILL.md): `.agents/skills/parse-fit-run/SKILL.md`
- [Research gear](https://github.com/matevivan/running-coach/blob/main/.agents/skills/research-running-gear/SKILL.md): `.agents/skills/research-running-gear/SKILL.md`
- [FIT file parser](https://github.com/matevivan/running-coach/blob/main/.agents/skills/parse-fit-run/scripts/parse_fit_run.py): `.agents/skills/parse-fit-run/scripts/parse_fit_run.py`

### Private data

- [Private workspace setup](https://github.com/matevivan/running-coach/blob/main/.agents/skills/initialize-running-project/scripts/initialize_private_workspace.py): `.agents/skills/initialize-running-project/scripts/initialize_private_workspace.py`
- [Private athlete history](https://github.com/matevivan/running-coach/blob/main/.agents/running_data/migrations/001_initial.sql): `.agents/running_data/migrations/001_initial.sql`
- **Runner profile**
- **Running plan**
- **Recovery projection**

### External data

- [GarminDB setup](https://github.com/matevivan/running-coach/blob/main/.agents/skills/initialize-running-project/scripts/setup_garmindb_config.py): `.agents/skills/initialize-running-project/scripts/setup_garmindb_config.py`
- [Read daily metrics](https://github.com/matevivan/running-coach/blob/main/.agents/skills/collect-daily-metrics/scripts/read_garmindb_daily.py): `.agents/skills/collect-daily-metrics/scripts/read_garmindb_daily.py`
- [Sync recovery data](https://github.com/matevivan/running-coach/blob/main/.agents/skills/collect-daily-metrics/scripts/sync_latest_garmindb_recovery.py): `.agents/skills/collect-daily-metrics/scripts/sync_latest_garmindb_recovery.py`
- [Sync recent runs](https://github.com/matevivan/running-coach/blob/main/.agents/skills/analyze-running-activity/scripts/sync_latest_garmindb.py): `.agents/skills/analyze-running-activity/scripts/sync_latest_garmindb.py`
- [List recent runs](https://github.com/matevivan/running-coach/blob/main/.agents/skills/analyze-running-activity/scripts/list_recent_garmindb_runs.py): `.agents/skills/analyze-running-activity/scripts/list_recent_garmindb_runs.py`
- [Fetch historical weather](https://github.com/matevivan/running-coach/blob/main/.agents/skills/analyze-running-activity/scripts/fetch_historical_weather.py): `.agents/skills/analyze-running-activity/scripts/fetch_historical_weather.py`
- **GarminDB**
- **Open-Meteo weather API**

### Other components

- **Runner / agent user**

## Connections

- Runner / agent user → Project instructions: starts task
- Project instructions → Initialize workspace: routes setup
- Project instructions → Collect daily metrics: routes collection
- Project instructions → Analyze activity: routes review
- Project instructions → Coach runner: routes coaching
- Project instructions → Research gear: routes research
- Analyze activity → Parse FIT run: uses parser
- Initialize workspace → Private workspace setup: creates workspace
- Initialize workspace → GarminDB setup: sets up GarminDB
- GarminDB setup → GarminDB: configures access
- Collect daily metrics → Read daily metrics: reads metrics
- Collect daily metrics → Sync recovery data: syncs recovery
- Read daily metrics → GarminDB: reads
- Sync recovery data → GarminDB: reads
- Collect daily metrics → Recovery projection: updates projection
- Analyze activity → Sync recent runs: syncs activities
- Analyze activity → List recent runs: lists activities
- Sync recent runs → GarminDB: reads
- List recent runs → GarminDB: reads
- Analyze activity → Fetch historical weather: requests weather
- Fetch historical weather → Open-Meteo weather API: queries history
- Analyze activity → Private athlete history: records reviewed run
- Initialize workspace → Private athlete history: projects evidence
- Coach runner → Private athlete history: maintains history
- Coach runner → Runner profile: updates profile
- Coach runner → Running plan: updates plan
- Initialize workspace → Runner profile: creates projection
- Initialize workspace → Running plan: creates projection
- Initialize workspace → Recovery projection: creates projection