# cosmoswems/aqact architecture

> Architecture diagram of the GitHub repository cosmoswems/aqact, 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/aqact
- Repository: https://github.com/cosmoswems/aqact

## Overview

AQACT is a local-first air-quality data workspace. Users upload sensor exports, clean and explore them, run scientific analyses, create plots, and export publication-ready figures. The Flask application coordinates local data and analysis; a separate browser-side assistant can use Puter.js with a deterministic local fallback. The graph preserves the documented analysis and mapping capabilities, but several are represented by their exact enclosing directories because their route implementations were not sampled.

Main entry points: [`app.py`](https://github.com/cosmoswems/aqact/blob/main/app.py) (Flask application), [`api/assistant_api.py`](https://github.com/cosmoswems/aqact/blob/main/api/assistant_api.py) (Local assistant API), [`static/js/assistant.js`](https://github.com/cosmoswems/aqact/blob/main/static/js/assistant.js) (Assistant interface), [`static/js/app.js`](https://github.com/cosmoswems/aqact/blob/main/static/js/app.js) (Workspace UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspace and API"]
  node_browser["Workspace UI<br/>[app.js]"]
  node_server["Flask application<br/>[app.py]"]
end

subgraph group_data["Data preparation"]
  node_io["File input<br/>[dataio.py]"]
  node_cleaners["Sensor cleaners"]
  node_sessions[("Session state<br/>[sessions.py]")]
end

subgraph group_science["Scientific analysis"]
  node_aqi["AQI analysis<br/>[aqi.py]"]
  node_compare["Station comparison<br/>[comparative.py]"]
  node_compliance["Compliance screening<br/>[compliance.py]"]
  node_extremes["Extreme values<br/>[extreme.py]"]
  node_ml["Machine learning"]
  node_evaluation["Model evaluation<br/>[model_eval.py]"]
end

subgraph group_publication["Plots and export"]
  node_plots["Plot generation<br/>[generators.py]"]
  node_exports["Figure export<br/>[export_api.py]"]
end

subgraph group_assistant["Assistant"]
  node_assistant_ui["Assistant interface<br/>[assistant.js]"]
  node_ai_transport["Puter transport<br/>[ai.js]"]
  node_model_router["Model routing<br/>[router.js]"]
  node_dataset_helper["Dataset assistant"]
  node_chart_helper["Chart interpretation"]
  node_fallback["Local AI fallback<br/>[fallback.js]"]
  node_assistant_api["Local assistant API<br/>[assistant_api.py]"]
  node_context["Compact context<br/>[context.py]"]
  node_profiling["Dataset profiling<br/>[profiling.py]"]
  node_insights["Deterministic insights<br/>[insights.py]"]
  node_offline_engine["Offline Q&amp;A<br/>[engine.py]"]
end

node_user(("Analyst"))
node_puter{{"Puter.js models"}}

node_user -->|"uses"| node_browser
node_browser -->|"sends workspace requests"| node_server
node_server -->|"handles file input"| node_io
node_server -->|"dispatches cleaning"| node_cleaners
node_server -->|"manages session state"| node_sessions
node_server -->|"routes analysis"| node_aqi
node_server -->|"routes analysis"| node_compare
node_server -->|"routes analysis"| node_compliance
node_server -->|"routes analysis"| node_extremes
node_server -->|"routes analysis"| node_ml
node_server -->|"routes analysis"| node_evaluation
node_server -->|"routes plotting"| node_plots
node_browser -->|"requests figure export"| node_exports
node_assistant_ui -->|"uses"| node_ai_transport
node_assistant_ui -->|"uses"| node_model_router
node_assistant_ui -->|"uses"| node_dataset_helper
node_assistant_ui -->|"uses"| node_chart_helper
node_ai_transport -->|"calls models"| node_puter
node_ai_transport -.->|"falls back"| node_fallback
node_dataset_helper -->|"requests local analysis"| node_assistant_api
node_chart_helper -->|"requests chart help"| node_assistant_api
node_assistant_api -->|"reads session"| node_sessions
node_assistant_api -->|"builds context"| node_context
node_assistant_api -->|"uses profile"| node_profiling
node_assistant_api -->|"answers locally"| node_offline_engine
node_offline_engine -->|"uses profile"| node_profiling
node_offline_engine -->|"uses insights"| node_insights

click node_browser "https://github.com/cosmoswems/aqact/blob/main/static/js/app.js"
click node_server "https://github.com/cosmoswems/aqact/blob/main/app.py"
click node_io "https://github.com/cosmoswems/aqact/blob/main/core/dataio.py"
click node_cleaners "https://github.com/cosmoswems/aqact/tree/main/cleaners"
click node_sessions "https://github.com/cosmoswems/aqact/blob/main/core/sessions.py"
click node_aqi "https://github.com/cosmoswems/aqact/blob/main/analysis/aqi.py"
click node_compare "https://github.com/cosmoswems/aqact/blob/main/analysis/comparative.py"
click node_compliance "https://github.com/cosmoswems/aqact/blob/main/analysis/compliance.py"
click node_extremes "https://github.com/cosmoswems/aqact/blob/main/analysis/extreme.py"
click node_ml "https://github.com/cosmoswems/aqact/blob/main/analysis/machine_learning.py"
click node_evaluation "https://github.com/cosmoswems/aqact/blob/main/analysis/model_eval.py"
click node_plots "https://github.com/cosmoswems/aqact/blob/main/plots/generators.py"
click node_exports "https://github.com/cosmoswems/aqact/blob/main/api/export_api.py"
click node_assistant_ui "https://github.com/cosmoswems/aqact/blob/main/static/js/assistant.js"
click node_ai_transport "https://github.com/cosmoswems/aqact/blob/main/static/js/services/ai.js"
click node_model_router "https://github.com/cosmoswems/aqact/blob/main/static/js/services/router.js"
click node_dataset_helper "https://github.com/cosmoswems/aqact/blob/main/static/js/services/datasetAssistant.js"
click node_chart_helper "https://github.com/cosmoswems/aqact/blob/main/static/js/services/chartInterpreter.js"
click node_fallback "https://github.com/cosmoswems/aqact/blob/main/static/js/services/fallback.js"
click node_assistant_api "https://github.com/cosmoswems/aqact/blob/main/api/assistant_api.py"
click node_context "https://github.com/cosmoswems/aqact/blob/main/assistant/context.py"
click node_profiling "https://github.com/cosmoswems/aqact/blob/main/assistant/profiling.py"
click node_insights "https://github.com/cosmoswems/aqact/blob/main/assistant/insights.py"
click node_offline_engine "https://github.com/cosmoswems/aqact/blob/main/assistant/engine.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_browser,node_server toneBlue
class node_io,node_cleaners,node_sessions toneAmber
class node_aqi,node_compare,node_compliance,node_extremes,node_ml,node_evaluation toneMint
class node_plots,node_exports toneRose
class node_assistant_ui,node_ai_transport,node_model_router,node_dataset_helper,node_chart_helper,node_fallback,node_assistant_api,node_context,node_profiling,node_insights,node_offline_engine,node_user,node_puter toneIndigo
```

## Components

### Workspace and API

- [Workspace UI](https://github.com/cosmoswems/aqact/blob/main/static/js/app.js): `static/js/app.js`
- [Flask application](https://github.com/cosmoswems/aqact/blob/main/app.py): `app.py`

### Data preparation

- [File input](https://github.com/cosmoswems/aqact/blob/main/core/dataio.py): `core/dataio.py`
- [Sensor cleaners](https://github.com/cosmoswems/aqact/tree/main/cleaners): `cleaners`
- [Session state](https://github.com/cosmoswems/aqact/blob/main/core/sessions.py): `core/sessions.py`

### Scientific analysis

- [AQI analysis](https://github.com/cosmoswems/aqact/blob/main/analysis/aqi.py): `analysis/aqi.py`
- [Station comparison](https://github.com/cosmoswems/aqact/blob/main/analysis/comparative.py): `analysis/comparative.py`
- [Compliance screening](https://github.com/cosmoswems/aqact/blob/main/analysis/compliance.py): `analysis/compliance.py`
- [Extreme values](https://github.com/cosmoswems/aqact/blob/main/analysis/extreme.py): `analysis/extreme.py`
- [Machine learning](https://github.com/cosmoswems/aqact/blob/main/analysis/machine_learning.py): `analysis/machine_learning.py`
- [Model evaluation](https://github.com/cosmoswems/aqact/blob/main/analysis/model_eval.py): `analysis/model_eval.py`

### Plots and export

- [Plot generation](https://github.com/cosmoswems/aqact/blob/main/plots/generators.py): `plots/generators.py`
- [Figure export](https://github.com/cosmoswems/aqact/blob/main/api/export_api.py): `api/export_api.py`

### Assistant

- [Assistant interface](https://github.com/cosmoswems/aqact/blob/main/static/js/assistant.js): `static/js/assistant.js`
- [Puter transport](https://github.com/cosmoswems/aqact/blob/main/static/js/services/ai.js): `static/js/services/ai.js`
- [Model routing](https://github.com/cosmoswems/aqact/blob/main/static/js/services/router.js): `static/js/services/router.js`
- [Dataset assistant](https://github.com/cosmoswems/aqact/blob/main/static/js/services/datasetAssistant.js): `static/js/services/datasetAssistant.js`
- [Chart interpretation](https://github.com/cosmoswems/aqact/blob/main/static/js/services/chartInterpreter.js): `static/js/services/chartInterpreter.js`
- [Local AI fallback](https://github.com/cosmoswems/aqact/blob/main/static/js/services/fallback.js): `static/js/services/fallback.js`
- [Local assistant API](https://github.com/cosmoswems/aqact/blob/main/api/assistant_api.py): `api/assistant_api.py`
- [Compact context](https://github.com/cosmoswems/aqact/blob/main/assistant/context.py): `assistant/context.py`
- [Dataset profiling](https://github.com/cosmoswems/aqact/blob/main/assistant/profiling.py): `assistant/profiling.py`
- [Deterministic insights](https://github.com/cosmoswems/aqact/blob/main/assistant/insights.py): `assistant/insights.py`
- [Offline Q&A](https://github.com/cosmoswems/aqact/blob/main/assistant/engine.py): `assistant/engine.py`

### Other components

- **Analyst**
- **Puter.js models**

## Connections

- Analyst → Workspace UI: uses
- Workspace UI → Flask application: sends workspace requests
- Flask application → File input: handles file input (evidence: `app.py`)
- Flask application → Sensor cleaners: dispatches cleaning (evidence: `app.py`)
- Flask application → Session state: manages session state (evidence: `app.py`)
- Flask application → AQI analysis: routes analysis (evidence: `app.py`)
- Flask application → Station comparison: routes analysis (evidence: `app.py`)
- Flask application → Compliance screening: routes analysis (evidence: `app.py`)
- Flask application → Extreme values: routes analysis (evidence: `app.py`)
- Flask application → Machine learning: routes analysis (evidence: `app.py`)
- Flask application → Model evaluation: routes analysis (evidence: `app.py`)
- Flask application → Plot generation: routes plotting (evidence: `app.py`)
- Workspace UI → Figure export: requests figure export
- Assistant interface → Puter transport: uses (evidence: `static/js/assistant.js`)
- Assistant interface → Model routing: uses (evidence: `static/js/assistant.js`)
- Assistant interface → Dataset assistant: uses (evidence: `static/js/assistant.js`)
- Assistant interface → Chart interpretation: uses (evidence: `static/js/assistant.js`)
- Puter transport → Puter.js models: calls models
- Puter transport → Local AI fallback: falls back
- Dataset assistant → Local assistant API: requests local analysis (evidence: `static/js/services/datasetAssistant.js`)
- Chart interpretation → Local assistant API: requests chart help (evidence: `static/js/services/chartInterpreter.js`)
- Local assistant API → Session state: reads session (evidence: `api/assistant_api.py`)
- Local assistant API → Compact context: builds context (evidence: `api/assistant_api.py`)
- Local assistant API → Dataset profiling: uses profile (evidence: `api/assistant_api.py`)
- Local assistant API → Offline Q&A: answers locally (evidence: `api/assistant_api.py`)
- Offline Q&A → Dataset profiling: uses profile (evidence: `assistant/engine.py`)
- Offline Q&A → Deterministic insights: uses insights (evidence: `assistant/engine.py`)
