WeatherTool/docs/README.md

# WeatherTool project documentation

This directory contains the working documentation for the WeatherTool modernization effort. The repository-root `README.md` is preserved as the original project overview; these documents describe the reviewed code, current staging environment, and changes being developed.

## Current status

- Windows is restricted to source editing, review, and Git operations. Rocky is the sole compile, build, development-runtime, and test environment. The Ubuntu VPS is a deployment target only.
- A production-like staging copy runs through Docker Compose on Rocky Linux at `http://192.168.1.101:9190`.
- Staging ingests real LVĢMC station and water-temperature observations from the free `data.gov.lv` open-data feeds; synthetic data generation was removed once real ingestion was verified. The private LVGMC FTP feed and DMI HARMONIE forecast feed still exist in code but stay gated behind `ENABLE_LEGACY_PROVIDER_JOBS` (default off) pending real credentials.
- The safe scheduled jobs (open-data station ingestion, GRIB cleanup) run in staging; the legacy FTP/HARMONIE jobs stay off by default so placeholder credentials can't crash-loop the app.
- PostgreSQL is private to the project Compose network; only the Scala application publishes a host port.
- The operator-facing workspaces now use the Latvian workflow names **Stacijas**, **Kartes**, **Faktiskā**, **Ūdens**, **Brīdinājumi**, **Apskats**, **Arhīvs**, **Harmonie**, and **LVĢMC**. Kartes retains custom analytical map outputs, while Faktiskā is a fixed 13-position, latest-temperature newsroom workflow with a locked 3840×1440 export.
- Faktiskā symbol placement is automatic after manual image selection and is anchored to each rendered temperature badge.
- **Ūdens** auto-populates its six ranges on load with real per-zone water-temperature min/max (65 LVĢMC stations classified into the 6 named zones), with manual override and reset still available. Uses separate authoritative 1920×1080 and 3840×1440 production templates; both exports have been visually validated.
- **Brīdinājumi** renders current LVĢMC warning polygons over a production border overlay with feathered severity fills, plus draggable/resizable per-warning weather-symbol placement. Its lon/lat-to-pixel projection is an affine fit calibrated against the same validated city pixel positions Kartes/Faktiskā already use, replacing an earlier bounding-box calibration that drifted up to ~200px on the 3840 canvas.
- Confirmed local Monda Regular/Bold files provide interface and generated-graphic typography; weather symbols use normalized transparent image assets.
- Release `138f57c8` is deployed as immutable image `weathertool:138f57c808631dc17396b22ac0305b670fbcf776`; release `6185dbf` remains the immediate application rollback. This is the full go-live release: real open-data station and water-temperature ingestion, the scheduler safety split (`ENABLE_SCHEDULED_JOBS` vs. `ENABLE_LEGACY_PROVIDER_JOBS`), synthetic-data-generation removal, the dead `METEO_*` path deleted, draggable Brīdinājumi symbol placement, and real per-zone water-temperature ranges — on top of the hardened LVĢMC warning fetching, full Brīdinājumi workspace, JSON API, and Latvian workflow labels already live in `6185dbf`.
- The isolated VPS UAT stack is running and healthy: WeatherTool is bound to `127.0.0.1:8002`, Authelia to `127.0.0.1:9091`, and PostgreSQL has no host port. Public access is routed through Cloudflare, Nginx, and Authelia.
- Cloudflare delegation is active, strict origin TLS covers only `laikapstak.li` and `auth.laikapstak.li`, and the public Nginx/Authelia login flow is operational without changing the existing HOP site.
- The VPS `weather` table now holds only real LVĢMC open-data station observations; its original 14-day synthetic dataset was backed up to `/srv/weathertool/backups/pre-real-data-release/` and wiped on 2026-08-23 as part of the `138f57c8` release. The scheduled open-data job runs on the VPS (minutes 15/45); the legacy FTP/HARMONIE jobs stay off pending real credentials.
- Approved 1920×1080 and 3840×1440 PNG production bases are now the rendering source for Faktiskā and Ūdens temperatūra; code draws only the changing values, selected weather symbols, and wind data over those fixed newsroom graphics.
- Browser branding assets and Latvian Open Graph/Twitter metadata are included for favicon, Apple home-screen icon, and link-preview support. Public crawler access still depends on the Nginx/Authelia policy used for the metadata and preview image.
- Browser verification is complete for the deployed `138f57c8` release: exact release image smoke-tested on Rocky before transfer, VPS PostgreSQL backed up before the synthetic-data wipe, checksum verified on both ends, container health/loopback/public HTTPS confirmed, and the scheduled open-data job observed firing and landing 1,577 real rows within ~2 minutes of the deploy. Newsroom testers will be given the domain first, without walkthrough, to see how intuitive the workflow is before any guidance is provided.
- Frontend dependency maintenance is complete: Solid runtime and Vite tooling were updated, obsolete packages were removed, TypeScript checking was added, and a clean Rocky `npm ci`, typecheck, production build, full audit, and production-only audit all pass with zero known vulnerabilities.
- This is not yet approved or hardened for workplace production.

## Documents

- [Architecture and data flow](ARCHITECTURE.md) — components, data sources, data flow, and repository layout.
- [Development and staging](DEVELOPMENT_AND_STAGING.md) — Windows source/Git workflow, Rocky development and verification, VPS deployment, synthetic data, and rollback.
- [Product workflows](PRODUCT_WORKFLOWS.md) — the intended purpose and current status of each visible workspace.
- [Update roadmap](UPDATE_ROADMAP.md) — phased technical, security, dependency, testing, and UI work.
- [Third-party notices](THIRD_PARTY_NOTICES.md) — licenses and attribution for adapted interface components.
- [Temporary VPS staging plan](VPS_STAGING_PLAN.md) — isolation, authentication, prepared deployment bundle, release, backup, verification, and rollback model for external user testing.

## Documentation rules

1. Do not put passwords, API keys, workplace URLs, or production data in Git.
2. Document the behavior that exists separately from behavior that is proposed.
3. Update these documents in the same commit when a change alters deployment, data flow, or a user workflow.
4. Keep synthetic/development instructions clearly distinguished from workplace production procedures.
5. Preserve established Latvian names in operator-facing workspaces and production files even when development notes are written in English.