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

- Development source is edited and committed on Windows; Docker builds and runtime testing are performed on Rocky.
- A production-like staging copy runs through Docker Compose on Rocky Linux at `http://192.168.1.101:9190`.
- Staging uses deterministic synthetic observations for the repository station set plus Valmiera, required by Faktiskā.
- Scheduled external-provider jobs are disabled in development and staging.
- PostgreSQL is private to the project Compose network; only the Scala application publishes a host port.
- UI modernization is in progress. City Analysis 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.
- The first **Ūdens temperatūra** workspace is implemented with manual Latvian-named fields and required 1920×1080 and 3840×1440 exports; visual calibration remains in progress.
- Confirmed local Monda Regular/Bold files provide interface and generated-graphic typography; weather symbols use normalized transparent image assets.
- Release `16a8c68` was built and checksummed on Rocky, transferred to the VPS, verified, and deployed as the immutable `weathertool:16a8c68` image. Release `7dbc55b` remains available for rollback.
- 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 database contains a deliberately limited 14-day, 34-city synthetic dataset for newsroom visual testing. It must be cleared before authorized real-provider ingestion begins.
- 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 of release `16a8c68` confirmed both fixed-map workspaces and the favicon. The shared UAT login is ready for the first newsroom-user handoff on 2026-08-21.
- Frontend dependency maintenance is complete through commit `de6f279`: 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. These commits are newer than the currently deployed VPS release `16a8c68`.
- 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) — Git workflow, local build, Rocky deployment, synthetic data, verification, 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.