b0txec
107 lines
5.8 KiB
Markdown
107 lines
5.8 KiB
Markdown
# Architecture and data flow
|
||
|
||
## System overview
|
||
|
||
WeatherTool is a Scala backend, SolidJS frontend, and PostgreSQL database used to inspect Latvian weather observations and prepare map-based newsroom graphics.
|
||
|
||
```text
|
||
External providers Local/staging workflow
|
||
LVGMC station FTP/CSV ----+ Synthetic SQL seed
|
||
LVGMC forecast CSV -------+ |
|
||
DMI HARMONIE APIs --------+ v
|
||
v PostgreSQL
|
||
Scala ingestion |
|
||
| |
|
||
+---------> Scala/http4s API
|
||
|
|
||
v
|
||
SolidJS web UI
|
||
|
|
||
v
|
||
Canvas preview and PNG export
|
||
```
|
||
|
||
Staging currently exercises the PostgreSQL → API → frontend path with synthetic observations. It does not emulate LVGMC forecast files or HARMONIE GRIB files.
|
||
|
||
## Components
|
||
|
||
### Scala backend
|
||
|
||
- Serves JSON API routes and the built frontend from `web/dist`.
|
||
- Queries and aggregates station observations in PostgreSQL.
|
||
- Contains ingestion/parsing code for LVGMC station and forecast data.
|
||
- Contains HARMONIE discovery, download, GRIB parsing, and rendering support.
|
||
- Starts scheduled ingestion/cleanup tasks unless `ENABLE_SCHEDULED_JOBS=false`.
|
||
|
||
### SolidJS frontend
|
||
|
||
- Queries the backend using the same origin in production builds.
|
||
- Provides Stations, City Analysis, Faktiskā, Ūdens temperatūra, Latvia overview, Database, HARMONIE, and LVGMC forecast workspaces.
|
||
- Uses HTML canvas for broadcast maps and PNG export.
|
||
- Uses normalized transparent PNG assets for weather symbols; the internal letter codes remain stable identifiers and are not rendered as text or emoji.
|
||
|
||
### PostgreSQL
|
||
|
||
- Stores normalized weather observations used by Stations, City Analysis, Faktiskā, and Latvia overview.
|
||
- Is accessible only inside the isolated Compose network in staging.
|
||
- Uses a bind-mounted `postgres/` runtime directory in the current Compose configuration.
|
||
|
||
## Main observation-data flow
|
||
|
||
1. An ingestion job parses provider station data, or the development seed inserts synthetic rows.
|
||
2. Observations are stored in the `weather` table.
|
||
3. The frontend requests an API route containing cities, time range, granularity, field, and aggregate key.
|
||
4. The backend performs the database query and returns JSON.
|
||
5. The frontend renders cards, lists, charts, or canvas graphics.
|
||
6. Broadcast maps can be downloaded as PNG files entirely in the browser.
|
||
|
||
## Broadcast-map flow
|
||
|
||
### City Analysis temperature maps
|
||
|
||
Queried city values are placed at predefined coordinates on one of four map backgrounds:
|
||
|
||
- `map_1920x1080`
|
||
- `map_1920x1080_wind`
|
||
- `map_3840x1440`
|
||
- `map_3840x1440_wind`
|
||
|
||
The operator can add title/source overlays and export the rendered canvas.
|
||
|
||
### Faktiskā
|
||
|
||
Faktiskā has a fixed 13-position station configuration. On page entry the frontend calls `/api/query/latest-temperatures/<cities>`. The backend selects the newest row per requested city and returns `tempAvg`, the station name, and its observation timestamp. The UI highlights missing or older observations and permits an explicit manual override without changing the stored observation.
|
||
|
||
Weather symbols and wind values remain manual editorial inputs. One symbol can be applied to all fixed stations and exceptions changed individually. The browser composes these values on the fixed wind-template canvas and exports exactly 3840×1440 pixels. The production master images define the required output geometry; final Monda pixel-level comparison remains pending.
|
||
|
||
The renderer attaches each normalized 256×256 weather image to the measured edge of its temperature badge. All assets share one canvas, center, and scale, so placement does not depend on font bearings or baselines. The configuration permits per-station offsets when later production comparison requires them. Operator input selects the symbol but never controls its coordinates.
|
||
|
||
### Ūdens temperatūra
|
||
|
||
Ūdens temperatūra is an independent fixed-template renderer. Its six ranges are currently manual editorial inputs rather than station-query results. A Latvian-named field configuration maps each water area to locked canvas coordinates. The workflow produces explicit 1920×1080 and 3840×1440 canvases and filenames; each size still requires comparison against newsroom output.
|
||
|
||
Monda Regular and Bold are bundled locally and used by the interface and generated text. Weather symbols are bundled as independent transparent PNG assets.
|
||
|
||
## What the repository does not provide by itself
|
||
|
||
- Authorized provider accounts and credentials.
|
||
- Workplace deployment topology or authentication requirements.
|
||
- Real LVGMC forecast CSV fixtures for development.
|
||
- Real HARMONIE GRIB fixtures for development.
|
||
- A complete automated test suite.
|
||
- Production monitoring, backups, incident handling, or a reviewed security boundary.
|
||
|
||
See `UPDATE_ROADMAP.md` before considering workplace deployment.
|
||
|
||
## Proposed temporary public-testing edge
|
||
|
||
WeatherTool has not yet been deployed publicly. The proposed month-long user-acceptance environment adds a removable edge layer without changing the application into the authentication authority:
|
||
|
||
```text
|
||
Cloudflare -> VPS Nginx -> Authelia authorization -> WeatherTool -> PostgreSQL
|
||
```
|
||
|
||
Rocky remains the trusted build and verification host. The VPS receives a commit-addressed immutable image and release metadata rather than pulling and building the development repository. WeatherTool, its database, and Authelia must use a dedicated Compose project, private network, storage paths, and loopback-only upstream port so the existing VPS services remain untouched.
|
||
|
||
See `VPS_STAGING_PLAN.md` for the proposed topology and release procedure.
|