70 lines
1.9 KiB
Markdown
70 lines
1.9 KiB
Markdown
# Weather Data Internals
|
|
|
|
This document describes the implemented weather data ingestion boundary.
|
|
|
|
## Purpose
|
|
|
|
`internal/adapters/weatherapi` fetches normalized weather data from one
|
|
configured weather API endpoint and assembles a `forecast.Bundle`.
|
|
|
|
## Inputs and Outputs
|
|
|
|
Input:
|
|
|
|
- `config.Config` with `weather_api.base_url`, `format`, `units`, `timezone`,
|
|
`precision`, timeout, and missing-source policy.
|
|
|
|
Output:
|
|
|
|
- `forecast.Bundle` containing observation, current conditions, hourly forecast,
|
|
narrative forecast, alerts, discussion, stub source slots, provenance, and
|
|
source warnings.
|
|
|
|
## Boundaries
|
|
|
|
- The adapter performs HTTP calls and decoding only.
|
|
- Forecast derivation, daypart grouping, report periods, report rendering, and
|
|
`scriptorium` execution are outside this boundary.
|
|
- Hourly forecast data is required. Other missing or malformed source sections
|
|
use the configured missing-source policy.
|
|
|
|
## External Adapter
|
|
|
|
The adapter calls:
|
|
|
|
- `/observations`
|
|
- `/conditions/current`
|
|
- `/forecast/hourly`
|
|
- `/forecast/narrative`
|
|
- `/alerts/active`
|
|
- `/discussion`
|
|
|
|
Forecast routes use the full-product endpoints, not day-slice endpoints.
|
|
|
|
## State
|
|
|
|
`app.FetchAndSaveBundle` can save an inspectable bundle JSON file using an
|
|
atomic rename. No report state, snapshots, or prompt input packages are written
|
|
yet.
|
|
|
|
## Failure Behavior
|
|
|
|
- HTTP and envelope decode failures return actionable errors with endpoint
|
|
context.
|
|
- Missing hourly data fails the fetch.
|
|
- Missing or malformed optional sources follow `error`, `warn`, or `none`.
|
|
- Source identity uses SHA-256 over compacted raw `data` JSON.
|
|
|
|
## Tests
|
|
|
|
Inspect:
|
|
|
|
- `internal/adapters/weatherapi/client_test.go`
|
|
- `internal/app/app_test.go`
|
|
|
|
## Invariants
|
|
|
|
- Weather facts come from normalized source data.
|
|
- External API details stay inside `internal/adapters/weatherapi`.
|
|
- Source provenance and warnings remain inspectable for later briefing builders.
|