# cosmoswems/api-data-retrieval-analysis-v2 architecture

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

- Interactive diagram: https://gitdiagram.com/cosmoswems/api-data-retrieval-analysis-v2
- Repository: https://github.com/cosmoswems/api-data-retrieval-analysis-v2

## Overview

This Shiny dashboard guides users from OpenAQ station discovery through measurement retrieval, analysis, and export, while also supporting direct CSV analysis and batch processing. Its UI and server provide the app boundary; helper modules cover API, data, plots, and batch operations. The README documents the major features and user workflow, but server.R and most helpers were not excerpted, so implementation-level wiring is not asserted beyond those documented relationships.

Main entry points: [`server.R`](https://github.com/cosmoswems/api-data-retrieval-analysis-v2/blob/main/server.R) (Reactive server), [`R/batch_helpers.R`](https://github.com/cosmoswems/api-data-retrieval-analysis-v2/blob/main/R/batch_helpers.R) (Stack and merge), [`ui.R`](https://github.com/cosmoswems/api-data-retrieval-analysis-v2/blob/main/ui.R) (Shiny interface), [`www/theme.js`](https://github.com/cosmoswems/api-data-retrieval-analysis-v2/blob/main/www/theme.js) (Theme toggle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Dashboard"]
  node_ui["Shiny interface<br/>[ui.R]"]
  node_server["Reactive server<br/>[server.R]"]
  node_session["Session reset<br/>[server.R]"]
  node_theme["Theme toggle<br/>[theme.js]"]
  node_styles["Theme styles<br/>[styles.css]"]
end

subgraph group_acquisition["OpenAQ Data"]
  node_openaq{{"OpenAQ API"}}
  node_discovery["Station discovery<br/>[api_helpers.R]"]
  node_fetch["Measurement retrieval<br/>[api_helpers.R]"]
  node_data["Data preparation<br/>[data_helpers.R]"]
end

subgraph group_analysis["Analysis"]
  node_analysis["Openair analysis<br/>[server.R]"]
  node_plot_helpers["Plot helpers<br/>[plot_helpers.R]"]
  node_upload["CSV analysis input<br/>[server.R]"]
end

subgraph group_batch["Batch and Export"]
  node_batch["Stack and merge<br/>[batch_helpers.R]"]
  node_batch_qc["Batch QC and plots<br/>[batch_helpers.R]"]
  node_export["Data and plot export<br/>[server.R]"]
  node_sample["Sample dataset"]
end

node_user(("Dashboard user"))

node_user -->|"uses"| node_ui
node_ui -->|"drives"| node_server
node_server -.->|"searches"| node_discovery
node_server -.->|"requests measurements"| node_fetch
node_discovery -.->|"queries"| node_openaq
node_fetch -.->|"retrieves data"| node_openaq
node_server -->|"runs plots"| node_analysis
node_upload -->|"supplies CSV"| node_analysis
node_analysis -.->|"uses"| node_plot_helpers
node_server -->|"dispatches processing"| node_batch
node_batch -->|"provides QC and plots"| node_batch_qc
node_batch -->|"sends assembled data"| node_analysis
node_server -->|"offers downloads"| node_export
node_server -->|"clears session data"| node_session
node_user -->|"changes theme"| node_theme
node_theme -.->|"applies classes"| node_styles
node_user -.->|"can upload"| node_sample

click node_ui "https://github.com/cosmoswems/api-data-retrieval-analysis-v2/blob/main/ui.R"
click node_server "https://github.com/cosmoswems/api-data-retrieval-analysis-v2/blob/main/server.R"
click node_session "https://github.com/cosmoswems/api-data-retrieval-analysis-v2/blob/main/server.R"
click node_theme "https://github.com/cosmoswems/api-data-retrieval-analysis-v2/blob/main/www/theme.js"
click node_styles "https://github.com/cosmoswems/api-data-retrieval-analysis-v2/blob/main/www/styles.css"
click node_discovery "https://github.com/cosmoswems/api-data-retrieval-analysis-v2/blob/main/R/api_helpers.R"
click node_fetch "https://github.com/cosmoswems/api-data-retrieval-analysis-v2/blob/main/R/api_helpers.R"
click node_data "https://github.com/cosmoswems/api-data-retrieval-analysis-v2/blob/main/R/data_helpers.R"
click node_analysis "https://github.com/cosmoswems/api-data-retrieval-analysis-v2/blob/main/server.R"
click node_plot_helpers "https://github.com/cosmoswems/api-data-retrieval-analysis-v2/blob/main/R/plot_helpers.R"
click node_upload "https://github.com/cosmoswems/api-data-retrieval-analysis-v2/blob/main/server.R"
click node_batch "https://github.com/cosmoswems/api-data-retrieval-analysis-v2/blob/main/R/batch_helpers.R"
click node_batch_qc "https://github.com/cosmoswems/api-data-retrieval-analysis-v2/blob/main/R/batch_helpers.R"
click node_export "https://github.com/cosmoswems/api-data-retrieval-analysis-v2/blob/main/server.R"
click node_sample "https://github.com/cosmoswems/api-data-retrieval-analysis-v2/blob/main/sample_data/sample_aq_met_data.csv"

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_ui,node_server,node_session,node_theme,node_styles,node_user toneBlue
class node_openaq,node_discovery,node_fetch,node_data toneAmber
class node_analysis,node_plot_helpers,node_upload toneMint
class node_batch,node_batch_qc,node_export,node_sample toneRose
```

## Components

### Dashboard

- [Shiny interface](https://github.com/cosmoswems/api-data-retrieval-analysis-v2/blob/main/ui.R): `ui.R`
- [Reactive server](https://github.com/cosmoswems/api-data-retrieval-analysis-v2/blob/main/server.R): `server.R`
- [Session reset](https://github.com/cosmoswems/api-data-retrieval-analysis-v2/blob/main/server.R): `server.R`
- [Theme toggle](https://github.com/cosmoswems/api-data-retrieval-analysis-v2/blob/main/www/theme.js): `www/theme.js`
- [Theme styles](https://github.com/cosmoswems/api-data-retrieval-analysis-v2/blob/main/www/styles.css): `www/styles.css`

### OpenAQ Data

- **OpenAQ API**
- [Station discovery](https://github.com/cosmoswems/api-data-retrieval-analysis-v2/blob/main/R/api_helpers.R): `R/api_helpers.R`
- [Measurement retrieval](https://github.com/cosmoswems/api-data-retrieval-analysis-v2/blob/main/R/api_helpers.R): `R/api_helpers.R`
- [Data preparation](https://github.com/cosmoswems/api-data-retrieval-analysis-v2/blob/main/R/data_helpers.R): `R/data_helpers.R`

### Analysis

- [Openair analysis](https://github.com/cosmoswems/api-data-retrieval-analysis-v2/blob/main/server.R): `server.R`
- [Plot helpers](https://github.com/cosmoswems/api-data-retrieval-analysis-v2/blob/main/R/plot_helpers.R): `R/plot_helpers.R`
- [CSV analysis input](https://github.com/cosmoswems/api-data-retrieval-analysis-v2/blob/main/server.R): `server.R`

### Batch and Export

- [Stack and merge](https://github.com/cosmoswems/api-data-retrieval-analysis-v2/blob/main/R/batch_helpers.R): `R/batch_helpers.R`
- [Batch QC and plots](https://github.com/cosmoswems/api-data-retrieval-analysis-v2/blob/main/R/batch_helpers.R): `R/batch_helpers.R`
- [Data and plot export](https://github.com/cosmoswems/api-data-retrieval-analysis-v2/blob/main/server.R): `server.R`
- [Sample dataset](https://github.com/cosmoswems/api-data-retrieval-analysis-v2/blob/main/sample_data/sample_aq_met_data.csv): `sample_data/sample_aq_met_data.csv`

### Other components

- **Dashboard user**

## Connections

- Dashboard user → Shiny interface: uses (evidence: `README.md`)
- Shiny interface → Reactive server: drives (evidence: `README.md`)
- Reactive server → Station discovery: searches
- Reactive server → Measurement retrieval: requests measurements
- Station discovery → OpenAQ API: queries
- Measurement retrieval → OpenAQ API: retrieves data
- Reactive server → Openair analysis: runs plots (evidence: `README.md`)
- CSV analysis input → Openair analysis: supplies CSV (evidence: `README.md`)
- Openair analysis → Plot helpers: uses
- Reactive server → Stack and merge: dispatches processing (evidence: `README.md`)
- Stack and merge → Batch QC and plots: provides QC and plots (evidence: `README.md`)
- Stack and merge → Openair analysis: sends assembled data (evidence: `README.md`)
- Reactive server → Data and plot export: offers downloads (evidence: `README.md`)
- Reactive server → Session reset: clears session data (evidence: `README.md`)
- Dashboard user → Theme toggle: changes theme (evidence: `README.md`)
- Theme toggle → Theme styles: applies classes
- Dashboard user → Sample dataset: can upload
