# sharmilnk/from-air-to-care architecture

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

- Interactive diagram: https://gitdiagram.com/sharmilnk/from-air-to-care
- Repository: https://github.com/sharmilnk/from-air-to-care

## Overview

1. **Repository purpose**
   - This project predicts hospital admissions for respiratory distress from environmental signals such as air quality, weather, and seasonality.
   - Architecturally, it is split into a **data science pipeline** at the repo root and a **small Flask-style web app** under `NYC_Health_App_Light_Mode/`.

2. **Primary data sources and stored datasets**
   - The `data/` directory holds the persisted tabular inputs used by the pipeline:
     - `Air_Quality.csv`
     - `Asthama.csv`
     - `Respiratory.csv`
     - `nyc_weather_by_borough_2017-2024.csv`
   - These files form the local data boundary between external public datasets and the model-training code.

3. **Data ingestion / enrichment layer**
   - `fetch_weather.py` appears to handle retrieval of NYC weather data, likely building or updating the weather dataset from an external source.
   - The README indicates the broader source set includes OpenAQ, EPA, NOAA, and NYC DOHMH, so this repo is designed around **multi-source public-data ingestion** rather than a single internal database.

4. **Data preparation layer**
   - `prepare_data.py` is the main transformation step that likely joins environmental variables with health outcomes, creates lagged features, and produces analysis-ready tables.
   - This is the key feature-engineering boundary in the system: raw CSV inputs in `data/` become model-ready time-aligned records.

5. **Exploration and analysis**
   - `eda.py` is the exploratory analysis module, and `plots/` stores generated visual outputs.
   - This subsystem supports understanding relationships between pollution, weather, and admissions before training, but is separate from the serving app.

6. **Model training and evaluation**
   - `main.py` is the primary entry point for the modeling workflow.
   - The README says several regressors were evaluated: Gradient Boosting, Random Forest, Lasso, and Ridge, with Gradient Boosting selected as the best model.
   - This implies the training layer is a classical tabular ML pipeline rather than deep learning or a streaming system.

7. **Application/serving subsystem**
   - `NYC_Health_App_Light_Mode/app.py` is the application entry point for a user-facing interface.
   - `rebuild_models.py` suggests a separate utility for retraining or regenerating model artifacts without going through the full analysis pipeline manually.
   - This creates a clear boundary between **offline training** and **online prediction/UI**.

8. **Web UI structure**
   - The app uses a standard template/static layout:
     - `templates/index.html` for the page structure
     - `static/css/style.css` for styling
     - `static/js/script.js` for client-side behavior
   - This indicates a lightweight server-rendered interface rather than a SPA or API-only deployment.

9. **Runtime and dependencies**
   - `requirements.txt` defines a Python-based stack.
   - Based on the structure, the repo likely depends on common data-science libraries plus a lightweight web framework for the app layer.
   - There is no sign of containerization, orchestration, or external service infrastructure in the tree.

10. **End-to-end data flow**
   - External public datasets are collected or refreshed.
   - Data is cleaned and merged into analysis/model tables.
   - EDA and plotting validate assumptions and relationships.
   - `main.py` trains and evaluates regression models.
   - The selected model is then consumed by the app in `NYC_Health_App_Light_Mode/` for a user-facing forecast experience.
   - The main architectural split is therefore: **offline environmental-health forecasting pipeline** + **lightweight presentation layer**.

Main entry points: [`NYC_Health_App_Light_Mode/app.py`](https://github.com/sharmilnk/from-air-to-care/blob/main/NYC_Health_App_Light_Mode/app.py) (Flask app), [`main.py`](https://github.com/sharmilnk/from-air-to-care/blob/main/main.py) (Train model), [`prepare_data.py`](https://github.com/sharmilnk/from-air-to-care/blob/main/prepare_data.py) (Prepare data), [`NYC_Health_App_Light_Mode/requirements.txt`](https://github.com/sharmilnk/from-air-to-care/blob/main/NYC_Health_App_Light_Mode/requirements.txt) (Dependencies)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data boundary"]
  node_external_sources(("Public data<br/>public sources"))
  node_data_dir[("Data files<br/>csv store")]
end

subgraph group_core["Forecasting pipeline"]
  node_fetch_weather["Fetch weather<br/>ingestion<br/>[fetch_weather.py]"]
  node_prepare_data["Prepare data<br/>feature engineering<br/>[prepare_data.py]"]
  node_eda["EDA<br/>analysis<br/>[eda.py]"]
  node_plots_dir["Plots<br/>visual outputs"]
  node_main["Train model<br/>training pipeline<br/>[main.py]"]
  node_gb_model{{"Gradient boosting<br/>selected regressor"}}
end

subgraph group_app["Serving app"]
  node_requirements["Dependencies<br/>python stack<br/>[requirements.txt]"]
  node_app_py["Flask app<br/>web entrypoint<br/>[app.py]"]
  node_rebuild_models["Rebuild models<br/>ops utility<br/>[rebuild_models.py]"]
  node_template["Page template<br/>html view<br/>[index.html]"]
  node_style["Stylesheet<br/>css asset<br/>[style.css]"]
  node_script["Client script<br/>js asset<br/>[script.js]"]
end

node_external_sources -->|"feeds"| node_fetch_weather
node_fetch_weather -->|"stores"| node_data_dir
node_data_dir -->|"inputs"| node_prepare_data
node_prepare_data -->|"enables"| node_eda
node_eda -->|"writes"| node_plots_dir
node_prepare_data -->|"features"| node_main
node_main -->|"selects"| node_gb_model
node_gb_model -->|"served by"| node_app_py
node_requirements -->|"supports"| node_app_py
node_requirements -->|"supports"| node_main
node_app_py -->|"renders"| node_template
node_app_py -->|"uses"| node_style
node_app_py -->|"uses"| node_script
node_rebuild_models -.->|"reuses"| node_main

click node_data_dir "https://github.com/sharmilnk/from-air-to-care/tree/main/data"
click node_fetch_weather "https://github.com/sharmilnk/from-air-to-care/blob/main/fetch_weather.py"
click node_prepare_data "https://github.com/sharmilnk/from-air-to-care/blob/main/prepare_data.py"
click node_eda "https://github.com/sharmilnk/from-air-to-care/blob/main/eda.py"
click node_plots_dir "https://github.com/sharmilnk/from-air-to-care/tree/main/plots"
click node_main "https://github.com/sharmilnk/from-air-to-care/blob/main/main.py"
click node_requirements "https://github.com/sharmilnk/from-air-to-care/blob/main/NYC_Health_App_Light_Mode/requirements.txt"
click node_app_py "https://github.com/sharmilnk/from-air-to-care/blob/main/NYC_Health_App_Light_Mode/app.py"
click node_rebuild_models "https://github.com/sharmilnk/from-air-to-care/blob/main/NYC_Health_App_Light_Mode/rebuild_models.py"
click node_template "https://github.com/sharmilnk/from-air-to-care/blob/main/NYC_Health_App_Light_Mode/templates/index.html"
click node_style "https://github.com/sharmilnk/from-air-to-care/blob/main/NYC_Health_App_Light_Mode/static/css/style.css"
click node_script "https://github.com/sharmilnk/from-air-to-care/blob/main/NYC_Health_App_Light_Mode/static/js/script.js"

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_external_sources,node_data_dir toneBlue
class node_fetch_weather,node_prepare_data,node_eda,node_plots_dir,node_main,node_gb_model toneAmber
class node_requirements,node_app_py,node_rebuild_models,node_template,node_style,node_script toneMint
```

## Components

### Data boundary

Persisted inputs and intermediate files for the forecasting pipeline

- **Public data**: public sources · OpenAQ, EPA, NOAA, and NYC DOHMH inputs referenced by the project
- [Data files](https://github.com/sharmilnk/from-air-to-care/tree/main/data): csv store · Persisted air quality, respiratory, asthma, and weather tables · `data`

### Forecasting pipeline

Ingestion, preparation, analysis, and model training

- [Fetch weather](https://github.com/sharmilnk/from-air-to-care/blob/main/fetch_weather.py): ingestion · Retrieves or refreshes NYC weather data · `fetch_weather.py`
- [Prepare data](https://github.com/sharmilnk/from-air-to-care/blob/main/prepare_data.py): feature engineering · Joins signals, aligns time series, and builds model-ready tables · `prepare_data.py`
- [EDA](https://github.com/sharmilnk/from-air-to-care/blob/main/eda.py): analysis · Explores relationships among pollution, weather, and admissions · `eda.py`
- [Plots](https://github.com/sharmilnk/from-air-to-care/tree/main/plots): visual outputs · Generated charts and exploratory visuals · `plots`
- [Train model](https://github.com/sharmilnk/from-air-to-care/blob/main/main.py): training pipeline · Runs regression experiments and selects the best predictor · `main.py`
- **Gradient boosting**: selected regressor · Chosen tabular model for admissions prediction

### Serving app

Lightweight web UI and model rebuild entry points

- [Dependencies](https://github.com/sharmilnk/from-air-to-care/blob/main/NYC_Health_App_Light_Mode/requirements.txt): python stack · Library set used by the pipeline and app · `NYC_Health_App_Light_Mode/requirements.txt`
- [Flask app](https://github.com/sharmilnk/from-air-to-care/blob/main/NYC_Health_App_Light_Mode/app.py): web entrypoint · User-facing application entry point · `NYC_Health_App_Light_Mode/app.py`
- [Rebuild models](https://github.com/sharmilnk/from-air-to-care/blob/main/NYC_Health_App_Light_Mode/rebuild_models.py): ops utility · Utility for retraining or regenerating artifacts · `NYC_Health_App_Light_Mode/rebuild_models.py`
- [Page template](https://github.com/sharmilnk/from-air-to-care/blob/main/NYC_Health_App_Light_Mode/templates/index.html): html view · Server-rendered UI structure · `NYC_Health_App_Light_Mode/templates/index.html`
- [Stylesheet](https://github.com/sharmilnk/from-air-to-care/blob/main/NYC_Health_App_Light_Mode/static/css/style.css): css asset · Presentation styling for the web app · `NYC_Health_App_Light_Mode/static/css/style.css`
- [Client script](https://github.com/sharmilnk/from-air-to-care/blob/main/NYC_Health_App_Light_Mode/static/js/script.js): js asset · Browser-side behavior for the interface · `NYC_Health_App_Light_Mode/static/js/script.js`

## Connections

- Public data → Fetch weather: feeds · Public datasets are ingested or refreshed
- Fetch weather → Data files: stores · Weather data is persisted alongside other inputs
- Data files → Prepare data: inputs · Raw tables are combined into analysis-ready records
- Prepare data → EDA: enables · Prepared data supports exploration and validation
- EDA → Plots: writes · EDA produces charts and diagnostic visuals
- Prepare data → Train model: features · Model training consumes engineered tables
- Train model → Gradient boosting: selects · Gradient boosting is chosen as the best regressor
- Gradient boosting → Flask app: served by · Selected model powers the user-facing app
- Dependencies → Flask app: supports · Shared Python dependencies underpin the app runtime
- Dependencies → Train model: supports · Shared Python dependencies underpin training
- Flask app → Page template: renders · Server-side rendering uses the page template
- Flask app → Stylesheet: uses · The UI is styled by static CSS
- Flask app → Client script: uses · Client-side behavior is provided by JavaScript
- Rebuild models → Train model: reuses · Rebuild utility regenerates model artifacts through the training workflow
