# brieantruss/health_stats architecture

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

- Interactive diagram: https://gitdiagram.com/brieantruss/health_stats
- Repository: https://github.com/brieantruss/health_stats

## Overview

Health Stats is a personal health-data platform: it ingests wearable, GPS, and workout data, enriches and stores it, syncs it to BigQuery for analytics, and supports dashboards and coaching reports. The primary user workflow is logging an exercise or diet entry in the Streamlit app, sending it to the Flask API, and persisting it in MySQL for later warehouse and dashboard use. The repository also includes scheduled ingestion, health agents, and pipeline operations monitoring. Some subsystem links are documented in the README; unsampled implementation details are not assumed.

Main entry points: [`ops_dashboard/src/App.tsx`](https://github.com/brieantruss/health_stats/blob/main/ops_dashboard/src/App.tsx) (Operations dashboard), [`fitness_streamlit_app/common.py`](https://github.com/brieantruss/health_stats/blob/main/fitness_streamlit_app/common.py) (Workout and diet UI), [`scripts/etl`](https://github.com/brieantruss/health_stats/tree/main/scripts/etl) (Health ETL stages), [`scripts/agents`](https://github.com/brieantruss/health_stats/tree/main/scripts/agents) (Health coaching agents)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_logging["Health Logging"]
  node_tracker["Workout and diet UI<br/>[common.py]"]
  node_exercise_page["Exercise page<br/>[1_Exercise.py]"]
  node_diet_page["Diet page<br/>[2_Diet.py]"]
  node_fitness_api["Fitness API<br/>[api_app.py]"]
end

subgraph group_ingestion["Ingestion &amp; Storage"]
  node_mysql[("MySQL health store")]
  node_gps_app["GPS logger<br/>[app.py]"]
  node_prefect["Scheduled ingestion"]
  node_etl["Health ETL stages"]
  node_warehouse_sync["Warehouse sync"]
end

subgraph group_insights["Analytics &amp; Coaching"]
  node_bigquery[("BigQuery warehouse")]
  node_dataform["Dataform views"]
  node_agent_orchestrator["Agent scheduler"]
  node_health_agents["Health coaching agents"]
  node_drive_uploader["Report uploader<br/>[gdrive_uploader.py]"]
end

subgraph group_operations["Pipeline Operations"]
  node_ops_api["Pipeline API and events<br/>[api_app.py]"]
  node_event_stream["Event stream<br/>[event_stream.py]"]
  node_telemetry["Pipeline telemetry"]
  node_ops_ui["Operations dashboard<br/>[App.tsx]"]
  node_stream_hook["Telemetry stream client"]
  node_category_grid["Category telemetry grid<br/>[CategoryGrid.tsx]"]
  node_metrics["Metrics overview"]
  node_live_feed["Live event feed<br/>[LiveEventFeed.tsx]"]
  node_simulator["Event simulator"]
end

node_user(("Health data user"))
node_drive[("Google Drive and storage")]
node_weather["Weather and geocoding APIs"]
node_looker["Looker Studio dashboards"]

node_user -->|"logs activity"| node_tracker
node_tracker -->|"renders"| node_exercise_page
node_tracker -->|"renders"| node_diet_page
node_exercise_page -->|"sends exercise requests"| node_fitness_api
node_diet_page -->|"sends diet requests"| node_fitness_api
node_fitness_api -->|"writes records"| node_mysql
node_user -.->|"records location"| node_gps_app
node_drive -->|"provides raw files"| node_prefect
node_prefect -->|"schedules ingestion"| node_etl
node_etl -->|"loads health data"| node_mysql
node_etl -->|"enriches GPS data"| node_weather
node_mysql -->|"source tables"| node_warehouse_sync
node_warehouse_sync -->|"syncs tables"| node_bigquery
node_bigquery -->|"transforms warehouse data"| node_dataform
node_dataform -->|"feeds dashboards"| node_looker
node_agent_orchestrator -->|"runs agents"| node_health_agents
node_health_agents -->|"analyze health trends"| node_bigquery
node_health_agents -->|"uploads reports"| node_drive_uploader
node_drive_uploader -->|"stores reports"| node_drive
node_ops_ui -->|"uses stream client"| node_stream_hook
node_stream_hook -->|"fetches and publishes"| node_ops_api
node_ops_api -->|"reads and publishes events"| node_event_stream
node_ops_api -.->|"serves pipeline telemetry"| node_telemetry
node_ops_ui -->|"renders categories"| node_category_grid
node_ops_ui -->|"renders metrics"| node_metrics
node_ops_ui -->|"renders events"| node_live_feed
node_ops_ui -->|"offers event simulation"| node_simulator
node_simulator -->|"publishes events"| node_stream_hook

click node_tracker "https://github.com/brieantruss/health_stats/blob/main/fitness_streamlit_app/common.py"
click node_exercise_page "https://github.com/brieantruss/health_stats/blob/main/fitness_streamlit_app/pages/1_Exercise.py"
click node_diet_page "https://github.com/brieantruss/health_stats/blob/main/fitness_streamlit_app/pages/2_Diet.py"
click node_fitness_api "https://github.com/brieantruss/health_stats/blob/main/fitness_api/api_app.py"
click node_gps_app "https://github.com/brieantruss/health_stats/blob/main/gps_logger_app/app.py"
click node_prefect "https://github.com/brieantruss/health_stats/tree/main/scripts/dags"
click node_etl "https://github.com/brieantruss/health_stats/tree/main/scripts/etl"
click node_warehouse_sync "https://github.com/brieantruss/health_stats/blob/main/scripts/mysql_to_bigquery.py"
click node_agent_orchestrator "https://github.com/brieantruss/health_stats/blob/main/scripts/agents/orchestrate_agents.py"
click node_health_agents "https://github.com/brieantruss/health_stats/tree/main/scripts/agents"
click node_drive_uploader "https://github.com/brieantruss/health_stats/blob/main/scripts/agents/gdrive_uploader.py"
click node_ops_api "https://github.com/brieantruss/health_stats/blob/main/fitness_api/api_app.py"
click node_event_stream "https://github.com/brieantruss/health_stats/blob/main/scripts/event_stream.py"
click node_telemetry "https://github.com/brieantruss/health_stats/blob/main/scripts/pipeline_telemetry.py"
click node_ops_ui "https://github.com/brieantruss/health_stats/blob/main/ops_dashboard/src/App.tsx"
click node_stream_hook "https://github.com/brieantruss/health_stats/blob/main/ops_dashboard/src/hooks/usePipelineStream.ts"
click node_category_grid "https://github.com/brieantruss/health_stats/blob/main/ops_dashboard/src/components/CategoryGrid.tsx"
click node_metrics "https://github.com/brieantruss/health_stats/blob/main/ops_dashboard/src/components/MetricsOverview.tsx"
click node_live_feed "https://github.com/brieantruss/health_stats/blob/main/ops_dashboard/src/components/LiveEventFeed.tsx"
click node_simulator "https://github.com/brieantruss/health_stats/blob/main/ops_dashboard/src/components/DevEventSimulator.tsx"

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_tracker,node_exercise_page,node_diet_page,node_fitness_api,node_user toneBlue
class node_mysql,node_gps_app,node_prefect,node_etl,node_warehouse_sync,node_drive toneAmber
class node_bigquery,node_dataform,node_agent_orchestrator,node_health_agents,node_drive_uploader,node_weather toneMint
class node_ops_api,node_event_stream,node_telemetry,node_ops_ui,node_stream_hook,node_category_grid,node_metrics,node_live_feed,node_simulator toneRose
class node_looker toneIndigo
```

## Components

### Health Logging

- [Workout and diet UI](https://github.com/brieantruss/health_stats/blob/main/fitness_streamlit_app/common.py): `fitness_streamlit_app/common.py`
- [Exercise page](https://github.com/brieantruss/health_stats/blob/main/fitness_streamlit_app/pages/1_Exercise.py): `fitness_streamlit_app/pages/1_Exercise.py`
- [Diet page](https://github.com/brieantruss/health_stats/blob/main/fitness_streamlit_app/pages/2_Diet.py): `fitness_streamlit_app/pages/2_Diet.py`
- [Fitness API](https://github.com/brieantruss/health_stats/blob/main/fitness_api/api_app.py): `fitness_api/api_app.py`

### Ingestion & Storage

- **MySQL health store**
- [GPS logger](https://github.com/brieantruss/health_stats/blob/main/gps_logger_app/app.py): `gps_logger_app/app.py`
- [Scheduled ingestion](https://github.com/brieantruss/health_stats/tree/main/scripts/dags): `scripts/dags`
- [Health ETL stages](https://github.com/brieantruss/health_stats/tree/main/scripts/etl): `scripts/etl`
- [Warehouse sync](https://github.com/brieantruss/health_stats/blob/main/scripts/mysql_to_bigquery.py): `scripts/mysql_to_bigquery.py`

### Analytics & Coaching

- **BigQuery warehouse**
- **Dataform views**
- [Agent scheduler](https://github.com/brieantruss/health_stats/blob/main/scripts/agents/orchestrate_agents.py): `scripts/agents/orchestrate_agents.py`
- [Health coaching agents](https://github.com/brieantruss/health_stats/tree/main/scripts/agents): `scripts/agents`
- [Report uploader](https://github.com/brieantruss/health_stats/blob/main/scripts/agents/gdrive_uploader.py): `scripts/agents/gdrive_uploader.py`

### Pipeline Operations

- [Pipeline API and events](https://github.com/brieantruss/health_stats/blob/main/fitness_api/api_app.py): `fitness_api/api_app.py`
- [Event stream](https://github.com/brieantruss/health_stats/blob/main/scripts/event_stream.py): `scripts/event_stream.py`
- [Pipeline telemetry](https://github.com/brieantruss/health_stats/blob/main/scripts/pipeline_telemetry.py): `scripts/pipeline_telemetry.py`
- [Operations dashboard](https://github.com/brieantruss/health_stats/blob/main/ops_dashboard/src/App.tsx): `ops_dashboard/src/App.tsx`
- [Telemetry stream client](https://github.com/brieantruss/health_stats/blob/main/ops_dashboard/src/hooks/usePipelineStream.ts): `ops_dashboard/src/hooks/usePipelineStream.ts`
- [Category telemetry grid](https://github.com/brieantruss/health_stats/blob/main/ops_dashboard/src/components/CategoryGrid.tsx): `ops_dashboard/src/components/CategoryGrid.tsx`
- [Metrics overview](https://github.com/brieantruss/health_stats/blob/main/ops_dashboard/src/components/MetricsOverview.tsx): `ops_dashboard/src/components/MetricsOverview.tsx`
- [Live event feed](https://github.com/brieantruss/health_stats/blob/main/ops_dashboard/src/components/LiveEventFeed.tsx): `ops_dashboard/src/components/LiveEventFeed.tsx`
- [Event simulator](https://github.com/brieantruss/health_stats/blob/main/ops_dashboard/src/components/DevEventSimulator.tsx): `ops_dashboard/src/components/DevEventSimulator.tsx`

### Other components

- **Health data user**
- **Google Drive and storage**
- **Weather and geocoding APIs**
- **Looker Studio dashboards**

## Connections

- Health data user → Workout and diet UI: logs activity
- Workout and diet UI → Exercise page: renders (evidence: `fitness_streamlit_app/pages/1_Exercise.py`)
- Workout and diet UI → Diet page: renders (evidence: `fitness_streamlit_app/pages/2_Diet.py`)
- Exercise page → Fitness API: sends exercise requests
- Diet page → Fitness API: sends diet requests
- Fitness API → MySQL health store: writes records
- Health data user → GPS logger: records location
- Google Drive and storage → Scheduled ingestion: provides raw files
- Scheduled ingestion → Health ETL stages: schedules ingestion
- Health ETL stages → MySQL health store: loads health data
- Health ETL stages → Weather and geocoding APIs: enriches GPS data
- MySQL health store → Warehouse sync: source tables
- Warehouse sync → BigQuery warehouse: syncs tables
- BigQuery warehouse → Dataform views: transforms warehouse data
- Dataform views → Looker Studio dashboards: feeds dashboards
- Agent scheduler → Health coaching agents: runs agents (evidence: `scripts/agents/orchestrate_agents.py`)
- Health coaching agents → BigQuery warehouse: analyze health trends
- Health coaching agents → Report uploader: uploads reports (evidence: `scripts/agents/health_trend_analyst.py`)
- Report uploader → Google Drive and storage: stores reports
- Operations dashboard → Telemetry stream client: uses stream client (evidence: `ops_dashboard/src/App.tsx`)
- Telemetry stream client → Pipeline API and events: fetches and publishes (evidence: `ops_dashboard/src/hooks/usePipelineStream.ts`)
- Pipeline API and events → Event stream: reads and publishes events (evidence: `fitness_api/api_app.py`)
- Pipeline API and events → Pipeline telemetry: serves pipeline telemetry (evidence: `fitness_api/api_app.py`)
- Operations dashboard → Category telemetry grid: renders categories (evidence: `ops_dashboard/src/App.tsx`)
- Operations dashboard → Metrics overview: renders metrics (evidence: `ops_dashboard/src/App.tsx`)
- Operations dashboard → Live event feed: renders events (evidence: `ops_dashboard/src/App.tsx`)
- Operations dashboard → Event simulator: offers event simulation (evidence: `ops_dashboard/src/App.tsx`)
- Event simulator → Telemetry stream client: publishes events (evidence: `ops_dashboard/src/App.tsx`)