# waitasecant/air-pollution-dashboard architecture

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

- Interactive diagram: https://gitdiagram.com/waitasecant/air-pollution-dashboard
- Repository: https://github.com/waitasecant/air-pollution-dashboard

## Overview

##### Project Type and Purpose
- This is a data‐driven interactive dashboard built with R Shiny (“myApp/app.R”) that visualizes ambient air quality in Delhi. It incorporates Python scripts (“checkRealTime.py” and “realTimeDelhi.py”) to fetch and preprocess real‐time data, plus precomputed monthly‐average maps stored under “myApp/www/monthlyAvg.”

##### High-Level Architectural Components
a. External Data Sources
- Government or third-party air-quality APIs (e.g., CPCB feeds)
- Historical datasets (e.g., monthly station data)
b. Data Ingestion & Processing Layer (Python)
- checkRealTime.py – scheduled ETL for last-24h data
- realTimeDelhi.py – fetch current readings, update “realTimeDelhi.csv”
- DTAQI.pkl – pickled DataFrame of processed AQI values
c. Data Storage
- Raw/processed CSV files in “myApp/data” (“dailyDataAQI.csv”, “realTimeDelhi.csv”)
- Precomputed choropleth map tiles/images in “myApp/www/monthlyAvg”
d. Backend & Business Logic (R Shiny)
- app.R – loads CSV/PKL, computes time-series plots, renders choropleth
- Uses inverse-distance interpolation over a 10×10 km grid
e. Frontend UI & Static Assets
- myApp/www – static assets (CSS, JS, prebuilt maps/images)
- Shiny UI elements (leaflet maps, ggplot2 time series)
f. Deployment & CI/CD
- GitHub Actions (/.github/workflows/main.yml) for linting/tests or build triggers
- Deployment target: https://waitasecant.shinyapps.io/myapp

##### Interactions & Data Flow
2. Python ETL → “myApp/data” CSV/PKL storage
5. R Shiny → renders maps & plots → browser (end user)

##### Architectural Patterns & Principles
- Separation of concerns: Python handles data ingestion/processing; R Shiny handles visualization.
- “Files as database”: flat‐file storage for small/medium data (CSV, PKL).
- Precomputation of heavy map tiles to speed up serving.
- Use of CI/CD (GitHub Actions) to automate testing/deployment.

##### Detail Checklist
- Every directory with its role (data/, www/, workflows/)
- Which file holds which piece of functionality
- Both real‐time time series and choropleth generation paths

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Data Sources
    ExternalAPIs["Government/Third-party APIs"]:::external
    Historical["Historical Datasets"]:::external

    %% Data Ingestion & Processing Layer
    subgraph "Data Ingestion & Processing (Python ETL)"
        direction TB
        ETL1["checkRealTime.py"]:::etl
        ETL2["realTimeDelhi.py"]:::etl
        DTAQI["DTAQI.pkl"]:::storage
    end

    %% Flat-File Data Storage
    subgraph "Flat-File Storage (myApp/data)" 
        direction TB
        CSV1["dailyDataAQI.csv"]:::storage
        CSV2["realTimeDelhi.csv"]:::storage
    end

    %% Precomputed Map Assets
    subgraph "Precomputed Monthly-Average (myApp/www/monthlyAvg)"
        direction TB
        AQI["AQI"]:::storage
        NH3["NH3"]:::storage
        PM10["PM10"]:::storage
        PM25["PM2.5"]:::storage
        SO2["SO2"]:::storage
    end

    %% Backend & Business Logic
    subgraph "R Shiny Server"
        direction TB
        Shiny["app.R"]:::backend
    end

    %% Frontend UI
    Browser["User Browser"]:::frontend

    %% CI/CD
    CI["GitHub Actions"]:::cicd
    ShinyApps["Shinyapps.io"]:::external

    %% Data Flows
    ExternalAPIs -->|"API feeds"| ETL1
    ExternalAPIs -->|"API feeds"| ETL2
    Historical -->|"Historical CSV"| ETL1
    ETL1 -->|"realTimeDelhi.csv"| CSV2
    ETL2 -->|"realTimeDelhi.csv"| CSV2
    ETL1 -->|"dailyDataAQI.csv"| CSV1
    ETL1 -->|"DTAQI.pkl"| DTAQI
    ETL1 -->|"Map tiles/images"| AQI
    ETL1 -->|"Map tiles/images"| NH3
    ETL1 -->|"Map tiles/images"| PM10
    ETL1 -->|"Map tiles/images"| PM25
    ETL1 -->|"Map tiles/images"| SO2

    CSV1 -->|reads| Shiny
    CSV2 -->|reads| Shiny
    DTAQI -->|reads| Shiny
    AQI -->|serves| Shiny
    NH3 -->|serves| Shiny
    PM10 -->|serves| Shiny
    PM25 -->|serves| Shiny
    SO2 -->|serves| Shiny

    Shiny -->|"renders UI"| Browser

    %% CI/CD Flows
    CI -->|triggers ETL| ETL1
    CI -->|triggers ETL| ETL2
    CI -.->|deploy| ShinyApps
    ShinyApps -->|hosts| Browser

    %% Click Events
    click ETL1 "https://github.com/waitasecant/air-pollution-dashboard/blob/main/checkRealTime.py"
    click ETL2 "https://github.com/waitasecant/air-pollution-dashboard/blob/main/realTimeDelhi.py"
    click DTAQI "https://github.com/waitasecant/air-pollution-dashboard/blob/main/DTAQI.pkl"
    click CSV1 "https://github.com/waitasecant/air-pollution-dashboard/blob/main/myApp/data/dailyDataAQI.csv"
    click CSV2 "https://github.com/waitasecant/air-pollution-dashboard/blob/main/myApp/data/realTimeDelhi.csv"
    click AQI "https://github.com/waitasecant/air-pollution-dashboard/tree/main/myApp/www/monthlyAvg/AQI"
    click NH3 "https://github.com/waitasecant/air-pollution-dashboard/tree/main/myApp/www/monthlyAvg/NH3"
    click PM10 "https://github.com/waitasecant/air-pollution-dashboard/tree/main/myApp/www/monthlyAvg/PM10"
    click PM25 "https://github.com/waitasecant/air-pollution-dashboard/blob/main/myApp/www/monthlyAvg/PM2.5"
    click SO2 "https://github.com/waitasecant/air-pollution-dashboard/tree/main/myApp/www/monthlyAvg/SO2"
    click Shiny "https://github.com/waitasecant/air-pollution-dashboard/blob/main/myApp/app.R"
    click CI "https://github.com/waitasecant/air-pollution-dashboard/blob/main/.github/workflows/main.yml"
    
    %% Styles
    classDef external fill:#AED6F1,stroke:#1F618D,color:#1B2631;
    classDef etl fill:#ABEBC6,stroke:#1D8348,color:#145A32;
    classDef storage fill:#F5CBA7,stroke:#BA4A00,color:#641E16;
    classDef backend fill:#D2B4DE,stroke:#6C3483,color:#4A235A;
    classDef frontend fill:#FCF3CF,stroke:#7D6608,color:#4E342E;
    classDef cicd fill:#F9E79F,stroke:#B7950B,color:#7E5109;
```
