weatherreporter/docs/internal/weather-data.md

Weather Data Internals

This document describes Weather API ingestion into weatherdata.Bundle.

Purpose

internal/adapters/weatherapi fetches normalized weather data from the configured Weather API and assembles the bundle consumed by forecast derivation and module builders. Module builders expose normalized current conditions and weather story context when those sources are available.

Inputs And Outputs

Inputs:

• config.Config with Weather API URL, timeout, format, units, timezone, precision, and missing-source policy
• HTTP responses using the Weather API data envelope

Outputs:

• weatherdata.Bundle with observation, current conditions, hourly forecast, narrative forecast, active alerts, discussion, latest weather story, source records, source warnings, and typed SPC convective outlook data when that optional source is available
• optional saved bundle JSON through app fetch helpers

Boundaries

• The adapter owns HTTP calls, response-envelope handling, source hashing, and decoding into internal bundle types.
• It does not derive dayparts, resolve report periods, build module values, compare snapshots, write report state, or invoke Scriptorium.

Config Fields Used

• weather_api.base_url
• weather_api.timeout
• weather_api.format
• weather_api.units
• weather_api.timezone
• weather_api.precision
• missing_source.default
• missing_source.sources

External Adapters Used

• Weather API HTTP service

See Weather API integration for the external contract used by this project.

State Or Manifest Behavior

The adapter records source name, endpoint, query, fetch time, source timestamps when available, SHA-256 hash over compact raw data JSON, missing status, and source warnings. Successful data: null responses from /alerts/active represent a checked empty active-alert list, not a missing source. Successful non-null /outlooks/convective responses with empty outlook and discussion arrays represent checked empty outlook data. app.FetchAndSaveBundle can write bundle JSON atomically for inspection.

SPC convective outlook data is stored on weatherdata.Bundle.SPCConvectiveOutlooks. The collected run keeps upstream run metadata, location identifiers, ordered outlook records, discussion records, and each outlook's raw GeoJSON geometry. Source provenance for this payload uses the spc_convective_outlooks source name, endpoint /outlooks/convective, the query sent by the adapter, timestamps, and a hash of the raw data object.

Skip And Resume Behavior

No resume behavior. Optional missing or malformed sources may be omitted, warned, or treated as errors according to missing-source policy. Hourly forecast data is required and cannot be skipped.

Failure Behavior

• Missing or invalid weather_api.base_url prevents client construction.
• HTTP errors, response read failures, and envelope decode failures include endpoint context.
• Missing hourly data or hourly forecasts with no periods fail bundle fetch.
• Optional sources follow missing-source policy.
• Explicit data: null from /alerts/active produces an empty, non-missing alert run.
• Explicit data: null from /outlooks/convective follows optional missing-source policy.

Tests

Inspect:

• internal/adapters/weatherapi/client_test.go
• internal/app/app_test.go

Invariants

• Weather facts come from normalized source data.
• Full hourly and narrative products are fetched; Go owns report-period selection.
• Source provenance and warnings remain inspectable downstream.