# arkaaiml/heatiq architecture

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

- Interactive diagram: https://gitdiagram.com/arkaaiml/heatiq
- Repository: https://github.com/arkaaiml/heatiq

## Overview

HeatIQ is described as an early-warning and thermal-stress system, but the supplied tree and excerpts show an ML-focused weather-to-forecast pipeline rather than health-risk, vulnerability, or GIS implementations. The principal evidenced workflow prepares ERA5 weather features, forms chronological supervised data, trains and evaluates regression models, then builds a deployment artifact for validated single-row inference. The broader README capabilities are not represented by source modules in this tree. Relationships below follow shown imports, calls, and index references; unsampled behavior is not assumed.

Main entry points: [`ml/models/build_deployment_artifact.py`](https://github.com/arkaaiml/heatiq/blob/main/ml/models/build_deployment_artifact.py) (Deployment builder), [`ml/inference/artifact.py`](https://github.com/arkaaiml/heatiq/blob/main/ml/inference/artifact.py) (Artifact contract), [`ml/inference/predict.py`](https://github.com/arkaaiml/heatiq/blob/main/ml/inference/predict.py) (Single-row prediction), [`ml/models/evaluate.py`](https://github.com/arkaaiml/heatiq/blob/main/ml/models/evaluate.py) (Metrics evaluation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prep["Weather preparation"]
  node_clean["ERA5 cleaning<br/>[clean.py]"]
  node_features["Daily features<br/>[features.py]"]
  node_supervised["Targets and splits<br/>[supervised.py]"]
end

subgraph group_training["Training and evaluation"]
  node_baseline["Regression baselines<br/>[baseline.py]"]
  node_xgboost["XGBoost training<br/>[train_xgboost.py]"]
  node_evaluation["Metrics evaluation<br/>[evaluate.py]"]
  node_builder["Deployment builder"]
end

subgraph group_inference["Inference and artifacts"]
  node_artifact["Artifact contract<br/>[artifact.py]"]
  node_predict["Single-row prediction<br/>[predict.py]"]
  node_artifactfile["Model artifact file"]
end

node_operator(("ML operator"))
node_era5["ERA5 NetCDF"]
node_forecast["Temperature forecast"]

node_era5 -->|"loads and validates"| node_clean
node_clean -->|"provides weather data"| node_features
node_operator -->|"runs build"| node_builder
node_builder -->|"fits regressor"| node_baseline
node_builder -->|"evaluates predictions"| node_evaluation
node_builder -->|"saves artifact"| node_artifact
node_baseline -->|"computes metrics"| node_evaluation
node_xgboost -->|"computes metrics"| node_evaluation
node_artifact -->|"delegates prediction"| node_predict
node_artifact -->|"reads or writes"| node_artifactfile
node_predict -->|"returns prediction"| node_forecast
node_operator -.->|"runs training"| node_xgboost
node_operator -.->|"requests forecast"| node_predict

click node_clean "https://github.com/arkaaiml/heatiq/blob/main/ml/preprocessing/clean.py"
click node_features "https://github.com/arkaaiml/heatiq/blob/main/ml/preprocessing/features.py"
click node_supervised "https://github.com/arkaaiml/heatiq/blob/main/ml/preprocessing/supervised.py"
click node_baseline "https://github.com/arkaaiml/heatiq/blob/main/ml/models/baseline.py"
click node_xgboost "https://github.com/arkaaiml/heatiq/blob/main/ml/models/train_xgboost.py"
click node_evaluation "https://github.com/arkaaiml/heatiq/blob/main/ml/models/evaluate.py"
click node_builder "https://github.com/arkaaiml/heatiq/blob/main/ml/models/build_deployment_artifact.py"
click node_artifact "https://github.com/arkaaiml/heatiq/blob/main/ml/inference/artifact.py"
click node_predict "https://github.com/arkaaiml/heatiq/blob/main/ml/inference/predict.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_clean,node_features,node_supervised toneBlue
class node_baseline,node_xgboost,node_evaluation,node_builder toneAmber
class node_artifact,node_predict,node_artifactfile toneMint
class node_operator,node_era5,node_forecast toneIndigo
```

## Components

### Weather preparation

- [ERA5 cleaning](https://github.com/arkaaiml/heatiq/blob/main/ml/preprocessing/clean.py): `ml/preprocessing/clean.py`
- [Daily features](https://github.com/arkaaiml/heatiq/blob/main/ml/preprocessing/features.py): `ml/preprocessing/features.py`
- [Targets and splits](https://github.com/arkaaiml/heatiq/blob/main/ml/preprocessing/supervised.py): `ml/preprocessing/supervised.py`

### Training and evaluation

- [Regression baselines](https://github.com/arkaaiml/heatiq/blob/main/ml/models/baseline.py): `ml/models/baseline.py`
- [XGBoost training](https://github.com/arkaaiml/heatiq/blob/main/ml/models/train_xgboost.py): `ml/models/train_xgboost.py`
- [Metrics evaluation](https://github.com/arkaaiml/heatiq/blob/main/ml/models/evaluate.py): `ml/models/evaluate.py`
- [Deployment builder](https://github.com/arkaaiml/heatiq/blob/main/ml/models/build_deployment_artifact.py): `ml/models/build_deployment_artifact.py`

### Inference and artifacts

- [Artifact contract](https://github.com/arkaaiml/heatiq/blob/main/ml/inference/artifact.py): `ml/inference/artifact.py`
- [Single-row prediction](https://github.com/arkaaiml/heatiq/blob/main/ml/inference/predict.py): `ml/inference/predict.py`
- **Model artifact file**

### Other components

- **ML operator**
- **ERA5 NetCDF**
- **Temperature forecast**

## Connections

- ERA5 NetCDF → ERA5 cleaning: loads and validates (evidence: `ml/preprocessing/clean.py`)
- ERA5 cleaning → Daily features: provides weather data (evidence: `ml/preprocessing/features.py`)
- ML operator → Deployment builder: runs build (evidence: `ml/models/build_deployment_artifact.py`)
- Deployment builder → Regression baselines: fits regressor (evidence: `ml/models/build_deployment_artifact.py`)
- Deployment builder → Metrics evaluation: evaluates predictions (evidence: `ml/models/build_deployment_artifact.py`)
- Deployment builder → Artifact contract: saves artifact (evidence: `ml/models/build_deployment_artifact.py`)
- Regression baselines → Metrics evaluation: computes metrics (evidence: `ml/models/baseline.py`)
- XGBoost training → Metrics evaluation: computes metrics (evidence: `ml/models/train_xgboost.py`)
- Artifact contract → Single-row prediction: delegates prediction (evidence: `ml/inference/artifact.py`)
- Artifact contract → Model artifact file: reads or writes (evidence: `ml/inference/artifact.py`)
- Single-row prediction → Temperature forecast: returns prediction (evidence: `ml/inference/predict.py`)
- ML operator → XGBoost training: runs training
- ML operator → Single-row prediction: requests forecast
