# theeliad/geospatial-watches-and-warnings-app architecture

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

- Interactive diagram: https://gitdiagram.com/theeliad/geospatial-watches-and-warnings-app
- Repository: https://github.com/theeliad/geospatial-watches-and-warnings-app

## Overview

This is a Streamlit coastal flood-risk application. Users select a NOAA station, load historical water levels, train a station-specific LSTM, then request a live forecast combining the model’s next-hour estimate with NWS precipitation and station flood thresholds. The graph separates station discovery, historical-data handling, model training, and forecast/risk evaluation. Source excerpts show the central calls and storage behavior; the README documents the three-step workflow. Some UI and integration details are described in the README but are not fully visible in the sampled source.

Main entry points: [`main.py`](https://github.com/theeliad/geospatial-watches-and-warnings-app/blob/main/main.py) (Streamlit Workflow), [`predictor.py`](https://github.com/theeliad/geospatial-watches-and-warnings-app/blob/main/predictor.py) (Live Predictor), [`data_loader.py`](https://github.com/theeliad/geospatial-watches-and-warnings-app/blob/main/data_loader.py) (Historical Loader), [`model_trainer.py`](https://github.com/theeliad/geospatial-watches-and-warnings-app/blob/main/model_trainer.py) (LSTM Trainer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_station["Station Discovery"]
  node_app["Streamlit Workflow<br/>[main.py]"]
  node_registry["Station Metadata"]
  node_station_csv["Station Registry CSV"]
end

subgraph group_history["Historical Data"]
  node_historical_loader["Historical Loader<br/>[data_loader.py]"]
  node_noaa_fetcher["NOAA Water Fetcher<br/>[data_fetcher.py]"]
  node_historical_store[("Historical CSV Cache")]
end

subgraph group_training["Model Training"]
  node_trainer["LSTM Trainer<br/>[model_trainer.py]"]
  node_model_store[("Model and Scaler Files")]
end

subgraph group_forecast["Forecast and Risk"]
  node_predictor["Live Predictor<br/>[predictor.py]"]
  node_risk_logic["Flood Thresholds and Classification<br/>[data_fetcher.py]"]
  node_nws_forecast["Precipitation Forecast<br/>[nws_fetcher.py]"]
end

node_user(("User"))
node_noaa{{"NOAA CO-OPS API"}}
node_nws{{"National Weather Service API"}}

node_user -->|"selects and requests"| node_app
node_app -->|"loads stations"| node_registry
node_registry -->|"reads"| node_station_csv
node_app -->|"loads history"| node_historical_loader
node_historical_loader -->|"requests water levels"| node_noaa_fetcher
node_noaa_fetcher -->|"fetches observations"| node_noaa
node_historical_loader -->|"writes history"| node_historical_store
node_app -->|"starts training"| node_trainer
node_trainer -->|"reads training data"| node_historical_store
node_trainer -->|"saves model and scaler"| node_model_store
node_app -->|"requests forecast"| node_predictor
node_predictor -->|"loads recent cache"| node_historical_loader
node_predictor -->|"loads model and scaler"| node_model_store
node_predictor -->|"fetches precipitation"| node_nws_forecast
node_nws_forecast -->|"requests forecast data"| node_nws
node_predictor -->|"classifies predicted level"| node_risk_logic

click node_app "https://github.com/theeliad/geospatial-watches-and-warnings-app/blob/main/main.py"
click node_registry "https://github.com/theeliad/geospatial-watches-and-warnings-app/blob/main/stations_df_func.py"
click node_station_csv "https://github.com/theeliad/geospatial-watches-and-warnings-app/blob/main/all_noaa_coops_stations_with_states.csv"
click node_historical_loader "https://github.com/theeliad/geospatial-watches-and-warnings-app/blob/main/data_loader.py"
click node_noaa_fetcher "https://github.com/theeliad/geospatial-watches-and-warnings-app/blob/main/data_fetcher.py"
click node_trainer "https://github.com/theeliad/geospatial-watches-and-warnings-app/blob/main/model_trainer.py"
click node_predictor "https://github.com/theeliad/geospatial-watches-and-warnings-app/blob/main/predictor.py"
click node_risk_logic "https://github.com/theeliad/geospatial-watches-and-warnings-app/blob/main/data_fetcher.py"
click node_nws_forecast "https://github.com/theeliad/geospatial-watches-and-warnings-app/blob/main/nws_fetcher.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_app,node_registry,node_station_csv,node_user toneBlue
class node_historical_loader,node_noaa_fetcher,node_historical_store toneAmber
class node_trainer,node_model_store,node_noaa,node_nws toneMint
class node_predictor,node_risk_logic,node_nws_forecast toneRose
```

## Components

### Station Discovery

- [Streamlit Workflow](https://github.com/theeliad/geospatial-watches-and-warnings-app/blob/main/main.py): `main.py`
- [Station Metadata](https://github.com/theeliad/geospatial-watches-and-warnings-app/blob/main/stations_df_func.py): `stations_df_func.py`
- [Station Registry CSV](https://github.com/theeliad/geospatial-watches-and-warnings-app/blob/main/all_noaa_coops_stations_with_states.csv): `all_noaa_coops_stations_with_states.csv`

### Historical Data

- [Historical Loader](https://github.com/theeliad/geospatial-watches-and-warnings-app/blob/main/data_loader.py): `data_loader.py`
- [NOAA Water Fetcher](https://github.com/theeliad/geospatial-watches-and-warnings-app/blob/main/data_fetcher.py): `data_fetcher.py`
- **Historical CSV Cache**

### Model Training

- [LSTM Trainer](https://github.com/theeliad/geospatial-watches-and-warnings-app/blob/main/model_trainer.py): `model_trainer.py`
- **Model and Scaler Files**

### Forecast and Risk

- [Live Predictor](https://github.com/theeliad/geospatial-watches-and-warnings-app/blob/main/predictor.py): `predictor.py`
- [Flood Thresholds and Classification](https://github.com/theeliad/geospatial-watches-and-warnings-app/blob/main/data_fetcher.py): `data_fetcher.py`
- [Precipitation Forecast](https://github.com/theeliad/geospatial-watches-and-warnings-app/blob/main/nws_fetcher.py): `nws_fetcher.py`

### Other components

- **User**
- **NOAA CO-OPS API**
- **National Weather Service API**

## Connections

- User → Streamlit Workflow: selects and requests (evidence: `README.md`)
- Streamlit Workflow → Station Metadata: loads stations (evidence: `main.py`)
- Station Metadata → Station Registry CSV: reads (evidence: `stations_df_func.py`)
- Streamlit Workflow → Historical Loader: loads history (evidence: `README.md`)
- Historical Loader → NOAA Water Fetcher: requests water levels (evidence: `data_loader.py`)
- NOAA Water Fetcher → NOAA CO-OPS API: fetches observations (evidence: `data_fetcher.py`)
- Historical Loader → Historical CSV Cache: writes history (evidence: `data_loader.py`)
- Streamlit Workflow → LSTM Trainer: starts training (evidence: `README.md`)
- LSTM Trainer → Historical CSV Cache: reads training data (evidence: `model_trainer.py`)
- LSTM Trainer → Model and Scaler Files: saves model and scaler (evidence: `model_trainer.py`)
- Streamlit Workflow → Live Predictor: requests forecast (evidence: `main.py`)
- Live Predictor → Historical Loader: loads recent cache (evidence: `predictor.py`)
- Live Predictor → Model and Scaler Files: loads model and scaler (evidence: `predictor.py`)
- Live Predictor → Precipitation Forecast: fetches precipitation (evidence: `predictor.py`)
- Precipitation Forecast → National Weather Service API: requests forecast data (evidence: `nws_fetcher.py`)
- Live Predictor → Flood Thresholds and Classification: classifies predicted level (evidence: `predictor.py`)
