# Weather Data Internals

This document describes Weather API ingestion into `forecast.Bundle`.

## Purpose

`internal/adapters/weatherapi` fetches normalized weather data from one
configured Weather API endpoint and assembles the bundle consumed by forecast
derivation and briefing builders.

## 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:

- `forecast.Bundle` with observation, current conditions, hourly forecast,
  narrative forecast, active alerts, discussion, source records, and source
  warnings
- stub source records for daily forecast and weather story source slots
- 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 briefings, 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](../integrations/weatherapi.md) 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. `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.

## 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.