Document development workflow and internals

docs/internal/normalizers.md

@@ -0,0 +1,90 @@
+# Normalizer Internals
+
+## Purpose
+
+Normalizers convert raw provider events into canonical weather events. They are
+weather-domain mapping code and should stay independent of runtime wiring,
+source polling, and sink persistence.
+
+Detailed package conventions live in `internal/normalizers/doc.go`.
+
+## Inputs And Outputs
+
+Inputs are raw feed events whose schemas identify provider payload shape.
+Outputs are canonical feed events using `model` payloads and `weather.*`
+schemas.
+
+Current mappings:
+
+| Raw schema | Canonical schema |
+| --- | --- |
+| `raw.nws.observation.v1` | `weather.observation.v1` |
+| `raw.openmeteo.current.v1` | `weather.observation.v1` |
+| `raw.openweather.current.v1` | `weather.observation.v1` |
+| `raw.nws.hourly.forecast.v1` | `weather.forecast.v1` |
+| `raw.nws.narrative.forecast.v1` | `weather.forecast.v1` |
+| `raw.openmeteo.hourly.forecast.v1` | `weather.forecast.v1` |
+| `raw.nws.forecast_discussion.v1` | `weather.forecast_discussion.v1` |
+| `raw.nws.weatherstories.v1` | `weather.weather_story.v1` |
+| `raw.nws.alerts.v1` | `weather.alert.v1` |
+
+## Boundaries
+
+- Normalizers match by `Event.Schema`.
+- Normalizers decode raw payloads into provider structs.
+- Normalizers map provider data into canonical `model` payloads.
+- Normalizers do not fetch network data, read config, route events, or write
+  sinks.
+- Shared cross-provider behavior belongs in `internal/normalizers/common`.
+- Provider-specific helper logic shared with sources belongs in
+  `internal/providers/<provider>`.
+
+## Config Fields Used
+
+Normalizers do not read config. They operate only on incoming events.
+
+## External Adapters Used
+
+Runtime composition creates feedkit's normalize processor with
+`RequireMatch=false`. Events without a matching normalizer pass through
+unchanged.
+
+Weatherfeeder registers normalizers in a stable order:
+
+1. NWS
+2. Open-Meteo
+3. OpenWeather
+
+The current normalizers avoid ambiguous matches by using schema equality.
+
+## State
+
+Normalizers should be stateless. Shared helpers should be deterministic and free
+of I/O.
+
+## Failure Behavior
+
+Malformed required raw payload data should produce contextual errors from the
+owning normalizer. Successful normalization validates the output event before it
+continues through the pipeline.
+
+`internal/normalizers/common.Finalize` preserves the input event envelope except
+for schema, payload, and effective time. It also rounds canonical float values
+to four digits after the decimal point.
+
+## Tests To Inspect
+
+- `internal/normalizers/builtins_test.go`
+- provider normalizer tests under `internal/normalizers/nws`
+- provider normalizer tests under `internal/normalizers/openmeteo`
+- provider normalizer tests under `internal/normalizers/openweather`
+- common helper tests under `internal/normalizers/common`
+
+## Invariants
+
+- Match by schema constants from `standards`.
+- Preserve the event envelope except for intentional canonical changes.
+- Produce canonical payload structs from `model`.
+- Validate normalized events before returning them.
+- Keep normalizers independent of sources, sinks, config loading, and runtime
+  composition.