# nst-guide/ndfd_historical architecture

> Architecture diagram of the GitHub repository nst-guide/ndfd_historical, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nst-guide/ndfd_historical
- Repository: https://github.com/nst-guide/ndfd_historical

## Overview

This repository builds historical NDFD weather summaries for selected CONUS geometry. The principal workflow is to turn input LineStrings into intersecting grid cells, import matching forecast data from NOAA bulk extracts, keep the latest forecast per cell and valid time, then aggregate values by cell and half-month alongside grid geometry. Grid projection constants support cell lookup; an optional elevation lookup uses the NWS API. The README describes the intended map-layer outcome, but the sampled summarizer stops after creating a merged in-memory result, so no exported map layer is shown.

Main entry points: [`code/get_grid.py`](https://github.com/nst-guide/ndfd_historical/blob/master/code/get_grid.py) (Grid Intersections), [`code/import.py`](https://github.com/nst-guide/ndfd_historical/blob/master/code/import.py) (Download and Import), [`code/summarize.py`](https://github.com/nst-guide/ndfd_historical/blob/master/code/summarize.py) (Half-Month Summaries), [`code/coalesce.py`](https://github.com/nst-guide/ndfd_historical/blob/master/code/coalesce.py) (Latest Forecast Selection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_selection["Geometry Selection"]
  node_get_grid["Grid Intersections<br/>[get_grid.py]"]
  node_grid_file["Selected Grid GeoJSON"]
end

subgraph group_ingest["Forecast Ingestion"]
  node_importer["Download and Import<br/>[import.py]"]
  node_raw_data["Raw Cell Forecasts"]
end

subgraph group_processing["Data Processing"]
  node_coalesce["Latest Forecast Selection<br/>[coalesce.py]"]
  node_coalesced_data["Coalesced Forecasts"]
  node_summarize["Half-Month Summaries<br/>[summarize.py]"]
  node_summary_result["Merged Summary Result"]
end

subgraph group_support["Grid Support"]
  node_constants["Projection Constants<br/>[constants.py]"]
end

node_user(("Geometry / Operator"))
node_noaa["NOAA Bulk Extracts"]
node_nws["NWS Elevation API"]

node_user -->|"provides geometry"| node_get_grid
node_get_grid -->|"uses projection"| node_constants
node_get_grid -->|"outputs cells"| node_grid_file
node_get_grid -.->|"optionally requests elevation"| node_nws
node_user -->|"provides extract IDs"| node_importer
node_importer -->|"lists and downloads"| node_noaa
node_grid_file -->|"selects cells"| node_importer
node_importer -->|"writes forecasts"| node_raw_data
node_raw_data -->|"reads forecasts"| node_coalesce
node_coalesce -->|"writes latest values"| node_coalesced_data
node_coalesced_data -->|"reads forecasts"| node_summarize
node_grid_file -->|"provides geometry"| node_summarize
node_summarize -->|"aggregates and merges"| node_summary_result

click node_get_grid "https://github.com/nst-guide/ndfd_historical/blob/master/code/get_grid.py"
click node_constants "https://github.com/nst-guide/ndfd_historical/blob/master/code/constants.py"
click node_importer "https://github.com/nst-guide/ndfd_historical/blob/master/code/import.py"
click node_coalesce "https://github.com/nst-guide/ndfd_historical/blob/master/code/coalesce.py"
click node_summarize "https://github.com/nst-guide/ndfd_historical/blob/master/code/summarize.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_get_grid,node_grid_file toneBlue
class node_importer,node_raw_data toneAmber
class node_coalesce,node_coalesced_data,node_summarize,node_summary_result,node_nws toneMint
class node_constants toneRose
class node_user,node_noaa toneIndigo
```

## Components

### Geometry Selection

- [Grid Intersections](https://github.com/nst-guide/ndfd_historical/blob/master/code/get_grid.py): `code/get_grid.py`
- **Selected Grid GeoJSON**

### Forecast Ingestion

- [Download and Import](https://github.com/nst-guide/ndfd_historical/blob/master/code/import.py): `code/import.py`
- **Raw Cell Forecasts**

### Data Processing

- [Latest Forecast Selection](https://github.com/nst-guide/ndfd_historical/blob/master/code/coalesce.py): `code/coalesce.py`
- **Coalesced Forecasts**
- [Half-Month Summaries](https://github.com/nst-guide/ndfd_historical/blob/master/code/summarize.py): `code/summarize.py`
- **Merged Summary Result**

### Grid Support

- [Projection Constants](https://github.com/nst-guide/ndfd_historical/blob/master/code/constants.py): `code/constants.py`

### Other components

- **Geometry / Operator**
- **NOAA Bulk Extracts**
- **NWS Elevation API**

## Connections

- Geometry / Operator → Grid Intersections: provides geometry
- Grid Intersections → Projection Constants: uses projection
- Grid Intersections → Selected Grid GeoJSON: outputs cells
- Grid Intersections → NWS Elevation API: optionally requests elevation
- Geometry / Operator → Download and Import: provides extract IDs
- Download and Import → NOAA Bulk Extracts: lists and downloads
- Selected Grid GeoJSON → Download and Import: selects cells
- Download and Import → Raw Cell Forecasts: writes forecasts
- Raw Cell Forecasts → Latest Forecast Selection: reads forecasts
- Latest Forecast Selection → Coalesced Forecasts: writes latest values
- Coalesced Forecasts → Half-Month Summaries: reads forecasts
- Selected Grid GeoJSON → Half-Month Summaries: provides geometry
- Half-Month Summaries → Merged Summary Result: aggregates and merges