89 lines
2.8 KiB
Markdown
89 lines
2.8 KiB
Markdown
# 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
|
|
- 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](../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. 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 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.
|