# 22bet10009-shuvam/aerosence architecture

> Architecture diagram of the GitHub repository 22bet10009-shuvam/aerosence, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/22bet10009-shuvam/aerosence
- Repository: https://github.com/22bet10009-shuvam/aerosence

## Overview

##### Project type and purpose
- This is a full-stack, single-page web application built with Flask (Python) on the backend and a lightweight JavaScript/CSS frontend.
- Purpose: Let users search any location, fetch current weather from Open-Meteo, and predict PM2.5 via a hybrid ML pipeline (RandomForest + ExtraTrees) or a heuristic fallback.

##### File structure
Top level
- app.py – Flask app defining HTTP endpoints, ties together weather API calls and ML inference.
- requirements.txt – lists Python dependencies (Flask, scikit-learn, joblib, requests, etc.).
- README.md, ABSOLUTE_DETAIL.txt – documentation.
Directories
- templates/index.html – single‐page app shell.
- static/app.js, static/style.css – client logic and dark UI styling.
- ml/
– train_hybrid.py: offline training script producing pm25_pipeline.pkl
– features.py, eval_cv.py: feature engineering and evaluation modules
– last_metrics.json: stored evaluation results
– (after training) pm25_pipeline.pkl: serialized pipeline (feature transformer + hybrid model)
- data/pm25_weather_kaggleish.csv – example dataset used by train_hybrid.py (synthetic by default).

##### README for additional insights
- Confirms no API keys required (Open-Meteo geocoding+forecast).
- Describes the fallback heuristic if the model is missing.
- Mentions offline training workflow separated from runtime inference.

a. Main components
1) Client (Browser SPA)
– index.html, app.js, style.css
2) Flask Backend
– HTTP endpoints: search → /geocode & /forecast to Open-Meteo, /predict → local ML
3) External Weather Service
– Open-Meteo Geocoding API
– Open-Meteo Forecast API
4) ML Inference
– pm25_pipeline.pkl loaded at startup
– feature engineering (ml/features.py)
– hybrid model (RandomForest + ExtraTrees with log1p transform)
– fallback heuristic logic
5) Offline Training (optional, separate flow)
– train_hybrid.py
– data/pm25_weather_kaggleish.csv or real dataset
– output: pm25_pipeline.pkl
b. Relationships and data flow
1) User enters location in UI → app.js sends AJAX to Flask /search endpoint.
2) Flask → calls Open-Meteo geocoding → returns lat/lon.
3) Flask → calls Open-Meteo weather → returns temperature, humidity, wind speed, etc.
4) Flask → passes weather features into pm25_pipeline (or heuristic) → PM2.5 prediction.
5) Flask → bundles weather + PM2.5 → JSON response back to client.
6) Client → renders results in UI.
7) Offline: Developer runs python ml/train_hybrid.py → trains new pipeline → serializes to .pkl.

c. Architectural patterns/design principles
- Separation of concerns:
– Presentation (SPA) vs. Business logic (Flask) vs. ML inference vs. Data training.
- API‐driven backend with clear REST endpoints.
- Modular ML pipeline (scikit-learn Pipeline, feature modules).
- Fallback to ensure uptime (heuristic rule when no model).

d. Key technologies/frameworks
- Backend: Python, Flask
- ML: scikit-learn (RandomForest, ExtraTrees), joblib/pickle for serialization
- Frontend: vanilla JavaScript (fetch API), CSS (animated skeleton loaders)
- External: Open-Meteo APIs

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    User["User"]:::external

    %% Frontend Layer
    subgraph "Frontend Layer"
        Browser["Browser SPA"]:::frontend
        HTML["index.html"]:::frontend
        JS["app.js"]:::frontend
        CSS["style.css"]:::frontend
    end

    %% Backend/API Layer
    subgraph "Backend/API Layer"
        Flask["Flask API Server\n(app.py)"]:::backend
    end

    %% External Services
    subgraph "External Services"
        GeoAPI["Open-Meteo Geocoding API"]:::external
        WeatherAPI["Open-Meteo Forecast API"]:::external
    end

    %% ML Components (Runtime)
    subgraph "ML Components (Runtime)"
        Features["Feature Engineering\n(ml/features.py)"]:::ml
        Pipeline["PM2.5 Pipeline\n(pm25_pipeline.pkl)"]:::ml
    end

    %% Fallback Heuristic
    subgraph "Fallback Heuristic"
        Heuristic["Fallback Logic\n(in app.py)"]:::ml
    end

    %% Offline Training Workflow
    subgraph "Offline Training Workflow"
        Train["train_hybrid.py"]:::ml
        Data["pm25_weather_kaggleish.csv"]:::ml
        Metrics["last_metrics.json"]:::ml
    end

    %% Miscellaneous
    subgraph "Miscellaneous"
        Req["requirements.txt"]:::misc
        README["README.md"]:::misc
        Detail["ABSOLUTE_DETAIL.txt"]:::misc
    end

    %% Runtime Data Flow
    User -->|uses UI| Browser
    Browser -->|"{location}"| Flask
    Flask -->|"{location}"| GeoAPI
    GeoAPI -->|"lat,lon"| Flask
    Flask -->|"{lat,lon}"| WeatherAPI
    WeatherAPI -->|"{weather features}"| Flask
    Flask -->|"raw features"| Features
    Features -->|"transformed features"| Pipeline
    Pipeline -->|"{PM2.5 prediction}"| Flask
    Flask -->|"JSON response"| Browser

    %% Fallback path
    Flask -->|model missing| Heuristic
    Heuristic -->|"{PM2.5 estimate}"| Flask

    %% Offline Training Flow
    Data -->|used by| Train
    Train -->|"produces model & metrics"| Pipeline
    Train -->|"writes"| Metrics

    %% Click Events
    click HTML "https://github.com/22bet10009-shuvam/aerosence/blob/main/templates/index.html"
    click JS "https://github.com/22bet10009-shuvam/aerosence/blob/main/static/app.js"
    click CSS "https://github.com/22bet10009-shuvam/aerosence/blob/main/static/style.css"
    click Flask "https://github.com/22bet10009-shuvam/aerosence/blob/main/app.py"
    click Features "https://github.com/22bet10009-shuvam/aerosence/blob/main/ml/features.py"
    click Pipeline "https://github.com/22bet10009-shuvam/aerosence/blob/main/ml/pm25_pipeline.pkl"
    click Train "https://github.com/22bet10009-shuvam/aerosence/blob/main/ml/train_hybrid.py"
    click Data "https://github.com/22bet10009-shuvam/aerosence/blob/main/data/pm25_weather_kaggleish.csv"
    click Metrics "https://github.com/22bet10009-shuvam/aerosence/blob/main/ml/last_metrics.json"
    click Req "https://github.com/22bet10009-shuvam/aerosence/blob/main/requirements.txt"
    click README "https://github.com/22bet10009-shuvam/aerosence/blob/main/README.md"
    click Detail "https://github.com/22bet10009-shuvam/aerosence/blob/main/ABSOLUTE_DETAIL.txt"

    %% Styles
    classDef frontend fill:#9f6,stroke:#333,stroke-width:1px;
    classDef backend fill:#6bf,stroke:#333,stroke-width:1px;
    classDef external fill:#fa0,stroke:#333,stroke-width:1px;
    classDef ml fill:#b3f,stroke:#333,stroke-width:1px;
    classDef misc fill:#ccc,stroke:#333,stroke-width:1px;
```
