# vahini-1/auratrack-ai architecture

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

- Interactive diagram: https://gitdiagram.com/vahini-1/auratrack-ai
- Repository: https://github.com/vahini-1/auratrack-ai

## Overview

AuraTrack AI accepts air-quality readings through a FastAPI service and returns six pollution-source fractions with a source-specific advisory. Its runtime supports PyTorch checkpoints and ONNX edge inference; a separate training path generates synthetic data, trains the model, and exports ONNX. IoT Hub telemetry is a separate ingestion capability, not shown feeding the API because that connection is not evidenced. Azure Maps, Stream Analytics, and SQL are documented integrations, but their runtime implementations are not present in the tree.

Main entry points: [`src/api/app.py`](https://github.com/vahini-1/auratrack-ai/blob/main/src/api/app.py) (FastAPI endpoints), [`src/models/training.py`](https://github.com/vahini-1/auratrack-ai/blob/main/src/models/training.py) (Model training), [`src/data_ingestion/iot_hub_client.py`](https://github.com/vahini-1/auratrack-ai/blob/main/src/data_ingestion/iot_hub_client.py) (IoT Hub client), [`src/inference/onnx_engine.py`](https://github.com/vahini-1/auratrack-ai/blob/main/src/inference/onnx_engine.py) (Predictor loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Sensor ingestion"]
  node_iot["IoT Hub client<br/>[iot_hub_client.py]"]
  node_reading["Reading schema<br/>[sensor_data.py]"]
end

subgraph group_service["Apportionment service"]
  node_api["FastAPI endpoints<br/>[app.py]"]
  node_result["Apportionment result<br/>[sensor_data.py]"]
  node_advisory["Actionable advisory<br/>[app.py]"]
end

subgraph group_modeling["Model lifecycle"]
  node_predictor["Predictor loader<br/>[onnx_engine.py]"]
  node_onnx["ONNX inference<br/>[onnx_engine.py]"]
  node_torchpredictor["PyTorch predictor"]
  node_mlp["Source MLP"]
  node_normalizer["Feature normalizer"]
  node_synthetic["Synthetic mixtures<br/>[training.py]"]
  node_training["Model training<br/>[training.py]"]
  node_export["ONNX export<br/>[training.py]"]
end

subgraph group_integrations["External integrations"]
  node_hub["Azure IoT Hub"]
  node_stream["Stream Analytics"]
  node_maps["Azure Maps"]
  node_sql[("Azure SQL")]
end

node_sensor(("Sensor network"))
node_citizens(("Citizens and agencies"))

node_sensor -->|"sends telemetry"| node_iot
node_iot -->|"serializes reading"| node_reading
node_iot -->|"publishes telemetry"| node_hub
node_sensor -->|"submits reading"| node_api
node_api -->|"accepts and features"| node_reading
node_api -->|"loads predictor"| node_predictor
node_predictor -->|"selects ONNX"| node_onnx
node_predictor -->|"selects PyTorch"| node_torchpredictor
node_torchpredictor -->|"normalizes features"| node_normalizer
node_torchpredictor -->|"runs prediction"| node_mlp
node_onnx -->|"normalizes features"| node_normalizer
node_api -->|"builds result"| node_result
node_api -->|"builds advisory"| node_advisory
node_api -->|"returns fractions and guidance"| node_citizens
node_synthetic -->|"provides training data"| node_training
node_training -->|"trains model"| node_mlp
node_training -->|"fits normalizer"| node_normalizer
node_training -->|"exports model"| node_export
node_export -.->|"enables edge inference"| node_onnx
node_api -.->|"optional upstream processing"| node_stream
node_api -.->|"visualizes fractions"| node_maps
node_sql -.->|"supports retraining data"| node_training

click node_iot "https://github.com/vahini-1/auratrack-ai/blob/main/src/data_ingestion/iot_hub_client.py"
click node_reading "https://github.com/vahini-1/auratrack-ai/blob/main/src/data_ingestion/sensor_data.py"
click node_api "https://github.com/vahini-1/auratrack-ai/blob/main/src/api/app.py"
click node_result "https://github.com/vahini-1/auratrack-ai/blob/main/src/data_ingestion/sensor_data.py"
click node_advisory "https://github.com/vahini-1/auratrack-ai/blob/main/src/api/app.py"
click node_predictor "https://github.com/vahini-1/auratrack-ai/blob/main/src/inference/onnx_engine.py"
click node_onnx "https://github.com/vahini-1/auratrack-ai/blob/main/src/inference/onnx_engine.py"
click node_torchpredictor "https://github.com/vahini-1/auratrack-ai/blob/main/src/models/source_apportionment.py"
click node_mlp "https://github.com/vahini-1/auratrack-ai/blob/main/src/models/source_apportionment.py"
click node_normalizer "https://github.com/vahini-1/auratrack-ai/blob/main/src/models/source_apportionment.py"
click node_synthetic "https://github.com/vahini-1/auratrack-ai/blob/main/src/models/training.py"
click node_training "https://github.com/vahini-1/auratrack-ai/blob/main/src/models/training.py"
click node_export "https://github.com/vahini-1/auratrack-ai/blob/main/src/models/training.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_iot,node_reading toneBlue
class node_api,node_result,node_advisory toneAmber
class node_predictor,node_onnx,node_torchpredictor,node_mlp,node_normalizer,node_synthetic,node_training,node_export toneMint
class node_hub,node_stream,node_maps,node_sql toneRose
class node_sensor,node_citizens toneIndigo
```

## Components

### Sensor ingestion

- [IoT Hub client](https://github.com/vahini-1/auratrack-ai/blob/main/src/data_ingestion/iot_hub_client.py): `src/data_ingestion/iot_hub_client.py`
- [Reading schema](https://github.com/vahini-1/auratrack-ai/blob/main/src/data_ingestion/sensor_data.py): `src/data_ingestion/sensor_data.py`

### Apportionment service

- [FastAPI endpoints](https://github.com/vahini-1/auratrack-ai/blob/main/src/api/app.py): `src/api/app.py`
- [Apportionment result](https://github.com/vahini-1/auratrack-ai/blob/main/src/data_ingestion/sensor_data.py): `src/data_ingestion/sensor_data.py`
- [Actionable advisory](https://github.com/vahini-1/auratrack-ai/blob/main/src/api/app.py): `src/api/app.py`

### Model lifecycle

- [Predictor loader](https://github.com/vahini-1/auratrack-ai/blob/main/src/inference/onnx_engine.py): `src/inference/onnx_engine.py`
- [ONNX inference](https://github.com/vahini-1/auratrack-ai/blob/main/src/inference/onnx_engine.py): `src/inference/onnx_engine.py`
- [PyTorch predictor](https://github.com/vahini-1/auratrack-ai/blob/main/src/models/source_apportionment.py): `src/models/source_apportionment.py`
- [Source MLP](https://github.com/vahini-1/auratrack-ai/blob/main/src/models/source_apportionment.py): `src/models/source_apportionment.py`
- [Feature normalizer](https://github.com/vahini-1/auratrack-ai/blob/main/src/models/source_apportionment.py): `src/models/source_apportionment.py`
- [Synthetic mixtures](https://github.com/vahini-1/auratrack-ai/blob/main/src/models/training.py): `src/models/training.py`
- [Model training](https://github.com/vahini-1/auratrack-ai/blob/main/src/models/training.py): `src/models/training.py`
- [ONNX export](https://github.com/vahini-1/auratrack-ai/blob/main/src/models/training.py): `src/models/training.py`

### External integrations

- **Azure IoT Hub**
- **Stream Analytics**
- **Azure Maps**
- **Azure SQL**

### Other components

- **Sensor network**
- **Citizens and agencies**

## Connections

- Sensor network → IoT Hub client: sends telemetry (evidence: `src/data_ingestion/iot_hub_client.py`)
- IoT Hub client → Reading schema: serializes reading (evidence: `src/data_ingestion/iot_hub_client.py`)
- IoT Hub client → Azure IoT Hub: publishes telemetry (evidence: `src/data_ingestion/iot_hub_client.py`)
- Sensor network → FastAPI endpoints: submits reading (evidence: `README.md`)
- FastAPI endpoints → Reading schema: accepts and features (evidence: `src/api/app.py`)
- FastAPI endpoints → Predictor loader: loads predictor (evidence: `src/api/app.py`)
- Predictor loader → ONNX inference: selects ONNX (evidence: `src/inference/onnx_engine.py`)
- Predictor loader → PyTorch predictor: selects PyTorch (evidence: `src/inference/onnx_engine.py`)
- PyTorch predictor → Feature normalizer: normalizes features (evidence: `src/models/source_apportionment.py`)
- PyTorch predictor → Source MLP: runs prediction (evidence: `src/models/source_apportionment.py`)
- ONNX inference → Feature normalizer: normalizes features (evidence: `src/inference/onnx_engine.py`)
- FastAPI endpoints → Apportionment result: builds result (evidence: `src/api/app.py`)
- FastAPI endpoints → Actionable advisory: builds advisory (evidence: `src/api/app.py`)
- FastAPI endpoints → Citizens and agencies: returns fractions and guidance (evidence: `README.md`)
- Synthetic mixtures → Model training: provides training data (evidence: `src/models/training.py`)
- Model training → Source MLP: trains model (evidence: `src/models/training.py`)
- Model training → Feature normalizer: fits normalizer (evidence: `src/models/training.py`)
- Model training → ONNX export: exports model (evidence: `src/models/training.py`)
- ONNX export → ONNX inference: enables edge inference (evidence: `README.md`)
- FastAPI endpoints → Stream Analytics: optional upstream processing (evidence: `README.md`)
- FastAPI endpoints → Azure Maps: visualizes fractions (evidence: `README.md`)
- Azure SQL → Model training: supports retraining data (evidence: `README.md`)
