WeatherTool/docs/PRODUCT_WORKFLOWS.md

# Product workflows

This document records the current understanding of the visible workspaces. It should be updated when workplace users clarify the real operational purpose.

## Operator language

Operator-facing workspace names, map names, export names, and production labels should use the established Latvian newsroom terminology. Development discussion and internal code may remain in English where useful, but that must not force English wording into the interface used by Latvian operators.

## Home

Entry point and navigation overview. It identifies the development dataset and links to each workspace.

## Stacijas

Purpose: inspect station-focused observations, map values, and open detailed charts for a selected station.

Current status: inherited workflow; still requires detailed workplace validation and UI review.

## Kartes

Purpose: compare historical observations across selected cities.

The operator chooses:

- cities;
- start and end time;
- weather field;
- aggregate key;
- granularity.

Results can be viewed as grid/list data or rendered into the familiar temperature-map formats. Weather-symbol authoring does not belong in this workflow.

## Faktiskā

Purpose: prepare the fixed daily **faktiskā laika ziņu karte**—the current-weather graphic used on air. The supplied production master images are the authoritative output specification, not visual inspiration.

The production template contains:

- the fixed title/source nameplate already present in the production artwork;
- the latest available temperature for each fixed station;
- weather conditions represented by normalized transparent image assets;
- manually entered wind direction, speed, and gust values;
- a fixed 3840×1440 PNG output.

Current operator flow:

1. Open Faktiskā; the fixed station set and latest `tempAvg` observations load automatically.
2. Review the observation timestamp, missing/stale indicators, and temperatures.
3. Override any temperature manually when editorial correction is required; reset restores the fetched value.
4. Enter wind values manually.
5. Select a weather symbol, apply it to all stations where appropriate, and adjust exceptions.
6. Review and download `faktiska-3840x1440.png`.

Fixed positions:

| Position | Station |
|---:|---|
| 0 | Liepāja |
| 1 | Ventspils |
| 2 | Stende (temporary substitute for Talsi) |
| 3 | Saldus |
| 4 | Rīga |
| 5 | Jelgava |
| 6 | Ainaži |
| 7 | Valmiera |
| 8 | Madona |
| 9 | Alūksne |
| 10 | Zīlāni (temporary substitute for Jēkabpils) |
| 11 | Daugavpils |
| 12 | Rēzekne |

The weather symbols are not automatically derived from the historical temperature query. They remain editorial/manual inputs until a reliable phenomena-data mapping is designed and validated.

Symbol selection is manual, but placement is automatic. Each Faktiskā position owns a fixed marker layout that attaches the selected normalized image to the actual rendered edge of its temperature badge. Operators do not position symbols for each export; per-station offsets can be refined centrally against the production master.

Completed Faktiskā checkpoint:

- fixed 13-position station set with no repeated city selection;
- automatic latest-temperature loading with observation time and stale/missing states;
- manual temperature correction and reset to the fetched value;
- manual wind direction, speed, and gust values;
- manual weather-symbol selection with apply-to-all and station exceptions;
- automatic badge-relative image placement using consistent 256×256 asset geometry;
- guarded 3840×1440 export using the fixed wind production artwork.

Confirmed Monda Regular/Bold files are now bundled and used. The export dimensions are locked, but final pixel-level placement must still be compared against the production masters after the font change. As of 2026-08-23 the 12 other fixed positions load real station data; Valmiera has no matching real open-data station yet, so it currently still shows the last synthetic row generated before synthetic data generation was stopped (increasingly stale, since nothing refreshes it). Once the old synthetic rows are wiped from `weather` (a still-pending step — see `docs/UPDATE_ROADMAP.md` Phase 7), Valmiera will show no data until a real source is found.

## Ūdens

Purpose: prepare the fixed water-temperature newsroom map as a separate production workflow. It must not be mixed into Faktiskā or Kartes.

Authoritative references:

- `UDENS_TEMPERATURA.png` defines the finished on-air composition;
- `UDENS_TEMP_NOSAUKUMI.png` defines the operator-facing names of the water areas/fields.

Required behavior:

1. Open the dedicated **Ūdens** workspace.
2. The six Latvian-named water-temperature fields auto-populate on load with the real current min/max for each zone (as of 2026-08-23), fetched from LVĢMC's open hydrological data — no manual entry needed for a normal, working day.
3. Any field can still be corrected manually if needed; editing a zone marks it "Manuāli" and an "Atiestatīt" button restores the fetched value. An "Atjaunot datus" action re-fetches all six.
4. Place values automatically at their locked production positions.
5. Preview and download either a 1920×1080 or 3840×1440 PNG.

The 1920×1080 and 3840×1440 products are independent authoritative canvases. Neither is derived by resizing or reflowing the other. Each template contains the fixed newsroom artwork and six separately measured value rectangles.

The renderer uses canvas `TextMetrics` visible-glyph bounds (`actualBoundingBoxLeft`, `actualBoundingBoxRight`, `actualBoundingBoxAscent`, and `actualBoundingBoxDescent`) to optically center Monda text inside each rectangle. The browser preview scales the complete canvas only; downloaded PNGs retain their native dimensions.

Implementation status: both native exports are implemented and visually validated against the supplied production templates. Later newsroom feedback can still tune the per-template rectangles without changing the auto-load/manual-override workflow.

## Brīdinājumi

Purpose: prepare a newsroom map from the current LVĢMC open hydrometeorological-warning dataset without tracing warning areas manually. The operator checks as many or as few warnings as should appear together on one export; newsroom practice is to combine multiple severity levels of the *same kind* of warning (e.g. a yellow and an orange wind warning) but never different phenomena (e.g. wind and rain) on one map — the tool does not currently enforce that boundary, so keeping selections to one phenomenon at a time is an operator responsibility.

Operator flow:

1. Open **Brīdinājumi**; warning metadata and ordered polygon coordinates load through the WeatherTool backend.
2. Select the independent 1920×1080 or 3840×1440 production canvas.
3. Optionally narrow the warning list by day and phenomenon.
4. Each warning card has its own checkbox and is independently clickable. The checkbox adds or removes that warning from the map (any number can be checked at once; at least one is auto-checked so the map is never empty). Clicking the card itself opens that warning's full detail — intensity, regions, validity period, description, and risk text — in a popup dialog above a dimmed, blurred background, without changing the map selection. Closing the popup (✕, backdrop click, or Escape) leaves the selection untouched.
5. The title field is pre-filled as "Brīdinājums: {phenomenon}" (e.g. "Brīdinājums: vējš") from the first checked warning and remains manually editable — useful since a combined-severity selection needs one title regardless of how many checkboxes are on; the LVĢMC source mark stays fixed.
6. For each checked warning, pick a weather symbol from the shared palette (the same symbol set used across Faktiskā and, historically, the Photoshop workflow) and assign it to that warning. On the map preview, drag the symbol to reposition it and drag its corner handle to resize it — placement and size are editorial judgment calls that reflect where and how intense a given warning is, the same way the newsroom has always hand-placed a symbol over the colored area in Photoshop.
7. Preview and download the native-resolution PNG.

The two exports use separate geographic-to-pixel calibration and layout values. Neither output is produced by resizing the other. Upstream times are interpreted in the `Europe/Riga` timezone. Empty warning data is a valid state and produces an uncolored base map. There is no on-canvas severity-color legend. Each warning card is a compact chip showing only its phenomenon icon, name, and severity color (left border); the full text lives in the detail popup so it stays readable regardless of length. Symbol placement and size are stored per warning as fractions of the canvas, so the same relative placement holds at both export resolutions; the drag/resize handles are a preview-only aid and are never present in the downloaded PNG.

## Apskats

Purpose: aggregate selected fields across Latvia for a selected time range.

Current status: inherited workflow; terminology, units, and workplace use still need validation.

## Arhīvs

Purpose: inspect available database dates and individual stored records/files.

Current status: inherited technical/administrative workflow. Access control and export correctness require review before production use.

## Harmonie

Purpose: inspect and render forecast-model GRIB fields.

Development limitation: no representative HARMONIE GRIB fixtures are currently included, and valid external-provider access is not configured in staging.

## LVĢMC

Purpose: display prepared LVGMC forecast products and broadcast tables.

Development limitation: representative forecast CSV fixtures are not currently included, and valid external-provider access is not configured in staging.

## Decisions still required

- Whether weather conditions can eventually be populated automatically and which provider field is authoritative.
- Whether Stende and Zīlāni remain the production feeds after users test real provider data.
- Confirm how Valmiera is named and sourced when authorized provider data is available.
- Apply the same native-resolution production comparison to additional broadcast products as they are finalized.
- Required authentication and role separation for analytical, production, and administrative workspaces.