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 one configured Weather API endpoint 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, and source warnings
• stub source record for the daily forecast source slot
• 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. app.FetchAndSaveBundle can write bundle JSON atomically for inspection.

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 and stub sources follow missing-source policy.
• Explicit data: null from /alerts/active produces an empty, non-missing alert run.

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.