Add integration and development documentation
This commit is contained in:
138
docs/integrations/feedapi.md
Normal file
138
docs/integrations/feedapi.md
Normal file
@@ -0,0 +1,138 @@
|
||||
# Feedapi Runtime Contract
|
||||
|
||||
`weatherapi` uses feedapi as its generic HTTP runtime and configuration layer.
|
||||
This document describes the feedapi behavior that `weatherapi` relies on.
|
||||
|
||||
## Version
|
||||
|
||||
`go.mod` depends on:
|
||||
|
||||
- `gitea.maximumdirect.net/ejr/feedapi v0.1.0`
|
||||
|
||||
Only feedapi behavior used by `weatherapi` is documented here.
|
||||
|
||||
## Packages Used
|
||||
|
||||
Runtime composition imports:
|
||||
|
||||
- `feedapi/app`
|
||||
- `feedapi/config`
|
||||
- `feedapi/db`
|
||||
|
||||
The HTTP adapter imports:
|
||||
|
||||
- `feedapi/bind`
|
||||
- `feedapi/endpoint`
|
||||
- `feedapi/errors`
|
||||
- `feedapi/render`
|
||||
- `feedapi/response`
|
||||
|
||||
Tests also use:
|
||||
|
||||
- `feedapi/templates`
|
||||
- `feedapi/transport/httpx`
|
||||
|
||||
## Config Ownership
|
||||
|
||||
Feedapi owns loading and validating the YAML config used by `weatherapi`.
|
||||
`weatherapi` adds one local runtime check: `databases` must contain at least
|
||||
one entry.
|
||||
|
||||
The implemented config areas used by `weatherapi` are:
|
||||
|
||||
- `server`: HTTP listen/default format/timeouts;
|
||||
- `databases`: named database handles opened into a registry;
|
||||
- `templates`: base directory for text templates.
|
||||
|
||||
The canonical config reference is [`docs/config.md`](../config.md).
|
||||
|
||||
## Database Registry
|
||||
|
||||
`cmd/weatherapi` calls feedapi `db.OpenAll` with configured databases and passes
|
||||
the resulting registry into `feedapi/app.New`. It also selects the first
|
||||
configured database name from the registry as the primary weather store.
|
||||
|
||||
Feedapi owns opening and closing database handles. `weatherapi` owns choosing
|
||||
which opened handle is used by the Postgres repository.
|
||||
|
||||
## Endpoint Registry
|
||||
|
||||
`weatherapi` builds endpoint definitions with `httpapi.Definitions` and passes
|
||||
them to feedapi through `feedapi/app.WithEndpoints`.
|
||||
|
||||
Feedapi owns:
|
||||
|
||||
- route adaptation;
|
||||
- HTTP method/path matching;
|
||||
- invoking endpoint binders;
|
||||
- invoking endpoint handlers;
|
||||
- rendering handler results.
|
||||
|
||||
Endpoint definitions remain owned by `internal/adapters/inbound/httpapi`.
|
||||
|
||||
## Renderers and Templates
|
||||
|
||||
Each implemented endpoint declares JSON, XML, and text output through feedapi
|
||||
render formats. Text endpoints also name a template file.
|
||||
|
||||
Feedapi owns:
|
||||
|
||||
- renderer registration;
|
||||
- format negotiation;
|
||||
- template loading from `templates.base_dir`;
|
||||
- applying templates to response envelopes.
|
||||
|
||||
`weatherapi` owns the template files under `templates/` and presenter output
|
||||
shapes consumed by those templates.
|
||||
|
||||
## Content Negotiation
|
||||
|
||||
`weatherapi` relies on feedapi's negotiation order:
|
||||
|
||||
1. `format` query parameter;
|
||||
2. `Accept` header;
|
||||
3. configured default format.
|
||||
|
||||
Unsupported formats are exposed as structured API errors. See
|
||||
[`docs/api.md`](../api.md) for the public HTTP contract.
|
||||
|
||||
## Success and Error Envelopes
|
||||
|
||||
Endpoint handlers return `response.Envelope{Data: ...}` for successful
|
||||
responses. Nil data is rendered as `data: null`.
|
||||
|
||||
Feedapi error handling exposes structured error envelopes with:
|
||||
|
||||
- `error.code`;
|
||||
- `error.message`.
|
||||
|
||||
`weatherapi` relies on feedapi invalid-parameter and unsupported-format errors
|
||||
for request validation and negotiation failures.
|
||||
|
||||
## Middleware and Shutdown
|
||||
|
||||
Feedapi owns generic HTTP middleware and server lifecycle. The architecture
|
||||
policy records that recovery, request ID, and timing middleware are installed by
|
||||
default.
|
||||
|
||||
`weatherapi` supplies a signal-cancelable context to feedapi startup. Feedapi
|
||||
owns graceful HTTP shutdown after that context is canceled.
|
||||
|
||||
## Upgrade Checklist
|
||||
|
||||
Before upgrading feedapi:
|
||||
|
||||
- verify config field names and defaults still match [`docs/config.md`](../config.md);
|
||||
- verify database registry behavior still supports first configured database
|
||||
selection;
|
||||
- verify endpoint definition APIs still support binders, handlers, formats,
|
||||
and template names;
|
||||
- verify negotiation order remains `format`, then `Accept`, then default;
|
||||
- verify success and error envelopes still match [`docs/api.md`](../api.md);
|
||||
- run `go test ./...` with private module access configured.
|
||||
|
||||
## Related Docs
|
||||
|
||||
- [`docs/internal/runtime.md`](../internal/runtime.md)
|
||||
- [`docs/internal/http-adapter.md`](../internal/http-adapter.md)
|
||||
- [`docs/api.md`](../api.md)
|
||||
175
docs/integrations/weatherfeeder-postgres.md
Normal file
175
docs/integrations/weatherfeeder-postgres.md
Normal file
@@ -0,0 +1,175 @@
|
||||
# Weatherfeeder Postgres Contract
|
||||
|
||||
`weatherapi` reads weather data from Postgres tables owned and populated by
|
||||
`weatherfeeder`. This document describes only the storage contract consumed by
|
||||
`weatherapi`; it is not a full weatherfeeder schema reference.
|
||||
|
||||
## Version
|
||||
|
||||
`go.mod` depends on:
|
||||
|
||||
- `gitea.maximumdirect.net/ejr/weatherfeeder v0.10.0`
|
||||
|
||||
The repository code also depends on weatherfeeder canonical model types. Table
|
||||
compatibility must match the SQL in `internal/adapters/outbound/postgres`.
|
||||
|
||||
## Boundary
|
||||
|
||||
`weatherapi` is read-only:
|
||||
|
||||
- it does not create tables;
|
||||
- it does not migrate tables;
|
||||
- it does not ingest provider data;
|
||||
- it does not write weatherfeeder events.
|
||||
|
||||
Weatherfeeder owns provider polling, normalization, table shape, and writes.
|
||||
Postgres owns persistence, backup, restore, and availability.
|
||||
|
||||
## Table Families Read
|
||||
|
||||
| Resource | Tables read |
|
||||
| --- | --- |
|
||||
| Latest observation | `observations`, `observation_present_weather` |
|
||||
| Current conditions | `observations` |
|
||||
| Active alerts | `alert_runs`, `alerts`, `alert_references` |
|
||||
| Hourly forecast | `forecasts`, `forecast_periods` |
|
||||
| Narrative forecast | `forecasts`, `forecast_periods` |
|
||||
| Forecast discussion | `forecast_discussions`, `forecast_discussion_key_messages` |
|
||||
| Weather story run | `weather_story_runs`, `weather_stories` |
|
||||
| Latest weather story | `weather_stories` |
|
||||
|
||||
## Latest Row Selection
|
||||
|
||||
Latest parent resources use these ordering rules:
|
||||
|
||||
- observations: `observed_at DESC, event_emitted_at DESC`;
|
||||
- alert runs: `as_of DESC, event_emitted_at DESC`;
|
||||
- hourly forecasts: `product = 'hourly'`, then `issued_at DESC,
|
||||
event_emitted_at DESC`;
|
||||
- narrative forecasts: `product = 'narrative'`, then `issued_at DESC,
|
||||
event_emitted_at DESC`;
|
||||
- forecast discussions: `issued_at DESC, event_emitted_at DESC`;
|
||||
- weather story runs: `as_of DESC, event_emitted_at DESC`;
|
||||
- latest individual weather story: `updated_at DESC, as_of DESC,
|
||||
story_order ASC, story_index ASC`.
|
||||
|
||||
Current conditions aggregate `observations` rows where `observed_at` is inside
|
||||
the application-provided observation window.
|
||||
|
||||
## Child Ordering
|
||||
|
||||
Child rows are loaded separately and attached in stored order:
|
||||
|
||||
- observation present weather: `weather_index ASC`;
|
||||
- alerts: `alert_index ASC`;
|
||||
- alert references: `alert_index ASC, reference_index ASC`;
|
||||
- forecast periods: `period_index ASC`;
|
||||
- forecast discussion key messages: `message_index ASC`;
|
||||
- weather stories for a run: `story_index ASC`.
|
||||
|
||||
## Columns Read
|
||||
|
||||
The repository reads only these columns.
|
||||
|
||||
### `observations`
|
||||
|
||||
`event_id`, `station_id`, `station_name`, `observed_at`, `condition_code`,
|
||||
`is_day`, `text_description`, `temperature_c`, `dewpoint_c`,
|
||||
`wind_direction_degrees`, `wind_speed_kmh`, `wind_gust_kmh`,
|
||||
`barometric_pressure_pa`, `visibility_meters`, `relative_humidity_percent`,
|
||||
`apparent_temperature_c`, and `event_emitted_at`.
|
||||
|
||||
Current conditions additionally aggregate recent `observations` values for
|
||||
temperature, apparent temperature, dewpoint, humidity, wind speed, wind
|
||||
direction, condition code, and latest `is_day`.
|
||||
|
||||
### `observation_present_weather`
|
||||
|
||||
`weather_index`, `raw_text`, and `event_id`.
|
||||
|
||||
`raw_text` is decoded as JSON when present. Empty or null raw text maps to an
|
||||
empty present-weather value; invalid JSON is returned as a repository error.
|
||||
|
||||
### `alert_runs`
|
||||
|
||||
`event_id`, `location_id`, `location_name`, `as_of`, `latitude`, `longitude`,
|
||||
and `event_emitted_at`.
|
||||
|
||||
### `alerts`
|
||||
|
||||
`alert_index`, `alert_id`, `event`, `headline`, `severity`, `urgency`,
|
||||
`certainty`, `status`, `message_type`, `category`, `response`, `description`,
|
||||
`instruction`, `sent`, `effective`, `onset`, `expires`, `area_description`,
|
||||
`sender_name`, and `run_event_id`.
|
||||
|
||||
### `alert_references`
|
||||
|
||||
`alert_index`, `reference_index`, `id`, `identifier`, `sender`, `sent`, and
|
||||
`run_event_id`.
|
||||
|
||||
### `forecasts`
|
||||
|
||||
`event_id`, `location_id`, `location_name`, `issued_at`, `updated_at`,
|
||||
`product`, `latitude`, `longitude`, `elevation_meters`, and
|
||||
`event_emitted_at`.
|
||||
|
||||
Only `product = 'hourly'` and `product = 'narrative'` are read by implemented
|
||||
routes.
|
||||
|
||||
### `forecast_periods`
|
||||
|
||||
`period_index`, `start_time`, `end_time`, `name`, `is_day`,
|
||||
`condition_code`, `text_description`, `temperature_c`, `temperature_c_min`,
|
||||
`temperature_c_max`, `dewpoint_c`, `relative_humidity_percent`,
|
||||
`wind_direction_degrees`, `wind_speed_kmh`, `wind_gust_kmh`,
|
||||
`barometric_pressure_pa`, `visibility_meters`, `apparent_temperature_c`,
|
||||
`cloud_cover_percent`, `probability_of_precipitation_percent`,
|
||||
`precipitation_amount_mm`, `snowfall_depth_mm`, `uv_index`, and
|
||||
`run_event_id`.
|
||||
|
||||
### `forecast_discussions`
|
||||
|
||||
`event_id`, `office_id`, `office_name`, `issued_at`, `updated_at`, `product`,
|
||||
`short_term_qualifier`, `short_term_issued_at`, `short_term_text`,
|
||||
`long_term_qualifier`, `long_term_issued_at`, `long_term_text`, and
|
||||
`event_emitted_at`.
|
||||
|
||||
### `forecast_discussion_key_messages`
|
||||
|
||||
`message_index`, `message_text`, and `run_event_id`.
|
||||
|
||||
### `weather_story_runs`
|
||||
|
||||
`event_id`, `office_id`, `as_of`, and `event_emitted_at`.
|
||||
|
||||
### `weather_stories`
|
||||
|
||||
`story_index`, `office_id`, `start_time`, `end_time`, `updated_at`, `title`,
|
||||
`description`, `alt_text`, `priority`, `story_order`, `download_url`,
|
||||
`run_event_id`, and `as_of`.
|
||||
|
||||
## Nullability and Time Assumptions
|
||||
|
||||
The repository scans nullable columns with `sql.Null*` types and maps them to
|
||||
nil pointers or omitted zero values depending on the canonical model field.
|
||||
|
||||
Timestamps returned by the repository are normalized to UTC. Presentation
|
||||
timezone conversion happens later in HTTP presenters.
|
||||
|
||||
Missing latest parent rows return `nil, nil` from repository methods. HTTP
|
||||
rendering exposes this as a successful response with `data: null`.
|
||||
|
||||
## Compatibility Checklist
|
||||
|
||||
Before changing weatherfeeder storage or upgrading the weatherfeeder module:
|
||||
|
||||
- compare table names and columns with `internal/adapters/outbound/postgres`;
|
||||
- preserve latest-row ordering columns used by `weatherapi`;
|
||||
- preserve child index columns used for ordering;
|
||||
- preserve nullable behavior expected by row mappers;
|
||||
- run `go test ./internal/adapters/outbound/postgres` and affected HTTP tests.
|
||||
|
||||
## Related Docs
|
||||
|
||||
- [`docs/internal/postgres-repository.md`](../internal/postgres-repository.md)
|
||||
- [`docs/operations.md`](../operations.md)
|
||||
Reference in New Issue
Block a user