# tcgoetz/garmindb architecture

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

- Interactive diagram: https://gitdiagram.com/tcgoetz/garmindb
- Repository: https://github.com/tcgoetz/garmindb

## Overview

GarminDB downloads and imports Garmin Connect health and activity data, stores it in databases, derives period summaries, and exposes analysis and visualization. README also documents retained source files, activity export, and Jupyter/command-line graphing; Fitbit and Microsoft Health data have separate import and analysis modules. The graph preserves these distinct stages and storage domains. Some subsystem links rely on README descriptions or SOURCE INDEX references; unsampled code is not treated as inspected, so uncertain runtime wiring is omitted.

Main entry points: [`scripts/garmindb_cli.py`](https://github.com/tcgoetz/garmindb/blob/master/scripts/garmindb_cli.py) (Command-line workflow), [`garmindb/download.py`](https://github.com/tcgoetz/garmindb/blob/master/garmindb/download.py) (Data download), [`garmindb/summarydb/summary_base.py`](https://github.com/tcgoetz/garmindb/blob/master/garmindb/summarydb/summary_base.py) (Period summaries), [`garmindb/garmin_connect_auth_adapter.py`](https://github.com/tcgoetz/garmindb/blob/master/garmindb/garmin_connect_auth_adapter.py) (Connect authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_acquisition["Garmin acquisition"]
  node_cli["Command-line workflow<br/>[garmindb_cli.py]"]
  node_config["Connect configuration"]
  node_auth["Connect authentication"]
  node_download["Data download<br/>[download.py]"]
end

subgraph group_processing["Parsing and import"]
  node_sourcefiles["Retained FIT and JSON"]
  node_fitparse["FIT parsing"]
  node_activityparse["Activity processing"]
  node_monitorimport["Monitoring import"]
  node_fitbit[("Fitbit import and analysis<br/>[fitbit_db.py]")]
  node_mshealth[("Microsoft Health import and analysis<br/>[mshealth_db.py]")]
  node_plugins["FIT plugins<br/>[plugin_manager.py]"]
end

subgraph group_storage["Health data stores"]
  node_activitydb[("Activity database<br/>[activities_db.py]")]
  node_monitoringdb[("Monitoring database<br/>[monitoring_db.py]")]
  node_garminsummary[("Garmin data database<br/>[garmin_db.py]")]
  node_summary[("Period summaries<br/>[summary_base.py]")]
end

subgraph group_analysis["Analysis and export"]
  node_analyze["Garmin analysis<br/>[analyze.py]"]
  node_visualize["Jupyter graphs<br/>[graphs.py]"]
  node_export["Activity export"]
end

node_user(("User"))
node_garmin["Garmin Connect"]

node_user -->|"runs workflow"| node_cli
node_cli -->|"downloads data"| node_download
node_cli -->|"imports monitoring"| node_monitorimport
node_cli -->|"analyzes data"| node_analyze
node_download -->|"uses authentication"| node_auth
node_auth -->|"reads credentials"| node_config
node_auth -->|"authenticates and requests"| node_garmin
node_download -->|"downloads data"| node_garmin
node_download -->|"retains downloaded files"| node_sourcefiles
node_activityparse -->|"delegates processing"| node_fitparse
node_activityparse -.->|"stores activity data"| node_activitydb
node_monitorimport -->|"uses FIT data"| node_fitparse
node_monitorimport -->|"imports monitoring records"| node_monitoringdb
node_analyze -->|"writes summaries"| node_summary
node_analyze -->|"reads Garmin data"| node_garminsummary
node_fitbit -->|"summarizes Fitbit data"| node_summary
node_mshealth -->|"summarizes health data"| node_summary
node_visualize -->|"graphs summaries"| node_summary
node_user -->|"views data"| node_visualize
node_user -->|"exports activities"| node_export
node_plugins -->|"initializes activity plugins"| node_activitydb

click node_cli "https://github.com/tcgoetz/garmindb/blob/master/scripts/garmindb_cli.py"
click node_config "https://github.com/tcgoetz/garmindb/blob/master/garmindb/garmin_connect_config_manager.py"
click node_auth "https://github.com/tcgoetz/garmindb/blob/master/garmindb/garmin_connect_auth_adapter.py"
click node_download "https://github.com/tcgoetz/garmindb/blob/master/garmindb/download.py"
click node_sourcefiles "https://github.com/tcgoetz/garmindb/blob/master/garmindb/garmin_json_data.py"
click node_fitparse "https://github.com/tcgoetz/garmindb/blob/master/garmindb/fit_file_processor.py"
click node_activityparse "https://github.com/tcgoetz/garmindb/blob/master/garmindb/activity_fit_file_processor.py"
click node_monitorimport "https://github.com/tcgoetz/garmindb/blob/master/garmindb/import_monitoring.py"
click node_activitydb "https://github.com/tcgoetz/garmindb/blob/master/garmindb/garmindb/activities_db.py"
click node_monitoringdb "https://github.com/tcgoetz/garmindb/blob/master/garmindb/garmindb/monitoring_db.py"
click node_garminsummary "https://github.com/tcgoetz/garmindb/blob/master/garmindb/garmindb/garmin_db.py"
click node_summary "https://github.com/tcgoetz/garmindb/blob/master/garmindb/summarydb/summary_base.py"
click node_analyze "https://github.com/tcgoetz/garmindb/blob/master/garmindb/analyze.py"
click node_fitbit "https://github.com/tcgoetz/garmindb/blob/master/garmindb/fitbitdb/fitbit_db.py"
click node_mshealth "https://github.com/tcgoetz/garmindb/blob/master/garmindb/mshealthdb/mshealth_db.py"
click node_visualize "https://github.com/tcgoetz/garmindb/blob/master/Jupyter/graphs.py"
click node_export "https://github.com/tcgoetz/garmindb/blob/master/garmindb/export_activities.py"
click node_plugins "https://github.com/tcgoetz/garmindb/blob/master/garmindb/plugin_manager.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_cli,node_config,node_auth,node_download,node_user toneBlue
class node_sourcefiles,node_fitparse,node_activityparse,node_monitorimport,node_fitbit,node_mshealth,node_plugins toneAmber
class node_activitydb,node_monitoringdb,node_garminsummary,node_summary toneMint
class node_analyze,node_visualize,node_export toneRose
class node_garmin toneIndigo
```

## Components

### Garmin acquisition

- [Command-line workflow](https://github.com/tcgoetz/garmindb/blob/master/scripts/garmindb_cli.py): `scripts/garmindb_cli.py`
- [Connect configuration](https://github.com/tcgoetz/garmindb/blob/master/garmindb/garmin_connect_config_manager.py): `garmindb/garmin_connect_config_manager.py`
- [Connect authentication](https://github.com/tcgoetz/garmindb/blob/master/garmindb/garmin_connect_auth_adapter.py): `garmindb/garmin_connect_auth_adapter.py`
- [Data download](https://github.com/tcgoetz/garmindb/blob/master/garmindb/download.py): `garmindb/download.py`

### Parsing and import

- [Retained FIT and JSON](https://github.com/tcgoetz/garmindb/blob/master/garmindb/garmin_json_data.py): `garmindb/garmin_json_data.py`
- [FIT parsing](https://github.com/tcgoetz/garmindb/blob/master/garmindb/fit_file_processor.py): `garmindb/fit_file_processor.py`
- [Activity processing](https://github.com/tcgoetz/garmindb/blob/master/garmindb/activity_fit_file_processor.py): `garmindb/activity_fit_file_processor.py`
- [Monitoring import](https://github.com/tcgoetz/garmindb/blob/master/garmindb/import_monitoring.py): `garmindb/import_monitoring.py`
- [Fitbit import and analysis](https://github.com/tcgoetz/garmindb/blob/master/garmindb/fitbitdb/fitbit_db.py): `garmindb/fitbitdb/fitbit_db.py`
- [Microsoft Health import and analysis](https://github.com/tcgoetz/garmindb/blob/master/garmindb/mshealthdb/mshealth_db.py): `garmindb/mshealthdb/mshealth_db.py`
- [FIT plugins](https://github.com/tcgoetz/garmindb/blob/master/garmindb/plugin_manager.py): `garmindb/plugin_manager.py`

### Health data stores

- [Activity database](https://github.com/tcgoetz/garmindb/blob/master/garmindb/garmindb/activities_db.py): `garmindb/garmindb/activities_db.py`
- [Monitoring database](https://github.com/tcgoetz/garmindb/blob/master/garmindb/garmindb/monitoring_db.py): `garmindb/garmindb/monitoring_db.py`
- [Garmin data database](https://github.com/tcgoetz/garmindb/blob/master/garmindb/garmindb/garmin_db.py): `garmindb/garmindb/garmin_db.py`
- [Period summaries](https://github.com/tcgoetz/garmindb/blob/master/garmindb/summarydb/summary_base.py): `garmindb/summarydb/summary_base.py`

### Analysis and export

- [Garmin analysis](https://github.com/tcgoetz/garmindb/blob/master/garmindb/analyze.py): `garmindb/analyze.py`
- [Jupyter graphs](https://github.com/tcgoetz/garmindb/blob/master/Jupyter/graphs.py): `Jupyter/graphs.py`
- [Activity export](https://github.com/tcgoetz/garmindb/blob/master/garmindb/export_activities.py): `garmindb/export_activities.py`

### Other components

- **User**
- **Garmin Connect**

## Connections

- User → Command-line workflow: runs workflow
- Command-line workflow → Data download: downloads data
- Command-line workflow → Monitoring import: imports monitoring
- Command-line workflow → Garmin analysis: analyzes data
- Data download → Connect authentication: uses authentication (evidence: `garmindb/download.py`)
- Connect authentication → Connect configuration: reads credentials (evidence: `garmindb/garmin_connect_auth_adapter.py`)
- Connect authentication → Garmin Connect: authenticates and requests (evidence: `garmindb/garmin_connect_auth_adapter.py`)
- Data download → Garmin Connect: downloads data
- Data download → Retained FIT and JSON: retains downloaded files
- Activity processing → FIT parsing: delegates processing (evidence: `garmindb/activity_fit_file_processor.py`)
- Activity processing → Activity database: stores activity data
- Monitoring import → FIT parsing: uses FIT data (evidence: `garmindb/import_monitoring.py`)
- Monitoring import → Monitoring database: imports monitoring records (evidence: `garmindb/import_monitoring.py`)
- Garmin analysis → Period summaries: writes summaries (evidence: `garmindb/analyze.py`)
- Garmin analysis → Garmin data database: reads Garmin data (evidence: `garmindb/analyze.py`)
- Fitbit import and analysis → Period summaries: summarizes Fitbit data
- Microsoft Health import and analysis → Period summaries: summarizes health data
- Jupyter graphs → Period summaries: graphs summaries (evidence: `Jupyter/graphs.py`)
- User → Jupyter graphs: views data
- User → Activity export: exports activities
- FIT plugins → Activity database: initializes activity plugins (evidence: `garmindb/plugin_manager.py`)
